From 454e6afd89d77c1005eae4838e74e82fae759668 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Felix=20D=C3=B6rre?= Date: Thu, 19 Jun 2014 19:21:23 +0200 Subject: [PATCH] adding servlet api (from tomcat) --- .classpath | 1 + .../javax/servlet/AsyncContext.java | 83 ++ lib/servlet-api/javax/servlet/AsyncEvent.java | 74 ++ .../javax/servlet/AsyncListener.java | 31 + .../javax/servlet/DispatcherType.java | 28 + lib/servlet-api/javax/servlet/Filter.java | 100 ++ .../javax/servlet/FilterChain.java | 49 + .../javax/servlet/FilterConfig.java | 73 ++ .../javax/servlet/FilterRegistration.java | 67 ++ .../javax/servlet/GenericServlet.java | 238 +++++ .../javax/servlet/HttpConstraintElement.java | 98 ++ .../servlet/HttpMethodConstraintElement.java | 57 ++ .../javax/servlet/LocalStrings.properties | 24 + .../javax/servlet/LocalStrings_es.properties | 19 + .../javax/servlet/LocalStrings_fr.properties | 23 + .../javax/servlet/LocalStrings_ja.properties | 21 + .../javax/servlet/MultipartConfigElement.java | 79 ++ .../javax/servlet/ReadListener.java | 52 + .../javax/servlet/Registration.java | 64 ++ .../javax/servlet/RequestDispatcher.java | 293 ++++++ lib/servlet-api/javax/servlet/Servlet.java | 178 ++++ .../javax/servlet/ServletConfig.java | 69 ++ .../servlet/ServletContainerInitializer.java | 53 ++ .../javax/servlet/ServletContext.java | 895 ++++++++++++++++++ .../servlet/ServletContextAttributeEvent.java | 59 ++ .../ServletContextAttributeListener.java | 49 + .../javax/servlet/ServletContextEvent.java | 48 + .../javax/servlet/ServletContextListener.java | 46 + .../javax/servlet/ServletException.java | 91 ++ .../javax/servlet/ServletInputStream.java | 117 +++ .../javax/servlet/ServletOutputStream.java | 302 ++++++ .../javax/servlet/ServletRegistration.java | 49 + .../javax/servlet/ServletRequest.java | 492 ++++++++++ .../servlet/ServletRequestAttributeEvent.java | 73 ++ .../ServletRequestAttributeListener.java | 50 + .../javax/servlet/ServletRequestEvent.java | 58 ++ .../javax/servlet/ServletRequestListener.java | 40 + .../javax/servlet/ServletRequestWrapper.java | 458 +++++++++ .../javax/servlet/ServletResponse.java | 342 +++++++ .../javax/servlet/ServletResponseWrapper.java | 244 +++++ .../javax/servlet/ServletSecurityElement.java | 135 +++ .../javax/servlet/SessionCookieConfig.java | 90 ++ .../javax/servlet/SessionTrackingMode.java | 26 + .../javax/servlet/SingleThreadModel.java | 44 + .../javax/servlet/UnavailableException.java | 178 ++++ .../javax/servlet/WriteListener.java | 45 + .../servlet/annotation/HandlesTypes.java | 39 + .../servlet/annotation/HttpConstraint.java | 69 ++ .../annotation/HttpMethodConstraint.java | 74 ++ .../servlet/annotation/MultipartConfig.java | 68 ++ .../servlet/annotation/ServletSecurity.java | 90 ++ .../javax/servlet/annotation/WebFilter.java | 122 +++ .../servlet/annotation/WebInitParam.java | 57 ++ .../javax/servlet/annotation/WebListener.java | 54 ++ .../javax/servlet/annotation/WebServlet.java | 113 +++ .../descriptor/JspConfigDescriptor.java | 28 + .../JspPropertyGroupDescriptor.java | 38 + .../servlet/descriptor/TaglibDescriptor.java | 26 + .../javax/servlet/http/Cookie.java | 458 +++++++++ .../javax/servlet/http/HttpServlet.java | 881 +++++++++++++++++ .../servlet/http/HttpServletRequest.java | 522 ++++++++++ .../http/HttpServletRequestWrapper.java | 376 ++++++++ .../servlet/http/HttpServletResponse.java | 597 ++++++++++++ .../http/HttpServletResponseWrapper.java | 270 ++++++ .../javax/servlet/http/HttpSession.java | 284 ++++++ .../http/HttpSessionActivationListener.java | 37 + .../http/HttpSessionAttributeListener.java | 46 + .../servlet/http/HttpSessionBindingEvent.java | 111 +++ .../http/HttpSessionBindingListener.java | 53 ++ .../servlet/http/HttpSessionContext.java | 49 + .../javax/servlet/http/HttpSessionEvent.java | 37 + .../servlet/http/HttpSessionIdListener.java | 41 + .../servlet/http/HttpSessionListener.java | 48 + .../servlet/http/HttpUpgradeHandler.java | 42 + .../javax/servlet/http/HttpUtils.java | 282 ++++++ .../servlet/http/LocalStrings.properties | 30 + .../servlet/http/LocalStrings_es.properties | 23 + .../servlet/http/LocalStrings_fr.properties | 28 + .../servlet/http/LocalStrings_ja.properties | 28 + lib/servlet-api/javax/servlet/http/Part.java | 118 +++ .../javax/servlet/http/WebConnection.java | 43 + .../javax/servlet/http/package.html | 30 + lib/servlet-api/javax/servlet/package.html | 30 + 83 files changed, 10947 insertions(+) create mode 100644 lib/servlet-api/javax/servlet/AsyncContext.java create mode 100644 lib/servlet-api/javax/servlet/AsyncEvent.java create mode 100644 lib/servlet-api/javax/servlet/AsyncListener.java create mode 100644 lib/servlet-api/javax/servlet/DispatcherType.java create mode 100644 lib/servlet-api/javax/servlet/Filter.java create mode 100644 lib/servlet-api/javax/servlet/FilterChain.java create mode 100644 lib/servlet-api/javax/servlet/FilterConfig.java create mode 100644 lib/servlet-api/javax/servlet/FilterRegistration.java create mode 100644 lib/servlet-api/javax/servlet/GenericServlet.java create mode 100644 lib/servlet-api/javax/servlet/HttpConstraintElement.java create mode 100644 lib/servlet-api/javax/servlet/HttpMethodConstraintElement.java create mode 100644 lib/servlet-api/javax/servlet/LocalStrings.properties create mode 100644 lib/servlet-api/javax/servlet/LocalStrings_es.properties create mode 100644 lib/servlet-api/javax/servlet/LocalStrings_fr.properties create mode 100644 lib/servlet-api/javax/servlet/LocalStrings_ja.properties create mode 100644 lib/servlet-api/javax/servlet/MultipartConfigElement.java create mode 100644 lib/servlet-api/javax/servlet/ReadListener.java create mode 100644 lib/servlet-api/javax/servlet/Registration.java create mode 100644 lib/servlet-api/javax/servlet/RequestDispatcher.java create mode 100644 lib/servlet-api/javax/servlet/Servlet.java create mode 100644 lib/servlet-api/javax/servlet/ServletConfig.java create mode 100644 lib/servlet-api/javax/servlet/ServletContainerInitializer.java create mode 100644 lib/servlet-api/javax/servlet/ServletContext.java create mode 100644 lib/servlet-api/javax/servlet/ServletContextAttributeEvent.java create mode 100644 lib/servlet-api/javax/servlet/ServletContextAttributeListener.java create mode 100644 lib/servlet-api/javax/servlet/ServletContextEvent.java create mode 100644 lib/servlet-api/javax/servlet/ServletContextListener.java create mode 100644 lib/servlet-api/javax/servlet/ServletException.java create mode 100644 lib/servlet-api/javax/servlet/ServletInputStream.java create mode 100644 lib/servlet-api/javax/servlet/ServletOutputStream.java create mode 100644 lib/servlet-api/javax/servlet/ServletRegistration.java create mode 100644 lib/servlet-api/javax/servlet/ServletRequest.java create mode 100644 lib/servlet-api/javax/servlet/ServletRequestAttributeEvent.java create mode 100644 lib/servlet-api/javax/servlet/ServletRequestAttributeListener.java create mode 100644 lib/servlet-api/javax/servlet/ServletRequestEvent.java create mode 100644 lib/servlet-api/javax/servlet/ServletRequestListener.java create mode 100644 lib/servlet-api/javax/servlet/ServletRequestWrapper.java create mode 100644 lib/servlet-api/javax/servlet/ServletResponse.java create mode 100644 lib/servlet-api/javax/servlet/ServletResponseWrapper.java create mode 100644 lib/servlet-api/javax/servlet/ServletSecurityElement.java create mode 100644 lib/servlet-api/javax/servlet/SessionCookieConfig.java create mode 100644 lib/servlet-api/javax/servlet/SessionTrackingMode.java create mode 100644 lib/servlet-api/javax/servlet/SingleThreadModel.java create mode 100644 lib/servlet-api/javax/servlet/UnavailableException.java create mode 100644 lib/servlet-api/javax/servlet/WriteListener.java create mode 100644 lib/servlet-api/javax/servlet/annotation/HandlesTypes.java create mode 100644 lib/servlet-api/javax/servlet/annotation/HttpConstraint.java create mode 100644 lib/servlet-api/javax/servlet/annotation/HttpMethodConstraint.java create mode 100644 lib/servlet-api/javax/servlet/annotation/MultipartConfig.java create mode 100644 lib/servlet-api/javax/servlet/annotation/ServletSecurity.java create mode 100644 lib/servlet-api/javax/servlet/annotation/WebFilter.java create mode 100644 lib/servlet-api/javax/servlet/annotation/WebInitParam.java create mode 100644 lib/servlet-api/javax/servlet/annotation/WebListener.java create mode 100644 lib/servlet-api/javax/servlet/annotation/WebServlet.java create mode 100644 lib/servlet-api/javax/servlet/descriptor/JspConfigDescriptor.java create mode 100644 lib/servlet-api/javax/servlet/descriptor/JspPropertyGroupDescriptor.java create mode 100644 lib/servlet-api/javax/servlet/descriptor/TaglibDescriptor.java create mode 100644 lib/servlet-api/javax/servlet/http/Cookie.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpServlet.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpServletRequest.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpServletRequestWrapper.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpServletResponse.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpServletResponseWrapper.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSession.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionActivationListener.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionAttributeListener.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionBindingEvent.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionBindingListener.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionContext.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionEvent.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionIdListener.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpSessionListener.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpUpgradeHandler.java create mode 100644 lib/servlet-api/javax/servlet/http/HttpUtils.java create mode 100644 lib/servlet-api/javax/servlet/http/LocalStrings.properties create mode 100644 lib/servlet-api/javax/servlet/http/LocalStrings_es.properties create mode 100644 lib/servlet-api/javax/servlet/http/LocalStrings_fr.properties create mode 100644 lib/servlet-api/javax/servlet/http/LocalStrings_ja.properties create mode 100644 lib/servlet-api/javax/servlet/http/Part.java create mode 100644 lib/servlet-api/javax/servlet/http/WebConnection.java create mode 100644 lib/servlet-api/javax/servlet/http/package.html create mode 100644 lib/servlet-api/javax/servlet/package.html diff --git a/.classpath b/.classpath index fb501163..342147de 100644 --- a/.classpath +++ b/.classpath @@ -1,6 +1,7 @@ + diff --git a/lib/servlet-api/javax/servlet/AsyncContext.java b/lib/servlet-api/javax/servlet/AsyncContext.java new file mode 100644 index 00000000..bc2267eb --- /dev/null +++ b/lib/servlet-api/javax/servlet/AsyncContext.java @@ -0,0 +1,83 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +/** + * TODO SERVLET3 - Add comments + * @since Servlet 3.0 + */ +public interface AsyncContext { + public static final String ASYNC_REQUEST_URI = + "javax.servlet.async.request_uri"; + public static final String ASYNC_CONTEXT_PATH = + "javax.servlet.async.context_path"; + public static final String ASYNC_PATH_INFO = + "javax.servlet.async.path_info"; + public static final String ASYNC_SERVLET_PATH = + "javax.servlet.async.servlet_path"; + public static final String ASYNC_QUERY_STRING = + "javax.servlet.async.query_string"; + + ServletRequest getRequest(); + + ServletResponse getResponse(); + + boolean hasOriginalRequestAndResponse(); + + /** + * + * @throws IllegalStateException + */ + void dispatch(); + + /** + * + * @param path + * @throws IllegalStateException + */ + void dispatch(String path); + + /** + * + * @param context + * @param path + * @throws IllegalStateException + */ + void dispatch(ServletContext context, String path); + + void complete(); + + void start(Runnable run); + + void addListener(AsyncListener listener); + + void addListener(AsyncListener listener, ServletRequest request, + ServletResponse response); + + T createListener(Class clazz) + throws ServletException; + + /** + * Set timeout in milliseconds. 0 or less indicates no timeout. + */ + void setTimeout(long timeout); + + /** + * Get timeout in milliseconds. 0 or less indicates no timeout. + */ + long getTimeout(); +} diff --git a/lib/servlet-api/javax/servlet/AsyncEvent.java b/lib/servlet-api/javax/servlet/AsyncEvent.java new file mode 100644 index 00000000..4b0f0b38 --- /dev/null +++ b/lib/servlet-api/javax/servlet/AsyncEvent.java @@ -0,0 +1,74 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +/** + * TODO SERVLET3 - Add comments + * @since Servlet 3.0 + */ +public class AsyncEvent { + private final AsyncContext context; + private final ServletRequest request; + private final ServletResponse response; + private final Throwable throwable; + + public AsyncEvent(AsyncContext context) { + this.context = context; + this.request = null; + this.response = null; + this.throwable = null; + } + + public AsyncEvent(AsyncContext context, ServletRequest request, + ServletResponse response) { + this.context = context; + this.request = request; + this.response = response; + this.throwable = null; + } + + public AsyncEvent(AsyncContext context, Throwable throwable) { + this.context = context; + this.throwable = throwable; + this.request = null; + this.response = null; + } + + public AsyncEvent(AsyncContext context, ServletRequest request, + ServletResponse response, Throwable throwable) { + this.context = context; + this.request = request; + this.response = response; + this.throwable = throwable; + } + + public AsyncContext getAsyncContext() { + return context; + } + + public ServletRequest getSuppliedRequest() { + return request; + } + + public ServletResponse getSuppliedResponse() { + return response; + } + + public Throwable getThrowable() { + return throwable; + } +} diff --git a/lib/servlet-api/javax/servlet/AsyncListener.java b/lib/servlet-api/javax/servlet/AsyncListener.java new file mode 100644 index 00000000..66f6392d --- /dev/null +++ b/lib/servlet-api/javax/servlet/AsyncListener.java @@ -0,0 +1,31 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.io.IOException; +import java.util.EventListener; + +/** + * TODO SERVLET3 - Add comments + * @since Servlet 3.0 + */ +public interface AsyncListener extends EventListener { + void onComplete(AsyncEvent event) throws IOException; + void onTimeout(AsyncEvent event) throws IOException; + void onError(AsyncEvent event) throws IOException; + void onStartAsync(AsyncEvent event) throws IOException; +} diff --git a/lib/servlet-api/javax/servlet/DispatcherType.java b/lib/servlet-api/javax/servlet/DispatcherType.java new file mode 100644 index 00000000..67e56030 --- /dev/null +++ b/lib/servlet-api/javax/servlet/DispatcherType.java @@ -0,0 +1,28 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +/** + * @since Servlet 3.0 + */ +public enum DispatcherType { + FORWARD, + INCLUDE, + REQUEST, + ASYNC, + ERROR +} diff --git a/lib/servlet-api/javax/servlet/Filter.java b/lib/servlet-api/javax/servlet/Filter.java new file mode 100644 index 00000000..b36b37d8 --- /dev/null +++ b/lib/servlet-api/javax/servlet/Filter.java @@ -0,0 +1,100 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; + +/** + * A filter is an object that performs filtering tasks on either the request to + * a resource (a servlet or static content), or on the response from a resource, + * or both.
+ *
+ * Filters perform filtering in the doFilter method. Every Filter + * has access to a FilterConfig object from which it can obtain its + * initialization parameters, a reference to the ServletContext which it can + * use, for example, to load resources needed for filtering tasks. + *

+ * Filters are configured in the deployment descriptor of a web application + *

+ * Examples that have been identified for this design are
+ * 1) Authentication Filters
+ * 2) Logging and Auditing Filters
+ * 3) Image conversion Filters
+ * 4) Data compression Filters
+ * 5) Encryption Filters
+ * 6) Tokenizing Filters
+ * 7) Filters that trigger resource access events
+ * 8) XSL/T filters
+ * 9) Mime-type chain Filter
+ * + * @since Servlet 2.3 + */ +public interface Filter { + + /** + * Called by the web container to indicate to a filter that it is being + * placed into service. The servlet container calls the init method exactly + * once after instantiating the filter. The init method must complete + * successfully before the filter is asked to do any filtering work.
+ *
+ * The web container cannot place the filter into service if the init method + * either
+ * 1.Throws a ServletException
+ * 2.Does not return within a time period defined by the web container + */ + public void init(FilterConfig filterConfig) throws ServletException; + + /** + * The doFilter method of the Filter is called by the container + * each time a request/response pair is passed through the chain due to a + * client request for a resource at the end of the chain. The FilterChain + * passed in to this method allows the Filter to pass on the request and + * response to the next entity in the chain. + *

+ * A typical implementation of this method would follow the following + * pattern:-
+ * 1. Examine the request
+ * 2. Optionally wrap the request object with a custom implementation to + * filter content or headers for input filtering
+ * 3. Optionally wrap the response object with a custom implementation to + * filter content or headers for output filtering
+ * 4. a) Either invoke the next entity in the chain using + * the FilterChain object (chain.doFilter()),
+ * 4. b) or not pass on the request/response pair to the + * next entity in the filter chain to block the request processing
+ * 5. Directly set headers on the response after invocation of the next + * entity in the filter chain. + **/ + public void doFilter(ServletRequest request, ServletResponse response, + FilterChain chain) throws IOException, ServletException; + + /** + * Called by the web container to indicate to a filter that it is being + * taken out of service. This method is only called once all threads within + * the filter's doFilter method have exited or after a timeout period has + * passed. After the web container calls this method, it will not call the + * doFilter method again on this instance of the filter.
+ *
+ * + * This method gives the filter an opportunity to clean up any resources + * that are being held (for example, memory, file handles, threads) and make + * sure that any persistent state is synchronized with the filter's current + * state in memory. + */ + public void destroy(); + +} diff --git a/lib/servlet-api/javax/servlet/FilterChain.java b/lib/servlet-api/javax/servlet/FilterChain.java new file mode 100644 index 00000000..cdc5206a --- /dev/null +++ b/lib/servlet-api/javax/servlet/FilterChain.java @@ -0,0 +1,49 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; + +/** + * A FilterChain is an object provided by the servlet container to the developer + * giving a view into the invocation chain of a filtered request for a resource. + * Filters use the FilterChain to invoke the next filter in the chain, or if the + * calling filter is the last filter in the chain, to invoke the resource at the + * end of the chain. + * + * @see Filter + * @since Servlet 2.3 + **/ + +public interface FilterChain { + + /** + * Causes the next filter in the chain to be invoked, or if the calling + * filter is the last filter in the chain, causes the resource at the end of + * the chain to be invoked. + * + * @param request + * the request to pass along the chain. + * @param response + * the response to pass along the chain. + * + * @since 2.3 + */ + public void doFilter(ServletRequest request, ServletResponse response) + throws IOException, ServletException; + +} diff --git a/lib/servlet-api/javax/servlet/FilterConfig.java b/lib/servlet-api/javax/servlet/FilterConfig.java new file mode 100644 index 00000000..4a0a65b6 --- /dev/null +++ b/lib/servlet-api/javax/servlet/FilterConfig.java @@ -0,0 +1,73 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet; + +import java.util.Enumeration; + +/** + * + * A filter configuration object used by a servlet container to pass information + * to a filter during initialization. + * + * @see Filter + * @since Servlet 2.3 + */ +public interface FilterConfig { + + /** + * Returns the filter-name of this filter as defined in the deployment + * descriptor. + */ + public String getFilterName(); + + /** + * Returns a reference to the {@link ServletContext} in which the caller is + * executing. + * + * @return {@link ServletContext} object, used by the caller to interact + * with its servlet container + * + * @see ServletContext + */ + public ServletContext getServletContext(); + + /** + * Returns a String containing the value of the named + * initialization parameter, or null if the parameter does not + * exist. + * + * @param name + * String specifying the name of the initialization + * parameter + * + * @return String containing the value of the initialization + * parameter + */ + public String getInitParameter(String name); + + /** + * Returns the names of the filter's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the filter has no initialization parameters. + * + * @return Enumeration of String objects + * containing the names of the filter's initialization parameters + */ + public Enumeration getInitParameterNames(); + +} diff --git a/lib/servlet-api/javax/servlet/FilterRegistration.java b/lib/servlet-api/javax/servlet/FilterRegistration.java new file mode 100644 index 00000000..52d95967 --- /dev/null +++ b/lib/servlet-api/javax/servlet/FilterRegistration.java @@ -0,0 +1,67 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.Collection; +import java.util.EnumSet; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public interface FilterRegistration extends Registration { + + /** + * + * @param dispatcherTypes + * @param isMatchAfter + * @param servletNames + * @throws IllegalArgumentException + * @throws IllegalStateException + */ + public void addMappingForServletNames( + EnumSet dispatcherTypes, + boolean isMatchAfter, String... servletNames); + /** + * + * @return TODO + */ + public Collection getServletNameMappings(); + + /** + * + * @param dispatcherTypes + * @param isMatchAfter + * @param urlPatterns + * @throws IllegalArgumentException + * @throws IllegalStateException + */ + public void addMappingForUrlPatterns( + EnumSet dispatcherTypes, + boolean isMatchAfter, String... urlPatterns); + + /** + * + * @return TODO + */ + public Collection getUrlPatternMappings(); + + public static interface Dynamic + extends FilterRegistration, Registration.Dynamic { + // No additional methods + } +} diff --git a/lib/servlet-api/javax/servlet/GenericServlet.java b/lib/servlet-api/javax/servlet/GenericServlet.java new file mode 100644 index 00000000..f040cb7a --- /dev/null +++ b/lib/servlet-api/javax/servlet/GenericServlet.java @@ -0,0 +1,238 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; +import java.util.Enumeration; + +/** + * Defines a generic, protocol-independent servlet. To write an HTTP servlet for + * use on the Web, extend {@link javax.servlet.http.HttpServlet} instead. + *

+ * GenericServlet implements the Servlet and + * ServletConfig interfaces. GenericServlet may be + * directly extended by a servlet, although it's more common to extend a + * protocol-specific subclass such as HttpServlet. + *

+ * GenericServlet makes writing servlets easier. It provides simple + * versions of the lifecycle methods init and destroy + * and of the methods in the ServletConfig interface. + * GenericServlet also implements the log method, + * declared in the ServletContext interface. + *

+ * To write a generic servlet, you need only override the abstract + * service method. + */ +public abstract class GenericServlet implements Servlet, ServletConfig, + java.io.Serializable { + + private static final long serialVersionUID = 1L; + + private transient ServletConfig config; + + /** + * Does nothing. All of the servlet initialization is done by one of the + * init methods. + */ + public GenericServlet() { + // NOOP + } + + /** + * Called by the servlet container to indicate to a servlet that the servlet + * is being taken out of service. See {@link Servlet#destroy}. + */ + @Override + public void destroy() { + // NOOP by default + } + + /** + * Returns a String containing the value of the named + * initialization parameter, or null if the parameter does not + * exist. See {@link ServletConfig#getInitParameter}. + *

+ * This method is supplied for convenience. It gets the value of the named + * parameter from the servlet's ServletConfig object. + * + * @param name + * a String specifying the name of the + * initialization parameter + * @return String a String containing the value of the + * initialization parameter + */ + @Override + public String getInitParameter(String name) { + return getServletConfig().getInitParameter(name); + } + + /** + * Returns the names of the servlet's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the servlet has no initialization parameters. + * See {@link ServletConfig#getInitParameterNames}. + *

+ * This method is supplied for convenience. It gets the parameter names from + * the servlet's ServletConfig object. + * + * @return Enumeration an enumeration of String objects + * containing the names of the servlet's initialization parameters + */ + @Override + public Enumeration getInitParameterNames() { + return getServletConfig().getInitParameterNames(); + } + + /** + * Returns this servlet's {@link ServletConfig} object. + * + * @return ServletConfig the ServletConfig object that + * initialized this servlet + */ + @Override + public ServletConfig getServletConfig() { + return config; + } + + /** + * Returns a reference to the {@link ServletContext} in which this servlet + * is running. See {@link ServletConfig#getServletContext}. + *

+ * This method is supplied for convenience. It gets the context from the + * servlet's ServletConfig object. + * + * @return ServletContext the ServletContext object passed to + * this servlet by the init method + */ + @Override + public ServletContext getServletContext() { + return getServletConfig().getServletContext(); + } + + /** + * Returns information about the servlet, such as author, version, and + * copyright. By default, this method returns an empty string. Override this + * method to have it return a meaningful value. See + * {@link Servlet#getServletInfo}. + * + * @return String information about this servlet, by default an empty string + */ + @Override + public String getServletInfo() { + return ""; + } + + /** + * Called by the servlet container to indicate to a servlet that the servlet + * is being placed into service. See {@link Servlet#init}. + *

+ * This implementation stores the {@link ServletConfig} object it receives + * from the servlet container for later use. When overriding this form of + * the method, call super.init(config). + * + * @param config + * the ServletConfig object that contains + * configuration information for this servlet + * @exception ServletException + * if an exception occurs that interrupts the servlet's + * normal operation + * @see UnavailableException + */ + @Override + public void init(ServletConfig config) throws ServletException { + this.config = config; + this.init(); + } + + /** + * A convenience method which can be overridden so that there's no need to + * call super.init(config). + *

+ * Instead of overriding {@link #init(ServletConfig)}, simply override this + * method and it will be called by + * GenericServlet.init(ServletConfig config). The + * ServletConfig object can still be retrieved via + * {@link #getServletConfig}. + * + * @exception ServletException + * if an exception occurs that interrupts the servlet's + * normal operation + */ + public void init() throws ServletException { + // NOOP by default + } + + /** + * Writes the specified message to a servlet log file, prepended by the + * servlet's name. See {@link ServletContext#log(String)}. + * + * @param msg + * a String specifying the message to be written to + * the log file + */ + public void log(String msg) { + getServletContext().log(getServletName() + ": " + msg); + } + + /** + * Writes an explanatory message and a stack trace for a given + * Throwable exception to the servlet log file, prepended by + * the servlet's name. See {@link ServletContext#log(String, Throwable)}. + * + * @param message + * a String that describes the error or exception + * @param t + * the java.lang.Throwable error or exception + */ + public void log(String message, Throwable t) { + getServletContext().log(getServletName() + ": " + message, t); + } + + /** + * Called by the servlet container to allow the servlet to respond to a + * request. See {@link Servlet#service}. + *

+ * This method is declared abstract so subclasses, such as + * HttpServlet, must override it. + * + * @param req + * the ServletRequest object that contains the + * client's request + * @param res + * the ServletResponse object that will contain the + * servlet's response + * @exception ServletException + * if an exception occurs that interferes with the servlet's + * normal operation occurred + * @exception IOException + * if an input or output exception occurs + */ + @Override + public abstract void service(ServletRequest req, ServletResponse res) + throws ServletException, IOException; + + /** + * Returns the name of this servlet instance. See + * {@link ServletConfig#getServletName}. + * + * @return the name of this servlet instance + */ + @Override + public String getServletName() { + return config.getServletName(); + } +} diff --git a/lib/servlet-api/javax/servlet/HttpConstraintElement.java b/lib/servlet-api/javax/servlet/HttpConstraintElement.java new file mode 100644 index 00000000..c7a4f93f --- /dev/null +++ b/lib/servlet-api/javax/servlet/HttpConstraintElement.java @@ -0,0 +1,98 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.ResourceBundle; + +import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; +import javax.servlet.annotation.ServletSecurity.TransportGuarantee; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public class HttpConstraintElement { + + private static final String LSTRING_FILE = "javax.servlet.LocalStrings"; + private static final ResourceBundle lStrings = + ResourceBundle.getBundle(LSTRING_FILE); + + private final EmptyRoleSemantic emptyRoleSemantic;// = EmptyRoleSemantic.PERMIT; + private final TransportGuarantee transportGuarantee;// = TransportGuarantee.NONE; + private final String[] rolesAllowed;// = new String[0]; + + /** + * Default constraint is permit with no transport guarantee. + */ + public HttpConstraintElement() { + // Default constructor + this.emptyRoleSemantic = EmptyRoleSemantic.PERMIT; + this.transportGuarantee = TransportGuarantee.NONE; + this.rolesAllowed = new String[0]; + } + + /** + * Convenience constructor for {@link EmptyRoleSemantic#DENY}. + * + */ + public HttpConstraintElement(EmptyRoleSemantic emptyRoleSemantic) { + this.emptyRoleSemantic = emptyRoleSemantic; + this.transportGuarantee = TransportGuarantee.NONE; + this.rolesAllowed = new String[0]; + } + + /** + * Convenience constructor to specify transport guarantee and/or roles. + */ + public HttpConstraintElement(TransportGuarantee transportGuarantee, + String... rolesAllowed) { + this.emptyRoleSemantic = EmptyRoleSemantic.PERMIT; + this.transportGuarantee = transportGuarantee; + this.rolesAllowed = rolesAllowed; + } + + /** + * + * @param emptyRoleSemantic + * @param transportGuarantee + * @param rolesAllowed + * @throws IllegalArgumentException if roles are specified when DENY is used + */ + public HttpConstraintElement(EmptyRoleSemantic emptyRoleSemantic, + TransportGuarantee transportGuarantee, String... rolesAllowed) { + if (rolesAllowed != null && rolesAllowed.length > 0 && + EmptyRoleSemantic.DENY.equals(emptyRoleSemantic)) { + throw new IllegalArgumentException(lStrings.getString( + "httpConstraintElement.invalidRolesDeny")); + } + this.emptyRoleSemantic = emptyRoleSemantic; + this.transportGuarantee = transportGuarantee; + this.rolesAllowed = rolesAllowed; + } + + public EmptyRoleSemantic getEmptyRoleSemantic() { + return emptyRoleSemantic; + } + + public TransportGuarantee getTransportGuarantee() { + return transportGuarantee; + } + + public String[] getRolesAllowed() { + return rolesAllowed; + } +} \ No newline at end of file diff --git a/lib/servlet-api/javax/servlet/HttpMethodConstraintElement.java b/lib/servlet-api/javax/servlet/HttpMethodConstraintElement.java new file mode 100644 index 00000000..5de2ad99 --- /dev/null +++ b/lib/servlet-api/javax/servlet/HttpMethodConstraintElement.java @@ -0,0 +1,57 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.ResourceBundle; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public class HttpMethodConstraintElement extends HttpConstraintElement { + + // Can't inherit from HttpConstraintElement as API does not allow it + private static final String LSTRING_FILE = "javax.servlet.LocalStrings"; + private static final ResourceBundle lStrings = + ResourceBundle.getBundle(LSTRING_FILE); + + private final String methodName; + + public HttpMethodConstraintElement(String methodName) { + if (methodName == null || methodName.length() == 0) { + throw new IllegalArgumentException(lStrings.getString( + "httpMethodConstraintElement.invalidMethod")); + } + this.methodName = methodName; + } + + public HttpMethodConstraintElement(String methodName, + HttpConstraintElement constraint) { + super(constraint.getEmptyRoleSemantic(), + constraint.getTransportGuarantee(), + constraint.getRolesAllowed()); + if (methodName == null || methodName.length() == 0) { + throw new IllegalArgumentException(lStrings.getString( + "httpMethodConstraintElement.invalidMethod")); + } + this.methodName = methodName; + } + + public String getMethodName() { + return methodName; + } +} \ No newline at end of file diff --git a/lib/servlet-api/javax/servlet/LocalStrings.properties b/lib/servlet-api/javax/servlet/LocalStrings.properties new file mode 100644 index 00000000..0f60d51e --- /dev/null +++ b/lib/servlet-api/javax/servlet/LocalStrings.properties @@ -0,0 +1,24 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Default localized string information +# Localized for Locale en_US + +err.not_iso8859_1=Not an ISO 8859-1 character: {0} +value.true=true +value.false=false + +httpConstraintElement.invalidRolesDeny=Roles may not be specified when using DENY +httpMethodConstraintElement.invalidMethod=Invalid HTTP method \ No newline at end of file diff --git a/lib/servlet-api/javax/servlet/LocalStrings_es.properties b/lib/servlet-api/javax/servlet/LocalStrings_es.properties new file mode 100644 index 00000000..497c0dc3 --- /dev/null +++ b/lib/servlet-api/javax/servlet/LocalStrings_es.properties @@ -0,0 +1,19 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +err.not_iso8859_1 = No es un car\u00E1cter ISO 8859-1\: {0} +value.true = true +value.false = false +httpConstraintElement.invalidRolesDeny = No se pueden especificar Roles al utilizar DENY (DENEGAR) +httpMethodConstraintElement.invalidMethod = M\u00E9todo HTTP inv\u00E1lido diff --git a/lib/servlet-api/javax/servlet/LocalStrings_fr.properties b/lib/servlet-api/javax/servlet/LocalStrings_fr.properties new file mode 100644 index 00000000..05f75ecc --- /dev/null +++ b/lib/servlet-api/javax/servlet/LocalStrings_fr.properties @@ -0,0 +1,23 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Default localized string information +# Localized for Locale fr_FR + +err.not_iso8859_1={0} n''est pas un caract\u00e8re ISO 8859-1 +value.true=true +value.false=false + + diff --git a/lib/servlet-api/javax/servlet/LocalStrings_ja.properties b/lib/servlet-api/javax/servlet/LocalStrings_ja.properties new file mode 100644 index 00000000..2a87482d --- /dev/null +++ b/lib/servlet-api/javax/servlet/LocalStrings_ja.properties @@ -0,0 +1,21 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Default localized string information +# Localized for Locale ja_JP + +err.not_iso8859_1=ISO 8859-1 \u306e\u6587\u5b57\u3067\u306f\u3042\u308a\u307e\u305b\u3093: {0} +value.true=true +value.false=false diff --git a/lib/servlet-api/javax/servlet/MultipartConfigElement.java b/lib/servlet-api/javax/servlet/MultipartConfigElement.java new file mode 100644 index 00000000..39b9f8b5 --- /dev/null +++ b/lib/servlet-api/javax/servlet/MultipartConfigElement.java @@ -0,0 +1,79 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import javax.servlet.annotation.MultipartConfig; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public class MultipartConfigElement { + + private final String location;// = ""; + private final long maxFileSize;// = -1; + private final long maxRequestSize;// = -1; + private final int fileSizeThreshold;// = 0; + + public MultipartConfigElement(String location) { + // Keep empty string default if location is null + if (location != null) { + this.location = location; + } else { + this.location = ""; + } + this.maxFileSize = -1; + this.maxRequestSize = -1; + this.fileSizeThreshold = 0; + } + + public MultipartConfigElement(String location, long maxFileSize, + long maxRequestSize, int fileSizeThreshold) { + // Keep empty string default if location is null + if (location != null) { + this.location = location; + } else { + this.location = ""; + } + this.maxFileSize = maxFileSize; + this.maxRequestSize = maxRequestSize; + this.fileSizeThreshold = fileSizeThreshold; + } + + public MultipartConfigElement(MultipartConfig annotation) { + location = annotation.location(); + maxFileSize = annotation.maxFileSize(); + maxRequestSize = annotation.maxRequestSize(); + fileSizeThreshold = annotation.fileSizeThreshold(); + } + + public String getLocation() { + return location; + } + + public long getMaxFileSize() { + return maxFileSize; + } + + public long getMaxRequestSize() { + return maxRequestSize; + } + + public int getFileSizeThreshold() { + return fileSizeThreshold; + } +} \ No newline at end of file diff --git a/lib/servlet-api/javax/servlet/ReadListener.java b/lib/servlet-api/javax/servlet/ReadListener.java new file mode 100644 index 00000000..1d51c6c9 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ReadListener.java @@ -0,0 +1,52 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; + +/** + * Receives notification of read events when using non-blocking IO. + * + * @since Servlet 3.1 + */ +public interface ReadListener extends java.util.EventListener{ + + /** + * Invoked when data is available to read. The container will invoke this + * method the first time for a request as soon as there is data to read. + * Subsequent invocations will only occur if a call to + * {@link ServletInputStream#isReady()} has returned false and data has + * subsequently become available to read. + * + * @throws IOException + */ + public abstract void onDataAvailable() throws IOException; + + /** + * Invoked when the request body has been fully read. + * + * @throws IOException + */ + public abstract void onAllDataRead() throws IOException; + + /** + * Invoked if an error occurs while reading the request body. + * + * @param throwable The exception that occurred + */ + public abstract void onError(java.lang.Throwable throwable); +} diff --git a/lib/servlet-api/javax/servlet/Registration.java b/lib/servlet-api/javax/servlet/Registration.java new file mode 100644 index 00000000..fa9f4ec8 --- /dev/null +++ b/lib/servlet-api/javax/servlet/Registration.java @@ -0,0 +1,64 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.Map; +import java.util.Set; + +/** + * TODO SERVLET3 - Add comments + * @since Servlet 3.0 + */ +public interface Registration { + + public String getName(); + + public String getClassName(); + + /** + * + * @param name + * @param value + * @return TODO + * @throws IllegalArgumentException + * @throws IllegalStateException + */ + public boolean setInitParameter(String name, String value); + + public String getInitParameter(String name); + + /** + * + * @param initParameters + * @return TODO + * @throws IllegalArgumentException + * @throws IllegalStateException + */ + public Set setInitParameters(Map initParameters); + + public Map getInitParameters(); + + public interface Dynamic extends Registration { + + /** + * + * @param isAsyncSupported + * @throws IllegalStateException + */ + public void setAsyncSupported(boolean isAsyncSupported); + } +} diff --git a/lib/servlet-api/javax/servlet/RequestDispatcher.java b/lib/servlet-api/javax/servlet/RequestDispatcher.java new file mode 100644 index 00000000..99ceeef8 --- /dev/null +++ b/lib/servlet-api/javax/servlet/RequestDispatcher.java @@ -0,0 +1,293 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; + +/** + * Defines an object that receives requests from the client and sends them to + * any resource (such as a servlet, HTML file, or JSP file) on the server. The + * servlet container creates the RequestDispatcher object, which is + * used as a wrapper around a server resource located at a particular path or + * given by a particular name. + * + *

+ * This interface is intended to wrap servlets, but a servlet container can + * create RequestDispatcher objects to wrap any type of resource. + * + * @see ServletContext#getRequestDispatcher(java.lang.String) + * @see ServletContext#getNamedDispatcher(java.lang.String) + * @see ServletRequest#getRequestDispatcher(java.lang.String) + * + */ +public interface RequestDispatcher { + + /** + * The name of the request attribute that should be set by the container + * when the {@link #forward(ServletRequest, ServletResponse)} method is + * called. It provides the original value of a path-related property of the + * request. See the chapter "Forwarded Request Parameters" in the Servlet + * Specification for details. + * + * @since Servlet 3.0 + */ + static final String FORWARD_REQUEST_URI = "javax.servlet.forward.request_uri"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #forward(ServletRequest, ServletResponse)} method is + * called. It provides the original value of a path-related property of the + * request. See the chapter "Forwarded Request Parameters" in the Servlet + * Specification for details. + * + * @since Servlet 3.0 + */ + static final String FORWARD_CONTEXT_PATH = "javax.servlet.forward.context_path"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #forward(ServletRequest, ServletResponse)} method is + * called. It provides the original value of a path-related property of the + * request. See the chapter "Forwarded Request Parameters" in the Servlet + * Specification for details. + * + * @since Servlet 3.0 + */ + static final String FORWARD_PATH_INFO = "javax.servlet.forward.path_info"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #forward(ServletRequest, ServletResponse)} method is + * called. It provides the original value of a path-related property of the + * request. See the chapter "Forwarded Request Parameters" in the Servlet + * Specification for details. + * + * @since Servlet 3.0 + */ + static final String FORWARD_SERVLET_PATH = "javax.servlet.forward.servlet_path"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #forward(ServletRequest, ServletResponse)} method is + * called. It provides the original value of a path-related property of the + * request. See the chapter "Forwarded Request Parameters" in the Servlet + * Specification for details. + * + * @since Servlet 3.0 + */ + static final String FORWARD_QUERY_STRING = "javax.servlet.forward.query_string"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #include(ServletRequest, ServletResponse)} method is + * called on the {@code RequestDispatcher} obtained by a path and not by a + * name. It provides information on the path that was used to obtain the + * {@code RequestDispatcher} instance for this include call. See the chapter + * "Included Request Parameters" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + static final String INCLUDE_REQUEST_URI = "javax.servlet.include.request_uri"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #include(ServletRequest, ServletResponse)} method is + * called on the {@code RequestDispatcher} obtained by a path and not by a + * name. It provides information on the path that was used to obtain the + * {@code RequestDispatcher} instance for this include call. See the chapter + * "Included Request Parameters" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + static final String INCLUDE_CONTEXT_PATH = "javax.servlet.include.context_path"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #include(ServletRequest, ServletResponse)} method is + * called on the {@code RequestDispatcher} obtained by a path and not by a + * name. It provides information on the path that was used to obtain the + * {@code RequestDispatcher} instance for this include call. See the chapter + * "Included Request Parameters" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + static final String INCLUDE_PATH_INFO = "javax.servlet.include.path_info"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #include(ServletRequest, ServletResponse)} method is + * called on the {@code RequestDispatcher} obtained by a path and not by a + * name. It provides information on the path that was used to obtain the + * {@code RequestDispatcher} instance for this include call. See the chapter + * "Included Request Parameters" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + static final String INCLUDE_SERVLET_PATH = "javax.servlet.include.servlet_path"; + + /** + * The name of the request attribute that should be set by the container + * when the {@link #include(ServletRequest, ServletResponse)} method is + * called on the {@code RequestDispatcher} obtained by a path and not by a + * name. It provides information on the path that was used to obtain the + * {@code RequestDispatcher} instance for this include call. See the chapter + * "Included Request Parameters" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + static final String INCLUDE_QUERY_STRING = "javax.servlet.include.query_string"; + + /** + * The name of the request attribute that should be set by the container + * when custom error-handling servlet or JSP page is invoked. The value of + * the attribute is of type {@code java.lang.Throwable}. See the chapter + * "Error Handling" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + public static final String ERROR_EXCEPTION = "javax.servlet.error.exception"; + + /** + * The name of the request attribute that should be set by the container + * when custom error-handling servlet or JSP page is invoked. The value of + * the attribute is of type {@code java.lang.Class}. See the chapter + * "Error Handling" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + public static final String ERROR_EXCEPTION_TYPE = "javax.servlet.error.exception_type"; + + /** + * The name of the request attribute that should be set by the container + * when custom error-handling servlet or JSP page is invoked. The value of + * the attribute is of type {@code java.lang.String}. See the chapter + * "Error Handling" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + public static final String ERROR_MESSAGE = "javax.servlet.error.message"; + + /** + * The name of the request attribute that should be set by the container + * when custom error-handling servlet or JSP page is invoked. The value of + * the attribute is of type {@code java.lang.String}. See the chapter + * "Error Handling" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + public static final String ERROR_REQUEST_URI = "javax.servlet.error.request_uri"; + + /** + * The name of the request attribute that should be set by the container + * when custom error-handling servlet or JSP page is invoked. The value of + * the attribute is of type {@code java.lang.String}. See the chapter + * "Error Handling" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + public static final String ERROR_SERVLET_NAME = "javax.servlet.error.servlet_name"; + + /** + * The name of the request attribute that should be set by the container + * when custom error-handling servlet or JSP page is invoked. The value of + * the attribute is of type {@code java.lang.Integer}. See the chapter + * "Error Handling" in the Servlet Specification for details. + * + * @since Servlet 3.0 + */ + public static final String ERROR_STATUS_CODE = "javax.servlet.error.status_code"; + + /** + * Forwards a request from a servlet to another resource (servlet, JSP file, + * or HTML file) on the server. This method allows one servlet to do + * preliminary processing of a request and another resource to generate the + * response. + * + *

+ * For a RequestDispatcher obtained via + * getRequestDispatcher(), the ServletRequest + * object has its path elements and parameters adjusted to match the path of + * the target resource. + * + *

+ * forward should be called before the response has been + * committed to the client (before response body output has been flushed). + * If the response already has been committed, this method throws an + * IllegalStateException. Uncommitted output in the response + * buffer is automatically cleared before the forward. + * + *

+ * The request and response parameters must be either the same objects as + * were passed to the calling servlet's service method or be subclasses of + * the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} + * classes that wrap them. + * + * + * @param request + * a {@link ServletRequest} object that represents the request + * the client makes of the servlet + * + * @param response + * a {@link ServletResponse} object that represents the response + * the servlet returns to the client + * + * @exception ServletException + * if the target resource throws this exception + * + * @exception IOException + * if the target resource throws this exception + * + * @exception IllegalStateException + * if the response was already committed + */ + public void forward(ServletRequest request, ServletResponse response) + throws ServletException, IOException; + + /** + * Includes the content of a resource (servlet, JSP page, HTML file) in the + * response. In essence, this method enables programmatic server-side + * includes. + * + *

+ * The {@link ServletResponse} object has its path elements and parameters + * remain unchanged from the caller's. The included servlet cannot change + * the response status code or set headers; any attempt to make a change is + * ignored. + * + *

+ * The request and response parameters must be either the same objects as + * were passed to the calling servlet's service method or be subclasses of + * the {@link ServletRequestWrapper} or {@link ServletResponseWrapper} + * classes that wrap them. + * + * @param request + * a {@link ServletRequest} object that contains the client's + * request + * + * @param response + * a {@link ServletResponse} object that contains the servlet's + * response + * + * @exception ServletException + * if the included resource throws this exception + * + * @exception IOException + * if the included resource throws this exception + */ + public void include(ServletRequest request, ServletResponse response) + throws ServletException, IOException; +} diff --git a/lib/servlet-api/javax/servlet/Servlet.java b/lib/servlet-api/javax/servlet/Servlet.java new file mode 100644 index 00000000..73d30bbf --- /dev/null +++ b/lib/servlet-api/javax/servlet/Servlet.java @@ -0,0 +1,178 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet; + +import java.io.IOException; + +/** + * Defines methods that all servlets must implement. + * + *

+ * A servlet is a small Java program that runs within a Web server. Servlets + * receive and respond to requests from Web clients, usually across HTTP, the + * HyperText Transfer Protocol. + * + *

+ * To implement this interface, you can write a generic servlet that extends + * javax.servlet.GenericServlet or an HTTP servlet that extends + * javax.servlet.http.HttpServlet. + * + *

+ * This interface defines methods to initialize a servlet, to service requests, + * and to remove a servlet from the server. These are known as life-cycle + * methods and are called in the following sequence: + *

    + *
  1. The servlet is constructed, then initialized with the init + * method. + *
  2. Any calls from clients to the service method are handled. + *
  3. The servlet is taken out of service, then destroyed with the + * destroy method, then garbage collected and finalized. + *
+ * + *

+ * In addition to the life-cycle methods, this interface provides the + * getServletConfig method, which the servlet can use to get any + * startup information, and the getServletInfo method, which allows + * the servlet to return basic information about itself, such as author, + * version, and copyright. + * + * @see GenericServlet + * @see javax.servlet.http.HttpServlet + */ +public interface Servlet { + + /** + * Called by the servlet container to indicate to a servlet that the servlet + * is being placed into service. + * + *

+ * The servlet container calls the init method exactly once + * after instantiating the servlet. The init method must + * complete successfully before the servlet can receive any requests. + * + *

+ * The servlet container cannot place the servlet into service if the + * init method + *

    + *
  1. Throws a ServletException + *
  2. Does not return within a time period defined by the Web server + *
+ * + * + * @param config + * a ServletConfig object containing the servlet's + * configuration and initialization parameters + * + * @exception ServletException + * if an exception has occurred that interferes with the + * servlet's normal operation + * + * @see UnavailableException + * @see #getServletConfig + */ + public void init(ServletConfig config) throws ServletException; + + /** + * + * Returns a {@link ServletConfig} object, which contains initialization and + * startup parameters for this servlet. The ServletConfig + * object returned is the one passed to the init method. + * + *

+ * Implementations of this interface are responsible for storing the + * ServletConfig object so that this method can return it. The + * {@link GenericServlet} class, which implements this interface, already + * does this. + * + * @return the ServletConfig object that initializes this + * servlet + * + * @see #init + */ + public ServletConfig getServletConfig(); + + /** + * Called by the servlet container to allow the servlet to respond to a + * request. + * + *

+ * This method is only called after the servlet's init() method + * has completed successfully. + * + *

+ * The status code of the response always should be set for a servlet that + * throws or sends an error. + * + * + *

+ * Servlets typically run inside multithreaded servlet containers that can + * handle multiple requests concurrently. Developers must be aware to + * synchronize access to any shared resources such as files, network + * connections, and as well as the servlet's class and instance variables. + * More information on multithreaded programming in Java is available in + * the Java tutorial on multi-threaded programming. + * + * + * @param req + * the ServletRequest object that contains the + * client's request + * + * @param res + * the ServletResponse object that contains the + * servlet's response + * + * @exception ServletException + * if an exception occurs that interferes with the servlet's + * normal operation + * + * @exception IOException + * if an input or output exception occurs + */ + public void service(ServletRequest req, ServletResponse res) + throws ServletException, IOException; + + /** + * Returns information about the servlet, such as author, version, and + * copyright. + * + *

+ * The string that this method returns should be plain text and not markup + * of any kind (such as HTML, XML, etc.). + * + * @return a String containing servlet information + */ + public String getServletInfo(); + + /** + * Called by the servlet container to indicate to a servlet that the servlet + * is being taken out of service. This method is only called once all + * threads within the servlet's service method have exited or + * after a timeout period has passed. After the servlet container calls this + * method, it will not call the service method again on this + * servlet. + * + *

+ * This method gives the servlet an opportunity to clean up any resources + * that are being held (for example, memory, file handles, threads) and make + * sure that any persistent state is synchronized with the servlet's current + * state in memory. + */ + public void destroy(); +} diff --git a/lib/servlet-api/javax/servlet/ServletConfig.java b/lib/servlet-api/javax/servlet/ServletConfig.java new file mode 100644 index 00000000..be61656e --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletConfig.java @@ -0,0 +1,69 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.util.Enumeration; + +/** + * A servlet configuration object used by a servlet container to pass + * information to a servlet during initialization. + */ +public interface ServletConfig { + + /** + * Returns the name of this servlet instance. The name may be provided via + * server administration, assigned in the web application deployment + * descriptor, or for an unregistered (and thus unnamed) servlet instance it + * will be the servlet's class name. + * + * @return the name of the servlet instance + */ + public String getServletName(); + + /** + * Returns a reference to the {@link ServletContext} in which the caller is + * executing. + * + * @return a {@link ServletContext} object, used by the caller to interact + * with its servlet container + * @see ServletContext + */ + public ServletContext getServletContext(); + + /** + * Returns a String containing the value of the named + * initialization parameter, or null if the parameter does not + * exist. + * + * @param name + * a String specifying the name of the + * initialization parameter + * @return a String containing the value of the initialization + * parameter + */ + public String getInitParameter(String name); + + /** + * Returns the names of the servlet's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the servlet has no initialization parameters. + * + * @return an Enumeration of String objects + * containing the names of the servlet's initialization parameters + */ + public Enumeration getInitParameterNames(); +} diff --git a/lib/servlet-api/javax/servlet/ServletContainerInitializer.java b/lib/servlet-api/javax/servlet/ServletContainerInitializer.java new file mode 100644 index 00000000..2029c8a4 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletContainerInitializer.java @@ -0,0 +1,53 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.Set; + +/** + * ServletContainerInitializers (SCIs) are registered via an entry in the + * file META-INF/services/javax.servlet.ServletContainerInitializer that must be + * included in the JAR file that contains the SCI implementation. + *

+ * SCI processing is performed regardless of the setting of metadata-complete. + * SCI processing can be controlled per JAR file via fragment ordering. If an + * absolute ordering is defined, the only those JARs included in the ordering + * will be processed for SCIs. To disable SCI processing completely, an empty + * absolute ordering may be defined. + *

+ * SCIs register an interest in annotations (class, method or field) and/or + * types via the {@link javax.servlet.annotation.HandlesTypes} annotation which + * is added to the class. + * + * @since Servlet 3.0 + */ +public interface ServletContainerInitializer { + + /** + * Receives notification during startup of a web application of the classes + * within the web application that matched the criteria defined via the + * {@link javax.servlet.annotation.HandlesTypes} annotation. + * + * @param c The (possibly null) set of classes that met the specified + * criteria + * @param ctx The ServletContext of the web application in which the + * classes were discovered + * + * @throws ServletException If an error occurs + */ + void onStartup(Set> c, ServletContext ctx) throws ServletException; +} diff --git a/lib/servlet-api/javax/servlet/ServletContext.java b/lib/servlet-api/javax/servlet/ServletContext.java new file mode 100644 index 00000000..9aa11775 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletContext.java @@ -0,0 +1,895 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.InputStream; +import java.net.MalformedURLException; +import java.net.URL; +import java.util.Enumeration; +import java.util.EventListener; +import java.util.Map; +import java.util.Set; + +import javax.servlet.descriptor.JspConfigDescriptor; + +/** + * Defines a set of methods that a servlet uses to communicate with its servlet + * container, for example, to get the MIME type of a file, dispatch requests, or + * write to a log file. + *

+ * There is one context per "web application" per Java Virtual Machine. (A + * "web application" is a collection of servlets and content installed under a + * specific subset of the server's URL namespace such as /catalog + * and possibly installed via a .war file.) + *

+ * In the case of a web application marked "distributed" in its deployment + * descriptor, there will be one context instance for each virtual machine. In + * this situation, the context cannot be used as a location to share global + * information (because the information won't be truly global). Use an external + * resource like a database instead. + *

+ * The ServletContext object is contained within the + * {@link ServletConfig} object, which the Web server provides the servlet when + * the servlet is initialized. + * + * @see Servlet#getServletConfig + * @see ServletConfig#getServletContext + */ +public interface ServletContext { + + public static final String TEMPDIR = "javax.servlet.context.tempdir"; + + /** + * @since Servlet 3.0 + */ + public static final String ORDERED_LIBS = "javax.servlet.context.orderedLibs"; + + public String getContextPath(); + + /** + * Returns a ServletContext object that corresponds to a + * specified URL on the server. + *

+ * This method allows servlets to gain access to the context for various + * parts of the server, and as needed obtain {@link RequestDispatcher} + * objects from the context. The given path must be begin with "/", is + * interpreted relative to the server's document root and is matched against + * the context roots of other web applications hosted on this container. + *

+ * In a security conscious environment, the servlet container may return + * null for a given URL. + * + * @param uripath + * a String specifying the context path of another + * web application in the container. + * @return the ServletContext object that corresponds to the + * named URL, or null if either none exists or the container wishes + * to restrict this access. + * @see RequestDispatcher + */ + public ServletContext getContext(String uripath); + + /** + * Returns the major version of the Java Servlet API that this servlet + * container supports. All implementations that comply with Version 3.1 must + * have this method return the integer 3. + * + * @return 3 + */ + public int getMajorVersion(); + + /** + * Returns the minor version of the Servlet API that this servlet container + * supports. All implementations that comply with Version 3.1 must have this + * method return the integer 1. + * + * @return 1 + */ + public int getMinorVersion(); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public int getEffectiveMajorVersion(); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public int getEffectiveMinorVersion(); + + /** + * Returns the MIME type of the specified file, or null if the + * MIME type is not known. The MIME type is determined by the configuration + * of the servlet container, and may be specified in a web application + * deployment descriptor. Common MIME types are "text/html" and + * "image/gif". + * + * @param file + * a String specifying the name of a file + * @return a String specifying the file's MIME type + */ + public String getMimeType(String file); + + /** + * Returns a directory-like listing of all the paths to resources within the + * web application whose longest sub-path matches the supplied path + * argument. Paths indicating subdirectory paths end with a '/'. The + * returned paths are all relative to the root of the web application and + * have a leading '/'. For example, for a web application containing
+ *
+ * /welcome.html
+ * /catalog/index.html
+ * /catalog/products.html
+ * /catalog/offers/books.html
+ * /catalog/offers/music.html
+ * /customer/login.jsp
+ * /WEB-INF/web.xml
+ * /WEB-INF/classes/com.acme.OrderServlet.class,
+ *
+ * getResourcePaths("/") returns {"/welcome.html", "/catalog/", + * "/customer/", "/WEB-INF/"}
+ * getResourcePaths("/catalog/") returns {"/catalog/index.html", + * "/catalog/products.html", "/catalog/offers/"}.
+ * + * @param path + * the partial path used to match the resources, which must start + * with a / + * @return a Set containing the directory listing, or null if there are no + * resources in the web application whose path begins with the + * supplied path. + * @since Servlet 2.3 + */ + public Set getResourcePaths(String path); + + /** + * Returns a URL to the resource that is mapped to a specified path. The + * path must begin with a "/" and is interpreted as relative to the current + * context root. + *

+ * This method allows the servlet container to make a resource available to + * servlets from any source. Resources can be located on a local or remote + * file system, in a database, or in a .war file. + *

+ * The servlet container must implement the URL handlers and + * URLConnection objects that are necessary to access the + * resource. + *

+ * This method returns null if no resource is mapped to the + * pathname. + *

+ * Some containers may allow writing to the URL returned by this method + * using the methods of the URL class. + *

+ * The resource content is returned directly, so be aware that requesting a + * .jsp page returns the JSP source code. Use a + * RequestDispatcher instead to include results of an + * execution. + *

+ * This method has a different purpose than + * java.lang.Class.getResource, which looks up resources based + * on a class loader. This method does not use class loaders. + * + * @param path + * a String specifying the path to the resource + * @return the resource located at the named path, or null if + * there is no resource at that path + * @exception MalformedURLException + * if the pathname is not given in the correct form + */ + public URL getResource(String path) throws MalformedURLException; + + /** + * Returns the resource located at the named path as an + * InputStream object. + *

+ * The data in the InputStream can be of any type or length. + * The path must be specified according to the rules given in + * getResource. This method returns null if no + * resource exists at the specified path. + *

+ * Meta-information such as content length and content type that is + * available via getResource method is lost when using this + * method. + *

+ * The servlet container must implement the URL handlers and + * URLConnection objects necessary to access the resource. + *

+ * This method is different from + * java.lang.Class.getResourceAsStream, which uses a class + * loader. This method allows servlet containers to make a resource + * available to a servlet from any location, without using a class loader. + * + * @param path + * a String specifying the path to the resource + * @return the InputStream returned to the servlet, or + * null if no resource exists at the specified path + */ + public InputStream getResourceAsStream(String path); + + /** + * Returns a {@link RequestDispatcher} object that acts as a wrapper for the + * resource located at the given path. A RequestDispatcher + * object can be used to forward a request to the resource or to include the + * resource in a response. The resource can be dynamic or static. + *

+ * The pathname must begin with a "/" and is interpreted as relative to the + * current context root. Use getContext to obtain a + * RequestDispatcher for resources in foreign contexts. This + * method returns null if the ServletContext + * cannot return a RequestDispatcher. + * + * @param path + * a String specifying the pathname to the resource + * @return a RequestDispatcher object that acts as a wrapper for + * the resource at the specified path, or null if the + * ServletContext cannot return a + * RequestDispatcher + * @see RequestDispatcher + * @see ServletContext#getContext + */ + public RequestDispatcher getRequestDispatcher(String path); + + /** + * Returns a {@link RequestDispatcher} object that acts as a wrapper for the + * named servlet. + *

+ * Servlets (and JSP pages also) may be given names via server + * administration or via a web application deployment descriptor. A servlet + * instance can determine its name using + * {@link ServletConfig#getServletName}. + *

+ * This method returns null if the ServletContext + * cannot return a RequestDispatcher for any reason. + * + * @param name + * a String specifying the name of a servlet to wrap + * @return a RequestDispatcher object that acts as a wrapper for + * the named servlet, or null if the + * ServletContext cannot return a + * RequestDispatcher + * @see RequestDispatcher + * @see ServletContext#getContext + * @see ServletConfig#getServletName + */ + public RequestDispatcher getNamedDispatcher(String name); + + /** + * @deprecated As of Java Servlet API 2.1, with no direct replacement. + *

+ * This method was originally defined to retrieve a servlet from + * a ServletContext. In this version, this method + * always returns null and remains only to preserve + * binary compatibility. This method will be permanently removed + * in a future version of the Java Servlet API. + *

+ * In lieu of this method, servlets can share information using + * the ServletContext class and can perform shared + * business logic by invoking methods on common non-servlet + * classes. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public Servlet getServlet(String name) throws ServletException; + + /** + * @deprecated As of Java Servlet API 2.0, with no replacement. + *

+ * This method was originally defined to return an + * Enumeration of all the servlets known to this + * servlet context. In this version, this method always returns + * an empty enumeration and remains only to preserve binary + * compatibility. This method will be permanently removed in a + * future version of the Java Servlet API. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public Enumeration getServlets(); + + /** + * @deprecated As of Java Servlet API 2.1, with no replacement. + *

+ * This method was originally defined to return an + * Enumeration of all the servlet names known to + * this context. In this version, this method always returns an + * empty Enumeration and remains only to preserve + * binary compatibility. This method will be permanently removed + * in a future version of the Java Servlet API. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public Enumeration getServletNames(); + + /** + * Writes the specified message to a servlet log file, usually an event log. + * The name and type of the servlet log file is specific to the servlet + * container. + * + * @param msg + * a String specifying the message to be written to + * the log file + */ + public void log(String msg); + + /** + * @deprecated As of Java Servlet API 2.1, use + * {@link #log(String message, Throwable throwable)} instead. + *

+ * This method was originally defined to write an exception's + * stack trace and an explanatory error message to the servlet + * log file. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public void log(Exception exception, String msg); + + /** + * Writes an explanatory message and a stack trace for a given + * Throwable exception to the servlet log file. The name and + * type of the servlet log file is specific to the servlet container, + * usually an event log. + * + * @param message + * a String that describes the error or exception + * @param throwable + * the Throwable error or exception + */ + public void log(String message, Throwable throwable); + + /** + * Returns a String containing the real path for a given + * virtual path. For example, the path "/index.html" returns the absolute + * file path on the server's filesystem would be served by a request for + * "http://host/contextPath/index.html", where contextPath is the context + * path of this ServletContext.. + *

+ * The real path returned will be in a form appropriate to the computer and + * operating system on which the servlet container is running, including the + * proper path separators. This method returns null if the + * servlet container cannot translate the virtual path to a real path for + * any reason (such as when the content is being made available from a + * .war archive). + * + * @param path + * a String specifying a virtual path + * @return a String specifying the real path, or null if the + * translation cannot be performed + */ + public String getRealPath(String path); + + /** + * Returns the name and version of the servlet container on which the + * servlet is running. + *

+ * The form of the returned string is + * servername/versionnumber. For example, the JavaServer Web + * Development Kit may return the string + * JavaServer Web Dev Kit/1.0. + *

+ * The servlet container may return other optional information after the + * primary string in parentheses, for example, + * JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86). + * + * @return a String containing at least the servlet container + * name and version number + */ + public String getServerInfo(); + + /** + * Returns a String containing the value of the named + * context-wide initialization parameter, or null if the + * parameter does not exist. + *

+ * This method can make available configuration information useful to an + * entire "web application". For example, it can provide a webmaster's email + * address or the name of a system that holds critical data. + * + * @param name + * a String containing the name of the parameter + * whose value is requested + * @return a String containing the value of the initialization + * parameter + * @see ServletConfig#getInitParameter + */ + public String getInitParameter(String name); + + /** + * Returns the names of the context's initialization parameters as an + * Enumeration of String objects, or an empty + * Enumeration if the context has no initialization parameters. + * + * @return an Enumeration of String objects + * containing the names of the context's initialization parameters + * @see ServletConfig#getInitParameter + */ + + public Enumeration getInitParameterNames(); + + /** + * @param name + * @param value + * @return TODO + * @throws IllegalStateException + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean setInitParameter(String name, String value); + + /** + * Returns the servlet container attribute with the given name, or + * null if there is no attribute by that name. An attribute + * allows a servlet container to give the servlet additional information not + * already provided by this interface. See your server documentation for + * information about its attributes. A list of supported attributes can be + * retrieved using getAttributeNames. + *

+ * The attribute is returned as a java.lang.Object or some + * subclass. Attribute names should follow the same convention as package + * names. The Java Servlet API specification reserves names matching + * java.*, javax.*, and sun.*. + * + * @param name + * a String specifying the name of the attribute + * @return an Object containing the value of the attribute, or + * null if no attribute exists matching the given name + * @see ServletContext#getAttributeNames + */ + public Object getAttribute(String name); + + /** + * Returns an Enumeration containing the attribute names + * available within this servlet context. Use the {@link #getAttribute} + * method with an attribute name to get the value of an attribute. + * + * @return an Enumeration of attribute names + * @see #getAttribute + */ + public Enumeration getAttributeNames(); + + /** + * Binds an object to a given attribute name in this servlet context. If the + * name specified is already used for an attribute, this method will replace + * the attribute with the new to the new attribute. + *

+ * If listeners are configured on the ServletContext the + * container notifies them accordingly. + *

+ * If a null value is passed, the effect is the same as calling + * removeAttribute(). + *

+ * Attribute names should follow the same convention as package names. The + * Java Servlet API specification reserves names matching + * java.*, javax.*, and sun.*. + * + * @param name + * a String specifying the name of the attribute + * @param object + * an Object representing the attribute to be bound + */ + public void setAttribute(String name, Object object); + + /** + * Removes the attribute with the given name from the servlet context. After + * removal, subsequent calls to {@link #getAttribute} to retrieve the + * attribute's value will return null. + *

+ * If listeners are configured on the ServletContext the + * container notifies them accordingly. + * + * @param name + * a String specifying the name of the attribute to + * be removed + */ + public void removeAttribute(String name); + + /** + * Returns the name of this web application corresponding to this + * ServletContext as specified in the deployment descriptor for this web + * application by the display-name element. + * + * @return The name of the web application or null if no name has been + * declared in the deployment descriptor. + * @since Servlet 2.3 + */ + public String getServletContextName(); + + /** + * @param servletName + * @param className + * @return TODO + * @throws IllegalStateException + * If the context has already been initialised + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public ServletRegistration.Dynamic addServlet(String servletName, + String className); + + /** + * @param servletName + * @param servlet + * @return TODO + * @throws IllegalStateException + * If the context has already been initialised + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public ServletRegistration.Dynamic addServlet(String servletName, + Servlet servlet); + + /** + * @param servletName + * @param servletClass + * @return TODO + * @throws IllegalStateException + * If the context has already been initialised + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public ServletRegistration.Dynamic addServlet(String servletName, + Class servletClass); + + /** + * @param c + * @return TODO + * @throws ServletException + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public T createServlet(Class c) + throws ServletException; + + /** + * Obtain the details of the named servlet. + * + * @param servletName The name of the Servlet of interest + * + * @return The registration details for the named Servlet or + * null if no Servlet has been registered with the + * given name + * + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * + * @since Servlet 3.0 + */ + public ServletRegistration getServletRegistration(String servletName); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public Map getServletRegistrations(); + + /** + * @param filterName + * @param className + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public FilterRegistration.Dynamic addFilter(String filterName, + String className); + + /** + * @param filterName + * @param filter + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public FilterRegistration.Dynamic addFilter(String filterName, Filter filter); + + /** + * @param filterName + * @param filterClass + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @throws IllegalStateException + * If the context has already been initialised + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public FilterRegistration.Dynamic addFilter(String filterName, + Class filterClass); + + /** + * @param c + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @throws ServletException + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public T createFilter(Class c) + throws ServletException; + + /** + * @param filterName + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public FilterRegistration getFilterRegistration(String filterName); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public Map getFilterRegistrations(); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public SessionCookieConfig getSessionCookieConfig(); + + /** + * @param sessionTrackingModes + * @throws IllegalArgumentException + * If sessionTrackingModes specifies + * {@link SessionTrackingMode#SSL} in combination with any other + * {@link SessionTrackingMode} + * @throws IllegalStateException + * If the context has already been initialised + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public void setSessionTrackingModes( + Set sessionTrackingModes); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public Set getDefaultSessionTrackingModes(); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public Set getEffectiveSessionTrackingModes(); + + /** + * @param className + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public void addListener(String className); + + /** + * @param + * @param t + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public void addListener(T t); + + /** + * @param listenerClass + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public void addListener(Class listenerClass); + + /** + * @param + * @param c + * @return TODO + * @throws ServletException + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public T createListener(Class c) + throws ServletException; + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public JspConfigDescriptor getJspConfigDescriptor(); + + /** + * @return TODO + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @throws SecurityException + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public ClassLoader getClassLoader(); + + /** + * @param roleNames + * @throws UnsupportedOperationException If called from a + * {@link ServletContextListener#contextInitialized(ServletContextEvent)} + * method of a {@link ServletContextListener} that was not defined in a + * web.xml file, a web-fragment.xml file nor annotated with + * {@link javax.servlet.annotation.WebListener}. For example, a + * {@link ServletContextListener} defined in a TLD would not be able to + * use this method. + * @throws IllegalArgumentException + * @throws IllegalStateException + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public void declareRoles(String... roleNames); + + /** + * Returns the primary name of the virtual host on which this context is + * deployed. The name may or may not be a valid host name. + */ + public String getVirtualServerName(); +} diff --git a/lib/servlet-api/javax/servlet/ServletContextAttributeEvent.java b/lib/servlet-api/javax/servlet/ServletContextAttributeEvent.java new file mode 100644 index 00000000..b1bf727a --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletContextAttributeEvent.java @@ -0,0 +1,59 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * This is the event class for notifications about changes to the attributes of + * the servlet context of a web application. + * + * @see ServletContextAttributeListener + * @since v 2.3 + */ +public class ServletContextAttributeEvent extends ServletContextEvent { + private static final long serialVersionUID = 1L; + + private final String name; + private final Object value; + + /** + * Construct a ServletContextAttributeEvent from the given context for the + * given attribute name and attribute value. + */ + public ServletContextAttributeEvent(ServletContext source, String name, + Object value) { + super(source); + this.name = name; + this.value = value; + } + + /** + * Return the name of the attribute that changed on the ServletContext. + */ + public String getName() { + return this.name; + } + + /** + * Returns the value of the attribute that has been added, removed, or + * replaced. If the attribute was added, this is the value of the attribute. + * If the attribute was removed, this is the value of the removed attribute. + * If the attribute was replaced, this is the old value of the attribute. + */ + public Object getValue() { + return this.value; + } +} diff --git a/lib/servlet-api/javax/servlet/ServletContextAttributeListener.java b/lib/servlet-api/javax/servlet/ServletContextAttributeListener.java new file mode 100644 index 00000000..60cd3abb --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletContextAttributeListener.java @@ -0,0 +1,49 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.util.EventListener; + +/** + * Implementations of this interface receive notifications of changes to the + * attribute list on the servlet context of a web application. To receive + * notification events, the implementation class must be configured in the + * deployment descriptor for the web application. + * + * @see ServletContextAttributeEvent + * @since v 2.3 + */ + +public interface ServletContextAttributeListener extends EventListener { + /** + * Notification that a new attribute was added to the servlet context. + * Called after the attribute is added. + */ + public void attributeAdded(ServletContextAttributeEvent scab); + + /** + * Notification that an existing attribute has been removed from the servlet + * context. Called after the attribute is removed. + */ + public void attributeRemoved(ServletContextAttributeEvent scab); + + /** + * Notification that an attribute on the servlet context has been replaced. + * Called after the attribute is replaced. + */ + public void attributeReplaced(ServletContextAttributeEvent scab); +} diff --git a/lib/servlet-api/javax/servlet/ServletContextEvent.java b/lib/servlet-api/javax/servlet/ServletContextEvent.java new file mode 100644 index 00000000..92a9120d --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletContextEvent.java @@ -0,0 +1,48 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * This is the event class for notifications about changes to the servlet + * context of a web application. + * + * @see ServletContextListener + * @since v 2.3 + */ +public class ServletContextEvent extends java.util.EventObject { + + private static final long serialVersionUID = 1L; + + /** + * Construct a ServletContextEvent from the given context. + * + * @param source + * - the ServletContext that is sending the event. + */ + public ServletContextEvent(ServletContext source) { + super(source); + } + + /** + * Return the ServletContext that changed. + * + * @return the ServletContext that sent the event. + */ + public ServletContext getServletContext() { + return (ServletContext) super.getSource(); + } +} diff --git a/lib/servlet-api/javax/servlet/ServletContextListener.java b/lib/servlet-api/javax/servlet/ServletContextListener.java new file mode 100644 index 00000000..7d1b8e62 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletContextListener.java @@ -0,0 +1,46 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.util.EventListener; + +/** + * Implementations of this interface receive notifications about changes to the + * servlet context of the web application they are part of. To receive + * notification events, the implementation class must be configured in the + * deployment descriptor for the web application. + * + * @see ServletContextEvent + * @since v 2.3 + */ + +public interface ServletContextListener extends EventListener { + + /** + ** Notification that the web application initialization process is starting. + * All ServletContextListeners are notified of context initialization before + * any filter or servlet in the web application is initialized. + */ + public void contextInitialized(ServletContextEvent sce); + + /** + ** Notification that the servlet context is about to be shut down. All + * servlets and filters have been destroy()ed before any + * ServletContextListeners are notified of context destruction. + */ + public void contextDestroyed(ServletContextEvent sce); +} diff --git a/lib/servlet-api/javax/servlet/ServletException.java b/lib/servlet-api/javax/servlet/ServletException.java new file mode 100644 index 00000000..96e3e5cb --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletException.java @@ -0,0 +1,91 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * Defines a general exception a servlet can throw when it encounters + * difficulty. + */ +public class ServletException extends Exception { + + private static final long serialVersionUID = 1L; + + /** + * Constructs a new servlet exception. + */ + public ServletException() { + super(); + } + + /** + * Constructs a new servlet exception with the specified message. The + * message can be written to the server log and/or displayed for the user. + * + * @param message + * a String specifying the text of the exception + * message + */ + public ServletException(String message) { + super(message); + } + + /** + * Constructs a new servlet exception when the servlet needs to throw an + * exception and include a message about the "root cause" exception that + * interfered with its normal operation, including a description message. + * + * @param message + * a String containing the text of the exception + * message + * @param rootCause + * the Throwable exception that interfered with the + * servlet's normal operation, making this servlet exception + * necessary + */ + public ServletException(String message, Throwable rootCause) { + super(message, rootCause); + } + + /** + * Constructs a new servlet exception when the servlet needs to throw an + * exception and include a message about the "root cause" exception that + * interfered with its normal operation. The exception's message is based on + * the localized message of the underlying exception. + *

+ * This method calls the getLocalizedMessage method on the + * Throwable exception to get a localized exception message. + * When subclassing ServletException, this method can be + * overridden to create an exception message designed for a specific locale. + * + * @param rootCause + * the Throwable exception that interfered with the + * servlet's normal operation, making the servlet exception + * necessary + */ + public ServletException(Throwable rootCause) { + super(rootCause); + } + + /** + * Returns the exception that caused this servlet exception. + * + * @return the Throwable that caused this servlet exception + */ + public Throwable getRootCause() { + return getCause(); + } +} diff --git a/lib/servlet-api/javax/servlet/ServletInputStream.java b/lib/servlet-api/javax/servlet/ServletInputStream.java new file mode 100644 index 00000000..d116e326 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletInputStream.java @@ -0,0 +1,117 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; +import java.io.InputStream; + +/** + * Provides an input stream for reading binary data from a client request, + * including an efficient readLine method for reading data one line + * at a time. With some protocols, such as HTTP POST and PUT, a + * ServletInputStream object can be used to read data sent from the + * client. + *

+ * A ServletInputStream object is normally retrieved via the + * {@link ServletRequest#getInputStream} method. + *

+ * This is an abstract class that a servlet container implements. Subclasses of + * this class must implement the java.io.InputStream.read() method. + * + * @see ServletRequest + */ +public abstract class ServletInputStream extends InputStream { + + /** + * Does nothing, because this is an abstract class. + */ + protected ServletInputStream() { + // NOOP + } + + /** + * Reads the input stream, one line at a time. Starting at an offset, reads + * bytes into an array, until it reads a certain number of bytes or reaches + * a newline character, which it reads into the array as well. + *

+ * This method returns -1 if it reaches the end of the input stream before + * reading the maximum number of bytes. + * + * @param b + * an array of bytes into which data is read + * @param off + * an integer specifying the character at which this method + * begins reading + * @param len + * an integer specifying the maximum number of bytes to read + * @return an integer specifying the actual number of bytes read, or -1 if + * the end of the stream is reached + * @exception IOException + * if an input or output exception has occurred + */ + public int readLine(byte[] b, int off, int len) throws IOException { + + if (len <= 0) { + return 0; + } + int count = 0, c; + + while ((c = read()) != -1) { + b[off++] = (byte) c; + count++; + if (c == '\n' || count == len) { + break; + } + } + return count > 0 ? count : -1; + } + + /** + * Returns true if all the data has been read from the stream, + * else false. + * + * @since Servlet 3.1 + */ + public abstract boolean isFinished(); + + /** + * Returns true if data can be read without blocking, else + * false. If this method is called and returns false, the + * container will invoke {@link ReadListener#onDataAvailable()} when data is + * available. + * + * @since Servlet 3.1 + */ + public abstract boolean isReady(); + + /** + * Sets the {@link ReadListener} for this {@link ServletInputStream} and + * thereby switches to non-blocking IO. It is only valid to switch to + * non-blocking IO within async processing or HTTP upgrade processing. + * + * @param listener The non-blocking IO read listener + * + * @throws IllegalStateException If this method is called if neither + * async nor HTTP upgrade is in progress or + * if the {@link ReadListener} has already + * been set + * @throws NullPointerException If listener is null + * + * @since Servlet 3.1 + */ + public abstract void setReadListener(ReadListener listener); +} diff --git a/lib/servlet-api/javax/servlet/ServletOutputStream.java b/lib/servlet-api/javax/servlet/ServletOutputStream.java new file mode 100644 index 00000000..3498e2d5 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletOutputStream.java @@ -0,0 +1,302 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.CharConversionException; +import java.io.IOException; +import java.io.OutputStream; +import java.text.MessageFormat; +import java.util.ResourceBundle; + +/** + * Provides an output stream for sending binary data to the client. A + * ServletOutputStream object is normally retrieved via the + * {@link ServletResponse#getOutputStream} method. + *

+ * This is an abstract class that the servlet container implements. Subclasses + * of this class must implement the java.io.OutputStream.write(int) + * method. + * + * @see ServletResponse + */ +public abstract class ServletOutputStream extends OutputStream { + + private static final String LSTRING_FILE = "javax.servlet.LocalStrings"; + private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE); + + /** + * Does nothing, because this is an abstract class. + */ + protected ServletOutputStream() { + // NOOP + } + + /** + * Writes a String to the client, without a carriage + * return-line feed (CRLF) character at the end. + * + * @param s + * the String to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(String s) throws IOException { + if (s == null) + s = "null"; + int len = s.length(); + for (int i = 0; i < len; i++) { + char c = s.charAt(i); + + // + // XXX NOTE: This is clearly incorrect for many strings, + // but is the only consistent approach within the current + // servlet framework. It must suffice until servlet output + // streams properly encode their output. + // + if ((c & 0xff00) != 0) { // high order byte must be zero + String errMsg = lStrings.getString("err.not_iso8859_1"); + Object[] errArgs = new Object[1]; + errArgs[0] = Character.valueOf(c); + errMsg = MessageFormat.format(errMsg, errArgs); + throw new CharConversionException(errMsg); + } + write(c); + } + } + + /** + * Writes a boolean value to the client, with no carriage + * return-line feed (CRLF) character at the end. + * + * @param b + * the boolean value to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(boolean b) throws IOException { + String msg; + if (b) { + msg = lStrings.getString("value.true"); + } else { + msg = lStrings.getString("value.false"); + } + print(msg); + } + + /** + * Writes a character to the client, with no carriage return-line feed + * (CRLF) at the end. + * + * @param c + * the character to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(char c) throws IOException { + print(String.valueOf(c)); + } + + /** + * Writes an int to the client, with no carriage return-line feed (CRLF) at + * the end. + * + * @param i + * the int to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(int i) throws IOException { + print(String.valueOf(i)); + } + + /** + * Writes a long value to the client, with no carriage + * return-line feed (CRLF) at the end. + * + * @param l + * the long value to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(long l) throws IOException { + print(String.valueOf(l)); + } + + /** + * Writes a float value to the client, with no carriage + * return-line feed (CRLF) at the end. + * + * @param f + * the float value to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(float f) throws IOException { + print(String.valueOf(f)); + } + + /** + * Writes a double value to the client, with no carriage + * return-line feed (CRLF) at the end. + * + * @param d + * the double value to send to the client + * @exception IOException + * if an input or output exception occurred + */ + public void print(double d) throws IOException { + print(String.valueOf(d)); + } + + /** + * Writes a carriage return-line feed (CRLF) to the client. + * + * @exception IOException + * if an input or output exception occurred + */ + public void println() throws IOException { + print("\r\n"); + } + + /** + * Writes a String to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param s + * the String to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(String s) throws IOException { + print(s); + println(); + } + + /** + * Writes a boolean value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param b + * the boolean value to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(boolean b) throws IOException { + print(b); + println(); + } + + /** + * Writes a character to the client, followed by a carriage return-line feed + * (CRLF). + * + * @param c + * the character to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(char c) throws IOException { + print(c); + println(); + } + + /** + * Writes an int to the client, followed by a carriage return-line feed + * (CRLF) character. + * + * @param i + * the int to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(int i) throws IOException { + print(i); + println(); + } + + /** + * Writes a long value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param l + * the long value to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(long l) throws IOException { + print(l); + println(); + } + + /** + * Writes a float value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param f + * the float value to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(float f) throws IOException { + print(f); + println(); + } + + /** + * Writes a double value to the client, followed by a carriage + * return-line feed (CRLF). + * + * @param d + * the double value to write to the client + * @exception IOException + * if an input or output exception occurred + */ + public void println(double d) throws IOException { + print(d); + println(); + } + + /** + * Checks if a non-blocking write will succeed. If this returns + * false, it will cause a callback to + * {@link WriteListener#onWritePossible()} when the buffer has emptied. If + * this method returns false no further data must be written + * until the contain calls {@link WriteListener#onWritePossible()}. + * + * @return true if data can be written, else false + * + * @since Servlet 3.1 + */ + public abstract boolean isReady(); + + /** + * Sets the {@link WriteListener} for this {@link ServletOutputStream} and + * thereby switches to non-blocking IO. It is only valid to switch to + * non-blocking IO within async processing or HTTP upgrade processing. + * + * @param listener The non-blocking IO write listener + * + * @throws IllegalStateException If this method is called if neither + * async nor HTTP upgrade is in progress or + * if the {@link WriteListener} has already + * been set + * @throws NullPointerException If listener is null + * + * @since Servlet 3.1 + */ + public abstract void setWriteListener(javax.servlet.WriteListener listener); +} diff --git a/lib/servlet-api/javax/servlet/ServletRegistration.java b/lib/servlet-api/javax/servlet/ServletRegistration.java new file mode 100644 index 00000000..a0b5b349 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRegistration.java @@ -0,0 +1,49 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.Collection; +import java.util.Set; + +/** + * TODO SERVLET3 - Add comments + * @since Servlet 3.0 + */ +public interface ServletRegistration extends Registration { + + /** + * + * @param urlPatterns + * @return TODO + * @throws IllegalArgumentException if urlPattern is null or empty + * @throws IllegalStateException if the associated ServletContext has + * already been initialised + */ + public Set addMapping(String... urlPatterns); + + public Collection getMappings(); + + public String getRunAsRole(); + + public static interface Dynamic + extends ServletRegistration, Registration.Dynamic { + public void setLoadOnStartup(int loadOnStartup); + public void setMultipartConfig(MultipartConfigElement multipartConfig); + public void setRunAsRole(String roleName); + public Set setServletSecurity(ServletSecurityElement constraint); + } +} diff --git a/lib/servlet-api/javax/servlet/ServletRequest.java b/lib/servlet-api/javax/servlet/ServletRequest.java new file mode 100644 index 00000000..f32dff3c --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequest.java @@ -0,0 +1,492 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.BufferedReader; +import java.io.IOException; +import java.util.Enumeration; +import java.util.Locale; +import java.util.Map; + +/** + * Defines an object to provide client request information to a servlet. The + * servlet container creates a ServletRequest object and passes it + * as an argument to the servlet's service method. + *

+ * A ServletRequest object provides data including parameter name + * and values, attributes, and an input stream. Interfaces that extend + * ServletRequest can provide additional protocol-specific data + * (for example, HTTP data is provided by + * {@link javax.servlet.http.HttpServletRequest}. + * + * @see javax.servlet.http.HttpServletRequest + */ +public interface ServletRequest { + + /** + * Returns the value of the named attribute as an Object, or + * null if no attribute of the given name exists. + *

+ * Attributes can be set two ways. The servlet container may set attributes + * to make available custom information about a request. For example, for + * requests made using HTTPS, the attribute + * javax.servlet.request.X509Certificate can be used to + * retrieve information on the certificate of the client. Attributes can + * also be set programatically using {@link ServletRequest#setAttribute}. + * This allows information to be embedded into a request before a + * {@link RequestDispatcher} call. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.* and javax.* are + * reserved for use by the Servlet specification. Names beginning with + * sun.*, com.sun.*, oracle.* and + * com.oracle.*) are reserved for use by Oracle Corporation. + * + * @param name + * a String specifying the name of the attribute + * @return an Object containing the value of the attribute, or + * null if the attribute does not exist + */ + public Object getAttribute(String name); + + /** + * Returns an Enumeration containing the names of the + * attributes available to this request. This method returns an empty + * Enumeration if the request has no attributes available to + * it. + * + * @return an Enumeration of strings containing the names of the + * request's attributes + */ + public Enumeration getAttributeNames(); + + /** + * Returns the name of the character encoding used in the body of this + * request. This method returns null if the request does not + * specify a character encoding + * + * @return a String containing the name of the character + * encoding, or null if the request does not specify a + * character encoding + */ + public String getCharacterEncoding(); + + /** + * Overrides the name of the character encoding used in the body of this + * request. This method must be called prior to reading request parameters + * or reading input using getReader(). + * + * @param env + * a String containing the name of the character + * encoding. + * @throws java.io.UnsupportedEncodingException + * if this is not a valid encoding + */ + public void setCharacterEncoding(String env) + throws java.io.UnsupportedEncodingException; + + /** + * Returns the length, in bytes, of the request body and made available by + * the input stream, or -1 if the length is not known. For HTTP servlets, + * same as the value of the CGI variable CONTENT_LENGTH. + * + * @return an integer containing the length of the request body or -1 if the + * length is not known or is greater than {@link Integer#MAX_VALUE} + */ + public int getContentLength(); + + /** + * Returns the length, in bytes, of the request body and made available by + * the input stream, or -1 if the length is not known. For HTTP servlets, + * same as the value of the CGI variable CONTENT_LENGTH. + * + * @return a long integer containing the length of the request body or -1 if + * the length is not known + */ + public long getContentLengthLong(); + + /** + * Returns the MIME type of the body of the request, or null if + * the type is not known. For HTTP servlets, same as the value of the CGI + * variable CONTENT_TYPE. + * + * @return a String containing the name of the MIME type of the + * request, or null if the type is not known + */ + public String getContentType(); + + /** + * Retrieves the body of the request as binary data using a + * {@link ServletInputStream}. Either this method or {@link #getReader} may + * be called to read the body, not both. + * + * @return a {@link ServletInputStream} object containing the body of the + * request + * @exception IllegalStateException + * if the {@link #getReader} method has already been called + * for this request + * @exception IOException + * if an input or output exception occurred + */ + public ServletInputStream getInputStream() throws IOException; + + /** + * Returns the value of a request parameter as a String, or + * null if the parameter does not exist. Request parameters are + * extra information sent with the request. For HTTP servlets, parameters + * are contained in the query string or posted form data. + *

+ * You should only use this method when you are sure the parameter has only + * one value. If the parameter might have more than one value, use + * {@link #getParameterValues}. + *

+ * If you use this method with a multivalued parameter, the value returned + * is equal to the first value in the array returned by + * getParameterValues. + *

+ * If the parameter data was sent in the request body, such as occurs with + * an HTTP POST request, then reading the body directly via + * {@link #getInputStream} or {@link #getReader} can interfere with the + * execution of this method. + * + * @param name + * a String specifying the name of the parameter + * @return a String representing the single value of the + * parameter + * @see #getParameterValues + */ + public String getParameter(String name); + + /** + * Returns an Enumeration of String objects + * containing the names of the parameters contained in this request. If the + * request has no parameters, the method returns an empty + * Enumeration. + * + * @return an Enumeration of String objects, each + * String containing the name of a request parameter; + * or an empty Enumeration if the request has no + * parameters + */ + public Enumeration getParameterNames(); + + /** + * Returns an array of String objects containing all of the + * values the given request parameter has, or null if the + * parameter does not exist. + *

+ * If the parameter has a single value, the array has a length of 1. + * + * @param name + * a String containing the name of the parameter + * whose value is requested + * @return an array of String objects containing the parameter's + * values + * @see #getParameter + */ + public String[] getParameterValues(String name); + + /** + * Returns a java.util.Map of the parameters of this request. Request + * parameters are extra information sent with the request. For HTTP + * servlets, parameters are contained in the query string or posted form + * data. + * + * @return an immutable java.util.Map containing parameter names as keys and + * parameter values as map values. The keys in the parameter map are + * of type String. The values in the parameter map are of type + * String array. + */ + public Map getParameterMap(); + + /** + * Returns the name and version of the protocol the request uses in the form + * protocol/majorVersion.minorVersion, for example, HTTP/1.1. For + * HTTP servlets, the value returned is the same as the value of the CGI + * variable SERVER_PROTOCOL. + * + * @return a String containing the protocol name and version + * number + */ + public String getProtocol(); + + /** + * Returns the name of the scheme used to make this request, for example, + * http, https, or ftp. Different + * schemes have different rules for constructing URLs, as noted in RFC 1738. + * + * @return a String containing the name of the scheme used to + * make this request + */ + public String getScheme(); + + /** + * Returns the host name of the server to which the request was sent. It is + * the value of the part before ":" in the Host header value, + * if any, or the resolved server name, or the server IP address. + * + * @return a String containing the name of the server + */ + public String getServerName(); + + /** + * Returns the port number to which the request was sent. It is the value of + * the part after ":" in the Host header value, if any, or the + * server port where the client connection was accepted on. + * + * @return an integer specifying the port number + */ + public int getServerPort(); + + /** + * Retrieves the body of the request as character data using a + * BufferedReader. The reader translates the character data + * according to the character encoding used on the body. Either this method + * or {@link #getInputStream} may be called to read the body, not both. + * + * @return a BufferedReader containing the body of the request + * @exception java.io.UnsupportedEncodingException + * if the character set encoding used is not supported and + * the text cannot be decoded + * @exception IllegalStateException + * if {@link #getInputStream} method has been called on this + * request + * @exception IOException + * if an input or output exception occurred + * @see #getInputStream + */ + public BufferedReader getReader() throws IOException; + + /** + * Returns the Internet Protocol (IP) address of the client or last proxy + * that sent the request. For HTTP servlets, same as the value of the CGI + * variable REMOTE_ADDR. + * + * @return a String containing the IP address of the client + * that sent the request + */ + public String getRemoteAddr(); + + /** + * Returns the fully qualified name of the client or the last proxy that + * sent the request. If the engine cannot or chooses not to resolve the + * hostname (to improve performance), this method returns the dotted-string + * form of the IP address. For HTTP servlets, same as the value of the CGI + * variable REMOTE_HOST. + * + * @return a String containing the fully qualified name of the + * client + */ + public String getRemoteHost(); + + /** + * Stores an attribute in this request. Attributes are reset between + * requests. This method is most often used in conjunction with + * {@link RequestDispatcher}. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.* and javax.* are + * reserved for use by the Servlet specification. Names beginning with + * sun.*, com.sun.*, oracle.* and + * com.oracle.*) are reserved for use by Oracle Corporation. + *
+ * If the object passed in is null, the effect is the same as calling + * {@link #removeAttribute}.
+ * It is warned that when the request is dispatched from the servlet resides + * in a different web application by RequestDispatcher, the + * object set by this method may not be correctly retrieved in the caller + * servlet. + * + * @param name + * a String specifying the name of the attribute + * @param o + * the Object to be stored + */ + public void setAttribute(String name, Object o); + + /** + * Removes an attribute from this request. This method is not generally + * needed as attributes only persist as long as the request is being + * handled. + *

+ * Attribute names should follow the same conventions as package names. + * Names beginning with java.* and javax.* are + * reserved for use by the Servlet specification. Names beginning with + * sun.*, com.sun.*, oracle.* and + * com.oracle.*) are reserved for use by Oracle Corporation. + * + * @param name + * a String specifying the name of the attribute to + * remove + */ + public void removeAttribute(String name); + + /** + * Returns the preferred Locale that the client will accept + * content in, based on the Accept-Language header. If the client request + * doesn't provide an Accept-Language header, this method returns the + * default locale for the server. + * + * @return the preferred Locale for the client + */ + public Locale getLocale(); + + /** + * Returns an Enumeration of Locale objects + * indicating, in decreasing order starting with the preferred locale, the + * locales that are acceptable to the client based on the Accept-Language + * header. If the client request doesn't provide an Accept-Language header, + * this method returns an Enumeration containing one + * Locale, the default locale for the server. + * + * @return an Enumeration of preferred Locale + * objects for the client + */ + public Enumeration getLocales(); + + /** + * Returns a boolean indicating whether this request was made using a secure + * channel, such as HTTPS. + * + * @return a boolean indicating if the request was made using a secure + * channel + */ + public boolean isSecure(); + + /** + * Returns a {@link RequestDispatcher} object that acts as a wrapper for the + * resource located at the given path. A RequestDispatcher + * object can be used to forward a request to the resource or to include the + * resource in a response. The resource can be dynamic or static. + *

+ * The pathname specified may be relative, although it cannot extend outside + * the current servlet context. If the path begins with a "/" it is + * interpreted as relative to the current context root. This method returns + * null if the servlet container cannot return a + * RequestDispatcher. + *

+ * The difference between this method and + * {@link ServletContext#getRequestDispatcher} is that this method can take + * a relative path. + * + * @param path + * a String specifying the pathname to the resource. + * If it is relative, it must be relative against the current + * servlet. + * @return a RequestDispatcher object that acts as a wrapper for + * the resource at the specified path, or null if the + * servlet container cannot return a RequestDispatcher + * @see RequestDispatcher + * @see ServletContext#getRequestDispatcher + */ + public RequestDispatcher getRequestDispatcher(String path); + + /** + * @deprecated As of Version 2.1 of the Java Servlet API, use + * {@link ServletContext#getRealPath} instead. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String getRealPath(String path); + + /** + * Returns the Internet Protocol (IP) source port of the client or last + * proxy that sent the request. + * + * @return an integer specifying the port number + * @since 2.4 + */ + public int getRemotePort(); + + /** + * Returns the host name of the Internet Protocol (IP) interface on which + * the request was received. + * + * @return a String containing the host name of the IP on which + * the request was received. + * @since 2.4 + */ + public String getLocalName(); + + /** + * Returns the Internet Protocol (IP) address of the interface on which the + * request was received. + * + * @return a String containing the IP address on which the + * request was received. + * @since 2.4 + */ + public String getLocalAddr(); + + /** + * Returns the Internet Protocol (IP) port number of the interface on which + * the request was received. + * + * @return an integer specifying the port number + * @since 2.4 + */ + public int getLocalPort(); + + /** + * @return TODO + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public ServletContext getServletContext(); + + /** + * @return TODO + * @throws java.lang.IllegalStateException + * If async is not supported for this request + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public AsyncContext startAsync() throws IllegalStateException; + + /** + * @param servletRequest + * @param servletResponse + * @return TODO + * @throws java.lang.IllegalStateException + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public AsyncContext startAsync(ServletRequest servletRequest, + ServletResponse servletResponse) throws IllegalStateException; + + /** + * @return TODO + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean isAsyncStarted(); + + /** + * @return TODO + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean isAsyncSupported(); + + /** + * @return TODO + * @throws java.lang.IllegalStateException + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public AsyncContext getAsyncContext(); + + /** + * @return TODO + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public DispatcherType getDispatcherType(); +} diff --git a/lib/servlet-api/javax/servlet/ServletRequestAttributeEvent.java b/lib/servlet-api/javax/servlet/ServletRequestAttributeEvent.java new file mode 100644 index 00000000..9b251841 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequestAttributeEvent.java @@ -0,0 +1,73 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * This is the event class for notifications of changes to the attributes of the + * servlet request in an application. + * + * @see ServletRequestAttributeListener + * @since Servlet 2.4 + */ +public class ServletRequestAttributeEvent extends ServletRequestEvent { + private static final long serialVersionUID = 1L; + + private final String name; + private final Object value; + + /** + * Construct a ServletRequestAttributeEvent giving the servlet context of + * this web application, the ServletRequest whose attributes are changing + * and the name and value of the attribute. + * + * @param sc + * the ServletContext that is sending the event. + * @param request + * the ServletRequest that is sending the event. + * @param name + * the name of the request attribute. + * @param value + * the value of the request attribute. + */ + public ServletRequestAttributeEvent(ServletContext sc, + ServletRequest request, String name, Object value) { + super(sc, request); + this.name = name; + this.value = value; + } + + /** + * Return the name of the attribute that changed on the ServletRequest. + * + * @return the name of the changed request attribute + */ + public String getName() { + return this.name; + } + + /** + * Returns the value of the attribute that has been added, removed or + * replaced. If the attribute was added, this is the value of the attribute. + * If the attribute was removed, this is the value of the removed attribute. + * If the attribute was replaced, this is the old value of the attribute. + * + * @return the value of the changed request attribute + */ + public Object getValue() { + return this.value; + } +} diff --git a/lib/servlet-api/javax/servlet/ServletRequestAttributeListener.java b/lib/servlet-api/javax/servlet/ServletRequestAttributeListener.java new file mode 100644 index 00000000..8d65fa12 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequestAttributeListener.java @@ -0,0 +1,50 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.EventListener; + + /** + * A ServletRequestAttributeListener can be implemented by the + * developer interested in being notified of request attribute + * changes. Notifications will be generated while the request + * is within the scope of the web application in which the listener + * is registered. A request is defined as coming into scope when + * it is about to enter the first servlet or filter in each web + * application, as going out of scope when it exits the last servlet + * or the first filter in the chain. + * + * @since Servlet 2.4 + */ + +public interface ServletRequestAttributeListener extends EventListener { + /** Notification that a new attribute was added to the + ** servlet request. Called after the attribute is added. + */ + public void attributeAdded(ServletRequestAttributeEvent srae); + + /** Notification that an existing attribute has been removed from the + ** servlet request. Called after the attribute is removed. + */ + public void attributeRemoved(ServletRequestAttributeEvent srae); + + /** Notification that an attribute was replaced on the + ** servlet request. Called after the attribute is replaced. + */ + public void attributeReplaced(ServletRequestAttributeEvent srae); +} + diff --git a/lib/servlet-api/javax/servlet/ServletRequestEvent.java b/lib/servlet-api/javax/servlet/ServletRequestEvent.java new file mode 100644 index 00000000..5d95eab2 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequestEvent.java @@ -0,0 +1,58 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * Events of this kind indicate lifecycle events for a ServletRequest. The + * source of the event is the ServletContext of this web application. + * + * @see ServletRequestListener + * @since Servlet 2.4 + */ +public class ServletRequestEvent extends java.util.EventObject { + private static final long serialVersionUID = 1L; + + private final transient ServletRequest request; + + /** + * Construct a ServletRequestEvent for the given ServletContext and + * ServletRequest. + * + * @param sc + * the ServletContext of the web application. + * @param request + * the ServletRequest that is sending the event. + */ + public ServletRequestEvent(ServletContext sc, ServletRequest request) { + super(sc); + this.request = request; + } + + /** + * Returns the ServletRequest that is changing. + */ + public ServletRequest getServletRequest() { + return this.request; + } + + /** + * Returns the ServletContext of this web application. + */ + public ServletContext getServletContext() { + return (ServletContext) super.getSource(); + } +} diff --git a/lib/servlet-api/javax/servlet/ServletRequestListener.java b/lib/servlet-api/javax/servlet/ServletRequestListener.java new file mode 100644 index 00000000..4ac7055d --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequestListener.java @@ -0,0 +1,40 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +import java.util.EventListener; + + /** + * A ServletRequestListener can be implemented by the developer + * interested in being notified of requests coming in and out of + * scope in a web component. A request is defined as coming into + * scope when it is about to enter the first servlet or filter + * in each web application, as going out of scope when it exits + * the last servlet or the first filter in the chain. + * + * @since Servlet 2.4 + */ + + +public interface ServletRequestListener extends EventListener { + + /** The request is about to go out of scope of the web application. */ + public void requestDestroyed ( ServletRequestEvent sre ); + + /** The request is about to come into scope of the web application. */ + public void requestInitialized ( ServletRequestEvent sre ); +} diff --git a/lib/servlet-api/javax/servlet/ServletRequestWrapper.java b/lib/servlet-api/javax/servlet/ServletRequestWrapper.java new file mode 100644 index 00000000..308a29fb --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletRequestWrapper.java @@ -0,0 +1,458 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.BufferedReader; +import java.io.IOException; +import java.util.Enumeration; +import java.util.Locale; +import java.util.Map; + +/** + * Provides a convenient implementation of the ServletRequest interface that can + * be subclassed by developers wishing to adapt the request to a Servlet. This + * class implements the Wrapper or Decorator pattern. Methods default to calling + * through to the wrapped request object. + * + * @since v 2.3 + * @see javax.servlet.ServletRequest + */ +public class ServletRequestWrapper implements ServletRequest { + private ServletRequest request; + + /** + * Creates a ServletRequest adaptor wrapping the given request object. + * + * @throws java.lang.IllegalArgumentException + * if the request is null + */ + public ServletRequestWrapper(ServletRequest request) { + if (request == null) { + throw new IllegalArgumentException("Request cannot be null"); + } + this.request = request; + } + + /** + * Return the wrapped request object. + */ + public ServletRequest getRequest() { + return this.request; + } + + /** + * Sets the request object being wrapped. + * + * @throws java.lang.IllegalArgumentException + * if the request is null. + */ + public void setRequest(ServletRequest request) { + if (request == null) { + throw new IllegalArgumentException("Request cannot be null"); + } + this.request = request; + } + + /** + * The default behavior of this method is to call getAttribute(String name) + * on the wrapped request object. + */ + @Override + public Object getAttribute(String name) { + return this.request.getAttribute(name); + } + + /** + * The default behavior of this method is to return getAttributeNames() on + * the wrapped request object. + */ + @Override + public Enumeration getAttributeNames() { + return this.request.getAttributeNames(); + } + + /** + * The default behavior of this method is to return getCharacterEncoding() + * on the wrapped request object. + */ + @Override + public String getCharacterEncoding() { + return this.request.getCharacterEncoding(); + } + + /** + * The default behavior of this method is to set the character encoding on + * the wrapped request object. + */ + @Override + public void setCharacterEncoding(String enc) + throws java.io.UnsupportedEncodingException { + this.request.setCharacterEncoding(enc); + } + + /** + * The default behavior of this method is to return getContentLength() on + * the wrapped request object. + */ + @Override + public int getContentLength() { + return this.request.getContentLength(); + } + + @Override + public long getContentLengthLong() { + return this.request.getContentLengthLong(); + } + + /** + * The default behavior of this method is to return getContentType() on the + * wrapped request object. + */ + @Override + public String getContentType() { + return this.request.getContentType(); + } + + /** + * The default behavior of this method is to return getInputStream() on the + * wrapped request object. + */ + @Override + public ServletInputStream getInputStream() throws IOException { + return this.request.getInputStream(); + } + + /** + * The default behavior of this method is to return getParameter(String + * name) on the wrapped request object. + */ + @Override + public String getParameter(String name) { + return this.request.getParameter(name); + } + + /** + * The default behavior of this method is to return getParameterMap() on the + * wrapped request object. + */ + @Override + public Map getParameterMap() { + return this.request.getParameterMap(); + } + + /** + * The default behavior of this method is to return getParameterNames() on + * the wrapped request object. + */ + @Override + public Enumeration getParameterNames() { + return this.request.getParameterNames(); + } + + /** + * The default behavior of this method is to return + * getParameterValues(String name) on the wrapped request object. + */ + @Override + public String[] getParameterValues(String name) { + return this.request.getParameterValues(name); + } + + /** + * The default behavior of this method is to return getProtocol() on the + * wrapped request object. + */ + @Override + public String getProtocol() { + return this.request.getProtocol(); + } + + /** + * The default behavior of this method is to return getScheme() on the + * wrapped request object. + */ + @Override + public String getScheme() { + return this.request.getScheme(); + } + + /** + * The default behavior of this method is to return getServerName() on the + * wrapped request object. + */ + @Override + public String getServerName() { + return this.request.getServerName(); + } + + /** + * The default behavior of this method is to return getServerPort() on the + * wrapped request object. + */ + @Override + public int getServerPort() { + return this.request.getServerPort(); + } + + /** + * The default behavior of this method is to return getReader() on the + * wrapped request object. + */ + @Override + public BufferedReader getReader() throws IOException { + return this.request.getReader(); + } + + /** + * The default behavior of this method is to return getRemoteAddr() on the + * wrapped request object. + */ + @Override + public String getRemoteAddr() { + return this.request.getRemoteAddr(); + } + + /** + * The default behavior of this method is to return getRemoteHost() on the + * wrapped request object. + */ + @Override + public String getRemoteHost() { + return this.request.getRemoteHost(); + } + + /** + * The default behavior of this method is to return setAttribute(String + * name, Object o) on the wrapped request object. + */ + @Override + public void setAttribute(String name, Object o) { + this.request.setAttribute(name, o); + } + + /** + * The default behavior of this method is to call removeAttribute(String + * name) on the wrapped request object. + */ + @Override + public void removeAttribute(String name) { + this.request.removeAttribute(name); + } + + /** + * The default behavior of this method is to return getLocale() on the + * wrapped request object. + */ + @Override + public Locale getLocale() { + return this.request.getLocale(); + } + + /** + * The default behavior of this method is to return getLocales() on the + * wrapped request object. + */ + @Override + public Enumeration getLocales() { + return this.request.getLocales(); + } + + /** + * The default behavior of this method is to return isSecure() on the + * wrapped request object. + */ + @Override + public boolean isSecure() { + return this.request.isSecure(); + } + + /** + * The default behavior of this method is to return + * getRequestDispatcher(String path) on the wrapped request object. + */ + @Override + public RequestDispatcher getRequestDispatcher(String path) { + return this.request.getRequestDispatcher(path); + } + + /** + * The default behavior of this method is to return getRealPath(String path) + * on the wrapped request object. + * + * @deprecated As of Version 3.0 of the Java Servlet API + */ + @Override + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String getRealPath(String path) { + return this.request.getRealPath(path); + } + + /** + * The default behavior of this method is to return getRemotePort() on the + * wrapped request object. + * + * @since 2.4 + */ + @Override + public int getRemotePort() { + return this.request.getRemotePort(); + } + + /** + * The default behavior of this method is to return getLocalName() on the + * wrapped request object. + * + * @since 2.4 + */ + @Override + public String getLocalName() { + return this.request.getLocalName(); + } + + /** + * The default behavior of this method is to return getLocalAddr() on the + * wrapped request object. + * + * @since 2.4 + */ + @Override + public String getLocalAddr() { + return this.request.getLocalAddr(); + } + + /** + * The default behavior of this method is to return getLocalPort() on the + * wrapped request object. + * + * @since 2.4 + */ + @Override + public int getLocalPort() { + return this.request.getLocalPort(); + } + + /** + * The default behavior of this method is to return getServletContext() on + * the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public ServletContext getServletContext() { + return request.getServletContext(); + } + + /** + * The default behavior of this method is to return startAsync() on the + * wrapped request object. + * + * @throws java.lang.IllegalStateException + * @since Servlet 3.0 + */ + @Override + public AsyncContext startAsync() throws IllegalStateException { + return request.startAsync(); + } + + /** + * The default behavior of this method is to return startAsync(Runnable) on + * the wrapped request object. + * + * @param servletRequest + * @param servletResponse + * @throws java.lang.IllegalStateException + * @since Servlet 3.0 + */ + @Override + public AsyncContext startAsync(ServletRequest servletRequest, + ServletResponse servletResponse) throws IllegalStateException { + return request.startAsync(servletRequest, servletResponse); + } + + /** + * The default behavior of this method is to return isAsyncStarted() on the + * wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public boolean isAsyncStarted() { + return request.isAsyncStarted(); + } + + /** + * The default behavior of this method is to return isAsyncSupported() on + * the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public boolean isAsyncSupported() { + return request.isAsyncSupported(); + } + + /** + * The default behavior of this method is to return getAsyncContext() on the + * wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public AsyncContext getAsyncContext() { + return request.getAsyncContext(); + } + + /** + * @param wrapped + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean isWrapperFor(ServletRequest wrapped) { + if (request == wrapped) { + return true; + } + if (request instanceof ServletRequestWrapper) { + return ((ServletRequestWrapper) request).isWrapperFor(wrapped); + } + return false; + } + + /** + * @param wrappedType + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean isWrapperFor(Class wrappedType) { + if (wrappedType.isAssignableFrom(request.getClass())) { + return true; + } + if (request instanceof ServletRequestWrapper) { + return ((ServletRequestWrapper) request).isWrapperFor(wrappedType); + } + return false; + } + + /** + * The default behavior of this method is to call getDispatcherType() on the + * wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public DispatcherType getDispatcherType() { + return this.request.getDispatcherType(); + } +} diff --git a/lib/servlet-api/javax/servlet/ServletResponse.java b/lib/servlet-api/javax/servlet/ServletResponse.java new file mode 100644 index 00000000..f96e24e7 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletResponse.java @@ -0,0 +1,342 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; +import java.io.PrintWriter; +import java.util.Locale; + +/** + * Defines an object to assist a servlet in sending a response to the client. + * The servlet container creates a ServletResponse object and + * passes it as an argument to the servlet's service method. + *

+ * To send binary data in a MIME body response, use the + * {@link ServletOutputStream} returned by {@link #getOutputStream}. To send + * character data, use the PrintWriter object returned by + * {@link #getWriter}. To mix binary and text data, for example, to create a + * multipart response, use a ServletOutputStream and manage the + * character sections manually. + *

+ * The charset for the MIME body response can be specified explicitly using the + * {@link #setCharacterEncoding} and {@link #setContentType} methods, or + * implicitly using the {@link #setLocale} method. Explicit specifications take + * precedence over implicit specifications. If no charset is specified, + * ISO-8859-1 will be used. The setCharacterEncoding, + * setContentType, or setLocale method must be called + * before getWriter and before committing the response for the + * character encoding to be used. + *

+ * See the Internet RFCs such as + * RFC 2045 for more information on MIME. Protocols such as SMTP and HTTP + * define profiles of MIME, and those standards are still evolving. + * + * @see ServletOutputStream + */ +public interface ServletResponse { + + /** + * Returns the name of the character encoding (MIME charset) used for the + * body sent in this response. The character encoding may have been + * specified explicitly using the {@link #setCharacterEncoding} or + * {@link #setContentType} methods, or implicitly using the + * {@link #setLocale} method. Explicit specifications take precedence over + * implicit specifications. Calls made to these methods after + * getWriter has been called or after the response has been + * committed have no effect on the character encoding. If no character + * encoding has been specified, ISO-8859-1 is returned. + *

+ * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information + * about character encoding and MIME. + * + * @return a String specifying the name of the character + * encoding, for example, UTF-8 + */ + public String getCharacterEncoding(); + + /** + * Returns the content type used for the MIME body sent in this response. + * The content type proper must have been specified using + * {@link #setContentType} before the response is committed. If no content + * type has been specified, this method returns null. If a content type has + * been specified and a character encoding has been explicitly or implicitly + * specified as described in {@link #getCharacterEncoding}, the charset + * parameter is included in the string returned. If no character encoding + * has been specified, the charset parameter is omitted. + * + * @return a String specifying the content type, for example, + * text/html; charset=UTF-8, or null + * @since 2.4 + */ + public String getContentType(); + + /** + * Returns a {@link ServletOutputStream} suitable for writing binary data in + * the response. The servlet container does not encode the binary data. + *

+ * Calling flush() on the ServletOutputStream commits the response. Either + * this method or {@link #getWriter} may be called to write the body, not + * both. + * + * @return a {@link ServletOutputStream} for writing binary data + * @exception IllegalStateException + * if the getWriter method has been called on + * this response + * @exception IOException + * if an input or output exception occurred + * @see #getWriter + */ + public ServletOutputStream getOutputStream() throws IOException; + + /** + * Returns a PrintWriter object that can send character text to + * the client. The PrintWriter uses the character encoding + * returned by {@link #getCharacterEncoding}. If the response's character + * encoding has not been specified as described in + * getCharacterEncoding (i.e., the method just returns the + * default value ISO-8859-1), getWriter updates it + * to ISO-8859-1. + *

+ * Calling flush() on the PrintWriter commits the response. + *

+ * Either this method or {@link #getOutputStream} may be called to write the + * body, not both. + * + * @return a PrintWriter object that can return character data + * to the client + * @exception java.io.UnsupportedEncodingException + * if the character encoding returned by + * getCharacterEncoding cannot be used + * @exception IllegalStateException + * if the getOutputStream method has already + * been called for this response object + * @exception IOException + * if an input or output exception occurred + * @see #getOutputStream + * @see #setCharacterEncoding + */ + public PrintWriter getWriter() throws IOException; + + /** + * Sets the character encoding (MIME charset) of the response being sent to + * the client, for example, to UTF-8. If the character encoding has already + * been set by {@link #setContentType} or {@link #setLocale}, this method + * overrides it. Calling {@link #setContentType} with the + * String of text/html and calling this method + * with the String of UTF-8 is equivalent with + * calling setContentType with the String of + * text/html; charset=UTF-8. + *

+ * This method can be called repeatedly to change the character encoding. + * This method has no effect if it is called after getWriter + * has been called or after the response has been committed. + *

+ * Containers must communicate the character encoding used for the servlet + * response's writer to the client if the protocol provides a way for doing + * so. In the case of HTTP, the character encoding is communicated as part + * of the Content-Type header for text media types. Note that + * the character encoding cannot be communicated via HTTP headers if the + * servlet does not specify a content type; however, it is still used to + * encode text written via the servlet response's writer. + * + * @param charset + * a String specifying only the character set defined by IANA + * Character Sets + * (http://www.iana.org/assignments/character-sets) + * @see #setContentType #setLocale + * @since 2.4 + */ + public void setCharacterEncoding(String charset); + + /** + * Sets the length of the content body in the response In HTTP servlets, + * this method sets the HTTP Content-Length header. + * + * @param len + * an integer specifying the length of the content being returned + * to the client; sets the Content-Length header + */ + public void setContentLength(int len); + + /** + * TODO SERVLET 3.1 + */ + public void setContentLengthLong(long length); + + /** + * Sets the content type of the response being sent to the client, if the + * response has not been committed yet. The given content type may include a + * character encoding specification, for example, + * text/html;charset=UTF-8. The response's character encoding + * is only set from the given content type if this method is called before + * getWriter is called. + *

+ * This method may be called repeatedly to change content type and character + * encoding. This method has no effect if called after the response has been + * committed. It does not set the response's character encoding if it is + * called after getWriter has been called or after the response + * has been committed. + *

+ * Containers must communicate the content type and the character encoding + * used for the servlet response's writer to the client if the protocol + * provides a way for doing so. In the case of HTTP, the + * Content-Type header is used. + * + * @param type + * a String specifying the MIME type of the content + * @see #setLocale + * @see #setCharacterEncoding + * @see #getOutputStream + * @see #getWriter + */ + public void setContentType(String type); + + /** + * Sets the preferred buffer size for the body of the response. The servlet + * container will use a buffer at least as large as the size requested. The + * actual buffer size used can be found using getBufferSize. + *

+ * A larger buffer allows more content to be written before anything is + * actually sent, thus providing the servlet with more time to set + * appropriate status codes and headers. A smaller buffer decreases server + * memory load and allows the client to start receiving data more quickly. + *

+ * This method must be called before any response body content is written; + * if content has been written or the response object has been committed, + * this method throws an IllegalStateException. + * + * @param size + * the preferred buffer size + * @exception IllegalStateException + * if this method is called after content has been written + * @see #getBufferSize + * @see #flushBuffer + * @see #isCommitted + * @see #reset + */ + public void setBufferSize(int size); + + /** + * Returns the actual buffer size used for the response. If no buffering is + * used, this method returns 0. + * + * @return the actual buffer size used + * @see #setBufferSize + * @see #flushBuffer + * @see #isCommitted + * @see #reset + */ + public int getBufferSize(); + + /** + * Forces any content in the buffer to be written to the client. A call to + * this method automatically commits the response, meaning the status code + * and headers will be written. + * + * @see #setBufferSize + * @see #getBufferSize + * @see #isCommitted + * @see #reset + */ + public void flushBuffer() throws IOException; + + /** + * Clears the content of the underlying buffer in the response without + * clearing headers or status code. If the response has been committed, this + * method throws an IllegalStateException. + * + * @see #setBufferSize + * @see #getBufferSize + * @see #isCommitted + * @see #reset + * @since 2.3 + */ + public void resetBuffer(); + + /** + * Returns a boolean indicating if the response has been committed. A + * committed response has already had its status code and headers written. + * + * @return a boolean indicating if the response has been committed + * @see #setBufferSize + * @see #getBufferSize + * @see #flushBuffer + * @see #reset + */ + public boolean isCommitted(); + + /** + * Clears any data that exists in the buffer as well as the status code and + * headers. If the response has been committed, this method throws an + * IllegalStateException. + * + * @exception IllegalStateException + * if the response has already been committed + * @see #setBufferSize + * @see #getBufferSize + * @see #flushBuffer + * @see #isCommitted + */ + public void reset(); + + /** + * Sets the locale of the response, if the response has not been committed + * yet. It also sets the response's character encoding appropriately for the + * locale, if the character encoding has not been explicitly set using + * {@link #setContentType} or {@link #setCharacterEncoding}, + * getWriter hasn't been called yet, and the response hasn't + * been committed yet. If the deployment descriptor contains a + * locale-encoding-mapping-list element, and that element + * provides a mapping for the given locale, that mapping is used. Otherwise, + * the mapping from locale to character encoding is container dependent. + *

+ * This method may be called repeatedly to change locale and character + * encoding. The method has no effect if called after the response has been + * committed. It does not set the response's character encoding if it is + * called after {@link #setContentType} has been called with a charset + * specification, after {@link #setCharacterEncoding} has been called, after + * getWriter has been called, or after the response has been + * committed. + *

+ * Containers must communicate the locale and the character encoding used + * for the servlet response's writer to the client if the protocol provides + * a way for doing so. In the case of HTTP, the locale is communicated via + * the Content-Language header, the character encoding as part + * of the Content-Type header for text media types. Note that + * the character encoding cannot be communicated via HTTP headers if the + * servlet does not specify a content type; however, it is still used to + * encode text written via the servlet response's writer. + * + * @param loc + * the locale of the response + * @see #getLocale + * @see #setContentType + * @see #setCharacterEncoding + */ + public void setLocale(Locale loc); + + /** + * Returns the locale specified for this response using the + * {@link #setLocale} method. Calls made to setLocale after the + * response is committed have no effect. If no locale has been specified, + * the container's default locale is returned. + * + * @see #setLocale + */ + public Locale getLocale(); + +} diff --git a/lib/servlet-api/javax/servlet/ServletResponseWrapper.java b/lib/servlet-api/javax/servlet/ServletResponseWrapper.java new file mode 100644 index 00000000..9b440ddf --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletResponseWrapper.java @@ -0,0 +1,244 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; +import java.io.PrintWriter; +import java.util.Locale; + +/** + * Provides a convenient implementation of the ServletResponse interface that + * can be subclassed by developers wishing to adapt the response from a Servlet. + * This class implements the Wrapper or Decorator pattern. Methods default to + * calling through to the wrapped response object. + * + * @since v 2.3 + * @see javax.servlet.ServletResponse + */ +public class ServletResponseWrapper implements ServletResponse { + private ServletResponse response; + + /** + * Creates a ServletResponse adaptor wrapping the given response object. + * + * @throws java.lang.IllegalArgumentException + * if the response is null. + */ + public ServletResponseWrapper(ServletResponse response) { + if (response == null) { + throw new IllegalArgumentException("Response cannot be null"); + } + this.response = response; + } + + /** + * Return the wrapped ServletResponse object. + */ + public ServletResponse getResponse() { + return this.response; + } + + /** + * Sets the response being wrapped. + * + * @throws java.lang.IllegalArgumentException + * if the response is null. + */ + public void setResponse(ServletResponse response) { + if (response == null) { + throw new IllegalArgumentException("Response cannot be null"); + } + this.response = response; + } + + /** + * The default behavior of this method is to call + * setCharacterEncoding(String charset) on the wrapped response object. + * + * @since 2.4 + */ + @Override + public void setCharacterEncoding(String charset) { + this.response.setCharacterEncoding(charset); + } + + /** + * The default behavior of this method is to return getCharacterEncoding() + * on the wrapped response object. + */ + @Override + public String getCharacterEncoding() { + return this.response.getCharacterEncoding(); + } + + /** + * The default behavior of this method is to return getOutputStream() on the + * wrapped response object. + */ + @Override + public ServletOutputStream getOutputStream() throws IOException { + return this.response.getOutputStream(); + } + + /** + * The default behavior of this method is to return getWriter() on the + * wrapped response object. + */ + @Override + public PrintWriter getWriter() throws IOException { + return this.response.getWriter(); + } + + /** + * The default behavior of this method is to call setContentLength(int len) + * on the wrapped response object. + */ + @Override + public void setContentLength(int len) { + this.response.setContentLength(len); + } + + /** + * The default behavior of this method is to call setContentLength(long len) + * on the wrapped response object. + */ + @Override + public void setContentLengthLong(long length) { + this.response.setContentLengthLong(length); + } + + /** + * The default behavior of this method is to call setContentType(String + * type) on the wrapped response object. + */ + @Override + public void setContentType(String type) { + this.response.setContentType(type); + } + + /** + * The default behavior of this method is to return getContentType() on the + * wrapped response object. + * + * @since 2.4 + */ + @Override + public String getContentType() { + return this.response.getContentType(); + } + + /** + * The default behavior of this method is to call setBufferSize(int size) on + * the wrapped response object. + */ + @Override + public void setBufferSize(int size) { + this.response.setBufferSize(size); + } + + /** + * The default behavior of this method is to return getBufferSize() on the + * wrapped response object. + */ + @Override + public int getBufferSize() { + return this.response.getBufferSize(); + } + + /** + * The default behavior of this method is to call flushBuffer() on the + * wrapped response object. + */ + @Override + public void flushBuffer() throws IOException { + this.response.flushBuffer(); + } + + /** + * The default behavior of this method is to return isCommitted() on the + * wrapped response object. + */ + @Override + public boolean isCommitted() { + return this.response.isCommitted(); + } + + /** + * The default behavior of this method is to call reset() on the wrapped + * response object. + */ + @Override + public void reset() { + this.response.reset(); + } + + /** + * The default behavior of this method is to call resetBuffer() on the + * wrapped response object. + */ + @Override + public void resetBuffer() { + this.response.resetBuffer(); + } + + /** + * The default behavior of this method is to call setLocale(Locale loc) on + * the wrapped response object. + */ + @Override + public void setLocale(Locale loc) { + this.response.setLocale(loc); + } + + /** + * The default behavior of this method is to return getLocale() on the + * wrapped response object. + */ + @Override + public Locale getLocale() { + return this.response.getLocale(); + } + + /** + * @param wrapped + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean isWrapperFor(ServletResponse wrapped) { + if (response == wrapped) { + return true; + } + if (response instanceof ServletResponseWrapper) { + return ((ServletResponseWrapper) response).isWrapperFor(wrapped); + } + return false; + } + + /** + * @param wrappedType + * @since Servlet 3.0 TODO SERVLET3 - Add comments + */ + public boolean isWrapperFor(Class wrappedType) { + if (wrappedType.isAssignableFrom(response.getClass())) { + return true; + } + if (response instanceof ServletResponseWrapper) { + return ((ServletResponseWrapper) response).isWrapperFor(wrappedType); + } + return false; + } + +} diff --git a/lib/servlet-api/javax/servlet/ServletSecurityElement.java b/lib/servlet-api/javax/servlet/ServletSecurityElement.java new file mode 100644 index 00000000..cf2832f0 --- /dev/null +++ b/lib/servlet-api/javax/servlet/ServletSecurityElement.java @@ -0,0 +1,135 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.util.ArrayList; +import java.util.Collection; +import java.util.HashMap; +import java.util.HashSet; +import java.util.List; +import java.util.Map; + +import javax.servlet.annotation.HttpMethodConstraint; +import javax.servlet.annotation.ServletSecurity; + +/** + * + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public class ServletSecurityElement extends HttpConstraintElement { + + private final Map methodConstraints = + new HashMap<>(); + + /** + * Use default HttpConstraint. + */ + public ServletSecurityElement() { + super(); + } + + /** + * Use specified HttpConstraintElement. + * @param httpConstraintElement + */ + public ServletSecurityElement(HttpConstraintElement httpConstraintElement) { + this (httpConstraintElement, null); + } + + /** + * Use specific constraints for specified methods and default + * HttpConstraintElement for all other methods. + * @param httpMethodConstraints + * @throws IllegalArgumentException if a method name is specified more than + * once + */ + public ServletSecurityElement( + Collection httpMethodConstraints) { + super(); + addHttpMethodConstraints(httpMethodConstraints); + } + + + /** + * Use specified HttpConstraintElement as default and specific constraints + * for specified methods. + * @param httpConstraintElement + * @param httpMethodConstraints + * @throws IllegalArgumentException if a method name is specified more than + */ + public ServletSecurityElement(HttpConstraintElement httpConstraintElement, + Collection httpMethodConstraints) { + super(httpConstraintElement.getEmptyRoleSemantic(), + httpConstraintElement.getTransportGuarantee(), + httpConstraintElement.getRolesAllowed()); + addHttpMethodConstraints(httpMethodConstraints); + } + + /** + * Create from an annotation. + * @param annotation + * @throws IllegalArgumentException if a method name is specified more than + */ + public ServletSecurityElement(ServletSecurity annotation) { + this(new HttpConstraintElement(annotation.value().value(), + annotation.value().transportGuarantee(), + annotation.value().rolesAllowed())); + + List l = new ArrayList<>(); + HttpMethodConstraint[] constraints = annotation.httpMethodConstraints(); + if (constraints != null) { + for (int i = 0; i < constraints.length; i++) { + HttpMethodConstraintElement e = + new HttpMethodConstraintElement(constraints[i].value(), + new HttpConstraintElement( + constraints[i].emptyRoleSemantic(), + constraints[i].transportGuarantee(), + constraints[i].rolesAllowed())); + l.add(e); + } + } + addHttpMethodConstraints(l); + } + + public Collection getHttpMethodConstraints() { + Collection result = new HashSet<>(); + result.addAll(methodConstraints.values()); + return result; + } + + public Collection getMethodNames() { + Collection result = new HashSet<>(); + result.addAll(methodConstraints.keySet()); + return result; + } + + private void addHttpMethodConstraints( + Collection httpMethodConstraints) { + if (httpMethodConstraints == null) { + return; + } + for (HttpMethodConstraintElement constraint : httpMethodConstraints) { + String method = constraint.getMethodName(); + if (methodConstraints.containsKey(method)) { + throw new IllegalArgumentException( + "Duplicate method name: " + method); + } + methodConstraints.put(method, constraint); + } + } +} diff --git a/lib/servlet-api/javax/servlet/SessionCookieConfig.java b/lib/servlet-api/javax/servlet/SessionCookieConfig.java new file mode 100644 index 00000000..11567c0d --- /dev/null +++ b/lib/servlet-api/javax/servlet/SessionCookieConfig.java @@ -0,0 +1,90 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * + * TODO SERVLET3 - Add comments + * @since Servlet 3.0 + */ +public interface SessionCookieConfig { + + /** + * + * @param name + * @throws IllegalStateException + */ + public void setName(String name); + + public String getName(); + + /** + * + * @param domain + * @throws IllegalStateException + */ + public void setDomain(String domain); + + public String getDomain(); + + /** + * + * @param path + * @throws IllegalStateException + */ + public void setPath(String path); + + public String getPath(); + + /** + * + * @param comment + * @throws IllegalStateException + */ + public void setComment(String comment); + + public String getComment(); + + /** + * + * @param httpOnly + * @throws IllegalStateException + */ + public void setHttpOnly(boolean httpOnly); + + public boolean isHttpOnly(); + + /** + * + * @param secure + * @throws IllegalStateException + */ + public void setSecure(boolean secure); + + public boolean isSecure(); + + /** + * Sets the maximum age. + * + * @param MaxAge the maximum age to set + * @throws IllegalStateException + */ + public void setMaxAge(int MaxAge); + + public int getMaxAge(); + +} diff --git a/lib/servlet-api/javax/servlet/SessionTrackingMode.java b/lib/servlet-api/javax/servlet/SessionTrackingMode.java new file mode 100644 index 00000000..c59fd0c9 --- /dev/null +++ b/lib/servlet-api/javax/servlet/SessionTrackingMode.java @@ -0,0 +1,26 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet; + +/** + * @since Servlet 3.0 + */ +public enum SessionTrackingMode { + COOKIE, + URL, + SSL +} diff --git a/lib/servlet-api/javax/servlet/SingleThreadModel.java b/lib/servlet-api/javax/servlet/SingleThreadModel.java new file mode 100644 index 00000000..6e8437e4 --- /dev/null +++ b/lib/servlet-api/javax/servlet/SingleThreadModel.java @@ -0,0 +1,44 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +/** + * Ensures that servlets handle only one request at a time. This interface has + * no methods. + *

+ * If a servlet implements this interface, you are guaranteed that no two + * threads will execute concurrently in the servlet's service + * method. The servlet container can make this guarantee by synchronizing access + * to a single instance of the servlet, or by maintaining a pool of servlet + * instances and dispatching each new request to a free servlet. + *

+ * Note that SingleThreadModel does not solve all thread safety issues. For + * example, session attributes and static variables can still be accessed by + * multiple requests on multiple threads at the same time, even when + * SingleThreadModel servlets are used. It is recommended that a developer take + * other means to resolve those issues instead of implementing this interface, + * such as avoiding the usage of an instance variable or synchronizing the block + * of the code accessing those resources. This interface is deprecated in + * Servlet API version 2.4. + * + * @deprecated As of Java Servlet API 2.4, with no direct replacement. + */ +@SuppressWarnings("dep-ann") +// Spec API does not use @Deprecated +public interface SingleThreadModel { + // No methods +} diff --git a/lib/servlet-api/javax/servlet/UnavailableException.java b/lib/servlet-api/javax/servlet/UnavailableException.java new file mode 100644 index 00000000..c03c6d25 --- /dev/null +++ b/lib/servlet-api/javax/servlet/UnavailableException.java @@ -0,0 +1,178 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet; + +/** + * Defines an exception that a servlet or filter throws to indicate that it is + * permanently or temporarily unavailable. + *

+ * When a servlet or filter is permanently unavailable, something is wrong with + * it, and it cannot handle requests until some action is taken. For example, a + * servlet might be configured incorrectly, or a filter's state may be + * corrupted. The component should log both the error and the corrective action + * that is needed. + *

+ * A servlet or filter is temporarily unavailable if it cannot handle requests + * momentarily due to some system-wide problem. For example, a third-tier server + * might not be accessible, or there may be insufficient memory or disk storage + * to handle requests. A system administrator may need to take corrective + * action. + *

+ * Servlet containers can safely treat both types of unavailable exceptions in + * the same way. However, treating temporary unavailability effectively makes + * the servlet container more robust. Specifically, the servlet container might + * block requests to the servlet or filter for a period of time suggested by the + * exception, rather than rejecting them until the servlet container restarts. + */ +public class UnavailableException extends ServletException { + + private static final long serialVersionUID = 1L; + + private final Servlet servlet; // what's unavailable + private final boolean permanent; // needs admin action? + private final int seconds; // unavailability estimate + + /** + * @param servlet + * the Servlet instance that is unavailable + * @param msg + * a String specifying the descriptive message + * @deprecated As of Java Servlet API 2.2, use + * {@link #UnavailableException(String)} instead. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public UnavailableException(Servlet servlet, String msg) { + super(msg); + this.servlet = servlet; + permanent = true; + this.seconds = 0; + } + + /** + * @param seconds + * an integer specifying the number of seconds the servlet + * expects to be unavailable; if zero or negative, indicates that + * the servlet can't make an estimate + * @param servlet + * the Servlet that is unavailable + * @param msg + * a String specifying the descriptive message, + * which can be written to a log file or displayed for the user. + * @deprecated As of Java Servlet API 2.2, use + * {@link #UnavailableException(String, int)} instead. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public UnavailableException(int seconds, Servlet servlet, String msg) { + super(msg); + this.servlet = servlet; + if (seconds <= 0) + this.seconds = -1; + else + this.seconds = seconds; + permanent = false; + } + + /** + * Constructs a new exception with a descriptive message indicating that the + * servlet is permanently unavailable. + * + * @param msg + * a String specifying the descriptive message + */ + public UnavailableException(String msg) { + super(msg); + seconds = 0; + servlet = null; + permanent = true; + } + + /** + * Constructs a new exception with a descriptive message indicating that the + * servlet is temporarily unavailable and giving an estimate of how long it + * will be unavailable. + *

+ * In some cases, the servlet cannot make an estimate. For example, the + * servlet might know that a server it needs is not running, but not be able + * to report how long it will take to be restored to functionality. This can + * be indicated with a negative or zero value for the seconds + * argument. + * + * @param msg + * a String specifying the descriptive message, + * which can be written to a log file or displayed for the user. + * @param seconds + * an integer specifying the number of seconds the servlet + * expects to be unavailable; if zero or negative, indicates that + * the servlet can't make an estimate + */ + public UnavailableException(String msg, int seconds) { + super(msg); + + if (seconds <= 0) + this.seconds = -1; + else + this.seconds = seconds; + servlet = null; + permanent = false; + } + + /** + * Returns a boolean indicating whether the servlet is + * permanently unavailable. If so, something is wrong with the servlet, and + * the system administrator must take some corrective action. + * + * @return true if the servlet is permanently unavailable; + * false if the servlet is available or temporarily + * unavailable + */ + public boolean isPermanent() { + return permanent; + } + + /** + * Returns the servlet that is reporting its unavailability. + * + * @return the Servlet object that is throwing the + * UnavailableException + * @deprecated As of Java Servlet API 2.2, with no replacement. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public Servlet getServlet() { + return servlet; + } + + /** + * Returns the number of seconds the servlet expects to be temporarily + * unavailable. + *

+ * If this method returns a negative number, the servlet is permanently + * unavailable or cannot provide an estimate of how long it will be + * unavailable. No effort is made to correct for the time elapsed since the + * exception was first reported. + * + * @return an integer specifying the number of seconds the servlet will be + * temporarily unavailable, or a negative number if the servlet is + * permanently unavailable or cannot make an estimate + */ + public int getUnavailableSeconds() { + return permanent ? -1 : seconds; + } +} diff --git a/lib/servlet-api/javax/servlet/WriteListener.java b/lib/servlet-api/javax/servlet/WriteListener.java new file mode 100644 index 00000000..488111f1 --- /dev/null +++ b/lib/servlet-api/javax/servlet/WriteListener.java @@ -0,0 +1,45 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet; + +import java.io.IOException; + +/** + * Receives notification of write events when using non-blocking IO. + * + * @since Servlet 3.1 + */ +public interface WriteListener extends java.util.EventListener{ + + /** + * Invoked when it it possible to write data without blocking. The container + * will invoke this method the first time for a request as soon as data can + * be written. Subsequent invocations will only occur if a call to + * {@link ServletOutputStream#isReady()} has returned false and it has since + * become possible to write data. + * + * @throws IOException + */ + public void onWritePossible() throws IOException; + + /** + * Invoked if an error occurs while writing the response. + * + * @param throwable + */ + public void onError(java.lang.Throwable throwable); +} \ No newline at end of file diff --git a/lib/servlet-api/javax/servlet/annotation/HandlesTypes.java b/lib/servlet-api/javax/servlet/annotation/HandlesTypes.java new file mode 100644 index 00000000..c5f26b03 --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/HandlesTypes.java @@ -0,0 +1,39 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This annotation is used to declare an array of application classes which are + * passed to a {@link javax.servlet.ServletContainerInitializer}. + * + * @since Servlet 3.0 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface HandlesTypes { + + /** + * @return array of classes + */ + Class[] value(); + +} diff --git a/lib/servlet-api/javax/servlet/annotation/HttpConstraint.java b/lib/servlet-api/javax/servlet/annotation/HttpConstraint.java new file mode 100644 index 00000000..fd4366c4 --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/HttpConstraint.java @@ -0,0 +1,69 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; +import javax.servlet.annotation.ServletSecurity.TransportGuarantee; + +/** + * This annotation represents the security constraints that are applied to all + * requests with HTTP protocol method types that are not otherwise represented + * by a corresponding {@link javax.servlet.annotation.HttpMethodConstraint} in a + * {@link javax.servlet.annotation.ServletSecurity} annotation. + * + * @since Servlet 3.0 + */ +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface HttpConstraint { + + /** + * The EmptyRoleSemantic determines the behaviour when the rolesAllowed list + * is empty. + * + * @return empty role semantic + */ + EmptyRoleSemantic value() default EmptyRoleSemantic.PERMIT; + + /** + * Determines whether SSL/TLS is required to process the current request. + * + * @return transport guarantee + */ + TransportGuarantee transportGuarantee() default TransportGuarantee.NONE; + + /** + * The authorized roles' names. The container may discard duplicate role + * names during processing of the annotation. N.B. The String "*" does not + * have a special meaning if it occurs as a role name. + * + * @return array of names. The array may be of zero length, in which case + * the EmptyRoleSemantic applies; the returned value determines + * whether access is to be permitted or denied regardless of the + * identity and authentication state in either case, PERMIT or DENY.
+ * Otherwise, when the array contains one or more role names access + * is permitted if the user a member of at least one of the named + * roles. The EmptyRoleSemantic is not applied in this case. + * + */ + String[] rolesAllowed() default {}; + +} diff --git a/lib/servlet-api/javax/servlet/annotation/HttpMethodConstraint.java b/lib/servlet-api/javax/servlet/annotation/HttpMethodConstraint.java new file mode 100644 index 00000000..84e7c1d0 --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/HttpMethodConstraint.java @@ -0,0 +1,74 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +import javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic; +import javax.servlet.annotation.ServletSecurity.TransportGuarantee; + +/** + * Specific security constraints can be applied to different types of request, + * differentiated by the HTTP protocol method type by using this annotation + * inside the {@link javax.servlet.annotation.ServletSecurity} annotation. + * + * @since Servlet 3.0 + * + */ +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface HttpMethodConstraint { + + /** + * HTTP Protocol method name (e.g. POST, PUT) + * + * @return method name + */ + String value(); + + /** + * The EmptyRoleSemantic determines the behaviour when the rolesAllowed list + * is empty. + * + * @return empty role semantic + */ + EmptyRoleSemantic emptyRoleSemantic() default EmptyRoleSemantic.PERMIT; + + /** + * Determines whether SSL/TLS is required to process the current request. + * + * @return transport guarantee + */ + TransportGuarantee transportGuarantee() default TransportGuarantee.NONE; + + /** + * The authorized roles' names. The container may discard duplicate role + * names during processing of the annotation. N.B. The String "*" does not + * have a special meaning if it occurs as a role name. + * + * @return array of names. The array may be of zero length, in which case + * the EmptyRoleSemantic applies; the returned value determines + * whether access is to be permitted or denied regardless of the + * identity and authentication state in either case, PERMIT or DENY.
+ * Otherwise, when the array contains one or more role names access + * is permitted if the user a member of at least one of the named + * roles. The EmptyRoleSemantic is not applied in this case. + */ + String[] rolesAllowed() default {}; +} diff --git a/lib/servlet-api/javax/servlet/annotation/MultipartConfig.java b/lib/servlet-api/javax/servlet/annotation/MultipartConfig.java new file mode 100644 index 00000000..a86f86ed --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/MultipartConfig.java @@ -0,0 +1,68 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This annotation is used to indicate that the {@link javax.servlet.Servlet} on + * which it is declared expects requests to made using the {@code + * multipart/form-data} MIME type.
+ *
+ * + * {@link javax.servlet.http.Part} components of a given {@code + * multipart/form-data} request are retrieved by a Servlet annotated with + * {@code MultipartConfig} by calling + * {@link javax.servlet.http.HttpServletRequest#getPart} or + * {@link javax.servlet.http.HttpServletRequest#getParts}.
+ *
+ * + * E.g. @WebServlet("/upload")}
+ * + * @MultipartConfig() public class UploadServlet extends + * HttpServlet ... }
+ * + * @since Servlet 3.0 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +public @interface MultipartConfig { + + /** + * @return location in which the Container stores temporary files + */ + String location() default ""; + + /** + * @return the maximum size allowed for uploaded files (in bytes) + */ + long maxFileSize() default -1L; + + /** + * @return the maximum size of the request allowed for {@code + * multipart/form-data} + */ + long maxRequestSize() default -1L; + + /** + * @return the size threshold at which the file will be written to the disk + */ + int fileSizeThreshold() default 0; +} diff --git a/lib/servlet-api/javax/servlet/annotation/ServletSecurity.java b/lib/servlet-api/javax/servlet/annotation/ServletSecurity.java new file mode 100644 index 00000000..7ed432ee --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/ServletSecurity.java @@ -0,0 +1,90 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Declare this annotation on a {@link javax.servlet.Servlet} implementation + * class to enforce security constraints on HTTP protocol requests.
+ * The container applies constraints to the URL patterns mapped to each Servlet + * which declares this annotation.
+ *
+ * + * @since Servlet 3.0 + */ +@Inherited +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface ServletSecurity { + + /** + * Represents the two possible values of the empty role semantic, active + * when a list of role names is empty. + */ + enum EmptyRoleSemantic { + + /** + * Access MUST be permitted, regardless of authentication state or + * identity + */ + PERMIT, + + /** + * Access MUST be denied, regardless of authentication state or identity + */ + DENY + } + + /** + * Represents the two possible values of data transport, encrypted or not. + */ + enum TransportGuarantee { + + /** + * User data must not be encrypted by the container during transport + */ + NONE, + + /** + * The container MUST encrypt user data during transport + */ + CONFIDENTIAL + } + + /** + * The default constraint to apply to requests not handled by specific + * method constraints + * + * @return http constraint + */ + HttpConstraint value() default @HttpConstraint; + + /** + * An array of HttpMethodContraint objects to which the security constraint + * will be applied + * + * @return array of http method constraint + */ + HttpMethodConstraint[] httpMethodConstraints() default {}; +} diff --git a/lib/servlet-api/javax/servlet/annotation/WebFilter.java b/lib/servlet-api/javax/servlet/annotation/WebFilter.java new file mode 100644 index 00000000..08cbfdbd --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/WebFilter.java @@ -0,0 +1,122 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +import javax.servlet.DispatcherType; + +/** + * The annotation used to declare a Servlet {@link javax.servlet.Filter}.
+ *
+ * + * This annotation will be processed by the container during deployment, the + * Filter class in which it is found will be created as per the configuration + * and applied to the URL patterns, {@link javax.servlet.Servlet}s and + * {@link javax.servlet.DispatcherType}s.
+ *
+ * + * If the name attribute is not defined, the fully qualified name of the class + * is used.
+ *
+ * + * At least one URL pattern MUST be declared in either the {@code value} or + * {@code urlPattern} attribute of the annotation, but not both.
+ *
+ * + * The {@code value} attribute is recommended for use when the URL pattern is + * the only attribute being set, otherwise the {@code urlPattern} attribute + * should be used.
+ *
+ * + * The annotated class MUST implement {@link javax.servlet.Filter}. + * + * E.g. + * + * @WebFilter("/path/*")
+ * public class AnExampleFilter implements Filter { ...
+ * + * @since Servlet 3.0 (Section 8.1.2) + * + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface WebFilter { + + /** + * @return description of the Filter, if present + */ + String description() default ""; + + /** + * @return display name of the Filter, if present + */ + String displayName() default ""; + + /** + * @return array of initialization params for this Filter + */ + WebInitParam[] initParams() default {}; + + /** + * @return name of the Filter, if present + */ + String filterName() default ""; + + /** + * @return small icon for this Filter, if present + */ + String smallIcon() default ""; + + /** + * @return the large icon for this Filter, if present + */ + String largeIcon() default ""; + + /** + * @return array of Servlet names to which this Filter applies + */ + String[] servletNames() default {}; + + /** + * A convenience method, to allow extremely simple annotation of a class. + * + * @return array of URL patterns + * @see #urlPatterns() + */ + String[] value() default {}; + + /** + * @return array of URL patterns to which this Filter applies + */ + String[] urlPatterns() default {}; + + /** + * @return array of DispatcherTypes to which this filter applies + */ + DispatcherType[] dispatcherTypes() default {DispatcherType.REQUEST}; + + /** + * @return asynchronous operation supported by this Filter + */ + boolean asyncSupported() default false; +} diff --git a/lib/servlet-api/javax/servlet/annotation/WebInitParam.java b/lib/servlet-api/javax/servlet/annotation/WebInitParam.java new file mode 100644 index 00000000..e5fb73f6 --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/WebInitParam.java @@ -0,0 +1,57 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * The annotation used to declare an initialization parameter on a + * {@link javax.servlet.Servlet} or {@link javax.servlet.Filter}, within a + * {@link javax.servlet.annotation.WebFilter} or + * {@link javax.servlet.annotation.WebServlet} annotation.
+ *
+ * + * E.g. + * &#064;WebServlet(name="TestServlet", urlPatterns={"/test"},initParams={&#064;WebInitParam(name="test", value="true")}) + * public class TestServlet extends HttpServlet { ...
+ * + * @since Servlet 3.0 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface WebInitParam { + + /** + * @return name of the initialization parameter + */ + String name(); + + /** + * @return value of the initialization parameter + */ + String value(); + + /** + * @return description of the initialization parameter + */ + String description() default ""; +} diff --git a/lib/servlet-api/javax/servlet/annotation/WebListener.java b/lib/servlet-api/javax/servlet/annotation/WebListener.java new file mode 100644 index 00000000..81f5ff74 --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/WebListener.java @@ -0,0 +1,54 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * The annotation used to declare a listener for various types of event, in a + * given web application context.
+ *
+ * + * The class annotated MUST implement one, (or more), of the following + * interfaces: {@link javax.servlet.http.HttpSessionAttributeListener}, + * {@link javax.servlet.http.HttpSessionListener}, + * {@link javax.servlet.ServletContextAttributeListener}, + * {@link javax.servlet.ServletContextListener}, + * {@link javax.servlet.ServletRequestAttributeListener}, + * {@link javax.servlet.ServletRequestListener} or + * {@link javax.servlet.http.HttpSessionIdListener} + *
+ * + * E.g. @WebListener
+ * public TestListener implements ServletContextListener {
+ * + * @since Servlet 3.0 + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface WebListener { + + /** + * @return description of the listener, if present + */ + String value() default ""; +} diff --git a/lib/servlet-api/javax/servlet/annotation/WebServlet.java b/lib/servlet-api/javax/servlet/annotation/WebServlet.java new file mode 100644 index 00000000..eebf8bac --- /dev/null +++ b/lib/servlet-api/javax/servlet/annotation/WebServlet.java @@ -0,0 +1,113 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * This annotation is used to declare the configuration of an + * {@link javax.servlet.Servlet}.
+ * + * If the name attribute is not defined, the fully qualified name of the class + * is used.
+ *
+ * + * At least one URL pattern MUST be declared in either the {@code value} or + * {@code urlPattern} attribute of the annotation, but not both.
+ *
+ * + * The {@code value} attribute is recommended for use when the URL pattern is + * the only attribute being set, otherwise the {@code urlPattern} attribute + * should be used.
+ *
+ * + * The class on which this annotation is declared MUST extend + * {@link javax.servlet.http.HttpServlet}.
+ *
+ * + * E.g. @WebServlet("/path")}
+ * public class TestServlet extends HttpServlet ... {
+ * + * E.g. + * @WebServlet(name="TestServlet", urlPatterns={"/path", "/alt"})
+ * public class TestServlet extends HttpServlet ... {
+ * + * @since Servlet 3.0 (Section 8.1.1) + * + */ +@Target({ElementType.TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface WebServlet { + + /** + * @return name of the Servlet + */ + String name() default ""; + + /** + * A convenience method, to allow extremely simple annotation of a class. + * + * @return array of URL patterns + * @see #urlPatterns() + */ + String[] value() default {}; + + /** + * @return array of URL patterns to which this Filter applies + */ + String[] urlPatterns() default {}; + + /** + * @return load on startup ordering hint + */ + int loadOnStartup() default -1; + + /** + * @return array of initialization params for this Servlet + */ + WebInitParam[] initParams() default {}; + + /** + * @return asynchronous operation supported by this Servlet + */ + boolean asyncSupported() default false; + + /** + * @return small icon for this Servlet, if present + */ + String smallIcon() default ""; + + /** + * @return large icon for this Servlet, if present + */ + String largeIcon() default ""; + + /** + * @return description of this Servlet, if present + */ + String description() default ""; + + /** + * @return display name of this Servlet, if present + */ + String displayName() default ""; +} diff --git a/lib/servlet-api/javax/servlet/descriptor/JspConfigDescriptor.java b/lib/servlet-api/javax/servlet/descriptor/JspConfigDescriptor.java new file mode 100644 index 00000000..27b3cc7f --- /dev/null +++ b/lib/servlet-api/javax/servlet/descriptor/JspConfigDescriptor.java @@ -0,0 +1,28 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.descriptor; + +import java.util.Collection; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public interface JspConfigDescriptor { + public Collection getTaglibs(); + public Collection getJspPropertyGroups(); +} diff --git a/lib/servlet-api/javax/servlet/descriptor/JspPropertyGroupDescriptor.java b/lib/servlet-api/javax/servlet/descriptor/JspPropertyGroupDescriptor.java new file mode 100644 index 00000000..ddee69b9 --- /dev/null +++ b/lib/servlet-api/javax/servlet/descriptor/JspPropertyGroupDescriptor.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.descriptor; + +import java.util.Collection; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public interface JspPropertyGroupDescriptor { + public Collection getUrlPatterns(); + public String getElIgnored(); + public String getPageEncoding(); + public String getScriptingInvalid(); + public String getIsXml(); + public Collection getIncludePreludes(); + public Collection getIncludeCodas(); + public String getDeferredSyntaxAllowedAsLiteral(); + public String getTrimDirectiveWhitespaces(); + public String getDefaultContentType(); + public String getBuffer(); + public String getErrorOnUndeclaredNamespace(); +} diff --git a/lib/servlet-api/javax/servlet/descriptor/TaglibDescriptor.java b/lib/servlet-api/javax/servlet/descriptor/TaglibDescriptor.java new file mode 100644 index 00000000..b2e8e98c --- /dev/null +++ b/lib/servlet-api/javax/servlet/descriptor/TaglibDescriptor.java @@ -0,0 +1,26 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.descriptor; + +/** + * @since Servlet 3.0 + * TODO SERVLET3 - Add comments + */ +public interface TaglibDescriptor { + public String getTaglibURI(); + public String getTaglibLocation(); +} diff --git a/lib/servlet-api/javax/servlet/http/Cookie.java b/lib/servlet-api/javax/servlet/http/Cookie.java new file mode 100644 index 00000000..17745556 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/Cookie.java @@ -0,0 +1,458 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.io.Serializable; +import java.text.MessageFormat; +import java.util.BitSet; +import java.util.Locale; +import java.util.ResourceBundle; + +/** + * Creates a cookie, a small amount of information sent by a servlet to a Web + * browser, saved by the browser, and later sent back to the server. A cookie's + * value can uniquely identify a client, so cookies are commonly used for + * session management. + *

+ * A cookie has a name, a single value, and optional attributes such as a + * comment, path and domain qualifiers, a maximum age, and a version number. + * Some Web browsers have bugs in how they handle the optional attributes, so + * use them sparingly to improve the interoperability of your servlets. + *

+ * The servlet sends cookies to the browser by using the + * {@link HttpServletResponse#addCookie} method, which adds fields to HTTP + * response headers to send cookies to the browser, one at a time. The browser + * is expected to support 20 cookies for each Web server, 300 cookies total, and + * may limit cookie size to 4 KB each. + *

+ * The browser returns cookies to the servlet by adding fields to HTTP request + * headers. Cookies can be retrieved from a request by using the + * {@link HttpServletRequest#getCookies} method. Several cookies might have the + * same name but different path attributes. + *

+ * Cookies affect the caching of the Web pages that use them. HTTP 1.0 does not + * cache pages that use cookies created with this class. This class does not + * support the cache control defined with HTTP 1.1. + *

+ * This class supports both the Version 0 (by Netscape) and Version 1 (by RFC + * 2109) cookie specifications. By default, cookies are created using Version 0 + * to ensure the best interoperability. + */ +public class Cookie implements Cloneable, Serializable { + + private static final CookieNameValidator validation; + static { + boolean strictNaming; + String prop = System.getProperty("org.apache.tomcat.util.http.ServerCookie.STRICT_NAMING"); + if (prop != null) { + strictNaming = Boolean.parseBoolean(prop); + } else { + strictNaming = Boolean.getBoolean("org.apache.catalina.STRICT_SERVLET_COMPLIANCE"); + } + + if (strictNaming) { + validation = new RFC2109Validator(); + } + else { + validation = new NetscapeValidator(); + } + } + + private static final long serialVersionUID = 1L; + + private final String name; + private String value; + + private int version = 0; // ;Version=1 ... means RFC 2109 style + + // + // Attributes encoded in the header's cookie fields. + // + private String comment; // ;Comment=VALUE ... describes cookie's use + private String domain; // ;Domain=VALUE ... domain that sees cookie + private int maxAge = -1; // ;Max-Age=VALUE ... cookies auto-expire + private String path; // ;Path=VALUE ... URLs that see the cookie + private boolean secure; // ;Secure ... e.g. use SSL + private boolean httpOnly; // Not in cookie specs, but supported by browsers + + /** + * Constructs a cookie with a specified name and value. + *

+ * The name must conform to RFC 2109. That means it can contain only ASCII + * alphanumeric characters and cannot contain commas, semicolons, or white + * space or begin with a $ character. The cookie's name cannot be changed + * after creation. + *

+ * The value can be anything the server chooses to send. Its value is + * probably of interest only to the server. The cookie's value can be + * changed after creation with the setValue method. + *

+ * By default, cookies are created according to the Netscape cookie + * specification. The version can be changed with the + * setVersion method. + * + * @param name + * a String specifying the name of the cookie + * @param value + * a String specifying the value of the cookie + * @throws IllegalArgumentException + * if the cookie name contains illegal characters (for example, + * a comma, space, or semicolon) or it is one of the tokens + * reserved for use by the cookie protocol + * @see #setValue + * @see #setVersion + */ + public Cookie(String name, String value) { + validation.validate(name); + this.name = name; + this.value = value; + } + + /** + * Specifies a comment that describes a cookie's purpose. The comment is + * useful if the browser presents the cookie to the user. Comments are not + * supported by Netscape Version 0 cookies. + * + * @param purpose + * a String specifying the comment to display to the + * user + * @see #getComment + */ + public void setComment(String purpose) { + comment = purpose; + } + + /** + * Returns the comment describing the purpose of this cookie, or + * null if the cookie has no comment. + * + * @return a String containing the comment, or + * null if none + * @see #setComment + */ + public String getComment() { + return comment; + } + + /** + * Specifies the domain within which this cookie should be presented. + *

+ * The form of the domain name is specified by RFC 2109. A domain name + * begins with a dot (.foo.com) and means that the cookie is + * visible to servers in a specified Domain Name System (DNS) zone (for + * example, www.foo.com, but not a.b.foo.com). By + * default, cookies are only returned to the server that sent them. + * + * @param pattern + * a String containing the domain name within which + * this cookie is visible; form is according to RFC 2109 + * @see #getDomain + */ + public void setDomain(String pattern) { + domain = pattern.toLowerCase(Locale.ENGLISH); // IE allegedly needs this + } + + /** + * Returns the domain name set for this cookie. The form of the domain name + * is set by RFC 2109. + * + * @return a String containing the domain name + * @see #setDomain + */ + public String getDomain() { + return domain; + } + + /** + * Sets the maximum age of the cookie in seconds. + *

+ * A positive value indicates that the cookie will expire after that many + * seconds have passed. Note that the value is the maximum age when + * the cookie will expire, not the cookie's current age. + *

+ * A negative value means that the cookie is not stored persistently and + * will be deleted when the Web browser exits. A zero value causes the + * cookie to be deleted. + * + * @param expiry + * an integer specifying the maximum age of the cookie in + * seconds; if negative, means the cookie is not stored; if zero, + * deletes the cookie + * @see #getMaxAge + */ + public void setMaxAge(int expiry) { + maxAge = expiry; + } + + /** + * Returns the maximum age of the cookie, specified in seconds, By default, + * -1 indicating the cookie will persist until browser + * shutdown. + * + * @return an integer specifying the maximum age of the cookie in seconds; if + * negative, means the cookie persists until browser shutdown + * @see #setMaxAge + */ + public int getMaxAge() { + return maxAge; + } + + /** + * Specifies a path for the cookie to which the client should return the + * cookie. + *

+ * The cookie is visible to all the pages in the directory you specify, and + * all the pages in that directory's subdirectories. A cookie's path must + * include the servlet that set the cookie, for example, /catalog, + * which makes the cookie visible to all directories on the server under + * /catalog. + *

+ * Consult RFC 2109 (available on the Internet) for more information on + * setting path names for cookies. + * + * @param uri + * a String specifying a path + * @see #getPath + */ + public void setPath(String uri) { + path = uri; + } + + /** + * Returns the path on the server to which the browser returns this cookie. + * The cookie is visible to all subpaths on the server. + * + * @return a String specifying a path that contains a servlet + * name, for example, /catalog + * @see #setPath + */ + public String getPath() { + return path; + } + + /** + * Indicates to the browser whether the cookie should only be sent using a + * secure protocol, such as HTTPS or SSL. + *

+ * The default value is false. + * + * @param flag + * if true, sends the cookie from the browser to the + * server only when using a secure protocol; if + * false, sent on any protocol + * @see #getSecure + */ + public void setSecure(boolean flag) { + secure = flag; + } + + /** + * Returns true if the browser is sending cookies only over a + * secure protocol, or false if the browser can send cookies + * using any protocol. + * + * @return true if the browser uses a secure protocol; + * otherwise, true + * @see #setSecure + */ + public boolean getSecure() { + return secure; + } + + /** + * Returns the name of the cookie. The name cannot be changed after + * creation. + * + * @return a String specifying the cookie's name + */ + public String getName() { + return name; + } + + /** + * Assigns a new value to a cookie after the cookie is created. If you use a + * binary value, you may want to use BASE64 encoding. + *

+ * With Version 0 cookies, values should not contain white space, brackets, + * parentheses, equals signs, commas, double quotes, slashes, question + * marks, at signs, colons, and semicolons. Empty values may not behave the + * same way on all browsers. + * + * @param newValue + * a String specifying the new value + * @see #getValue + * @see Cookie + */ + public void setValue(String newValue) { + value = newValue; + } + + /** + * Returns the value of the cookie. + * + * @return a String containing the cookie's present value + * @see #setValue + * @see Cookie + */ + public String getValue() { + return value; + } + + /** + * Returns the version of the protocol this cookie complies with. Version 1 + * complies with RFC 2109, and version 0 complies with the original cookie + * specification drafted by Netscape. Cookies provided by a browser use and + * identify the browser's cookie version. + * + * @return 0 if the cookie complies with the original Netscape specification; + * 1 if the cookie complies with RFC 2109 + * @see #setVersion + */ + public int getVersion() { + return version; + } + + /** + * Sets the version of the cookie protocol this cookie complies with. + * Version 0 complies with the original Netscape cookie specification. + * Version 1 complies with RFC 2109. + *

+ * Since RFC 2109 is still somewhat new, consider version 1 as experimental; + * do not use it yet on production sites. + * + * @param v + * 0 if the cookie should comply with the original Netscape + * specification; 1 if the cookie should comply with RFC 2109 + * @see #getVersion + */ + public void setVersion(int v) { + version = v; + } + + /** + * Overrides the standard java.lang.Object.clone method to + * return a copy of this cookie. + */ + @Override + public Object clone() { + try { + return super.clone(); + } catch (CloneNotSupportedException e) { + throw new RuntimeException(e.getMessage()); + } + } + + /** + * Sets the flag that controls if this cookie will be hidden from scripts on + * the client side. + * + * @param httpOnly The new value of the flag + * + * @since Servlet 3.0 + */ + public void setHttpOnly(boolean httpOnly) { + this.httpOnly = httpOnly; + } + + /** + * Gets the flag that controls if this cookie will be hidden from scripts on + * the client side. + * + * @return true if the cookie is hidden from scripts, else + * false + * @since Servlet 3.0 + */ + public boolean isHttpOnly() { + return httpOnly; + } +} + + +class CookieNameValidator { + private static final String LSTRING_FILE = "javax.servlet.http.LocalStrings"; + private static final ResourceBundle lStrings = ResourceBundle.getBundle(LSTRING_FILE); + + protected final BitSet allowed; + + protected CookieNameValidator(String separators) { + allowed = new BitSet(128); + allowed.set(0x20, 0x7f); // any CHAR except CTLs or separators + for (int i = 0; i < separators.length(); i++) { + char ch = separators.charAt(i); + allowed.clear(ch); + } + } + + void validate(String name) { + if (name == null || name.length() == 0) { + throw new IllegalArgumentException(lStrings.getString("err.cookie_name_blank")); + } + if (!isToken(name) || + name.equalsIgnoreCase("Comment") || + name.equalsIgnoreCase("Discard") || + name.equalsIgnoreCase("Domain") || + name.equalsIgnoreCase("Expires") || + name.equalsIgnoreCase("Max-Age") || + name.equalsIgnoreCase("Path") || + name.equalsIgnoreCase("Secure") || + name.equalsIgnoreCase("Version") || + name.startsWith("$")) { + String errMsg = lStrings.getString("err.cookie_name_is_token"); + throw new IllegalArgumentException(MessageFormat.format(errMsg, name)); + } + } + + private boolean isToken(String possibleToken) { + int len = possibleToken.length(); + + for (int i = 0; i < len; i++) { + char c = possibleToken.charAt(i); + if (!allowed.get(c)) { + return false; + } + } + return true; + } +} + +class NetscapeValidator extends CookieNameValidator { + private static final String NETSCAPE_SEPARATORS = ",; "; + + NetscapeValidator() { + super(NETSCAPE_SEPARATORS); + } +} + +class RFC2109Validator extends CookieNameValidator { + private static final String RFC2616_SEPARATORS = "()<>@,;:\\\"/[]?={} \t"; + + RFC2109Validator() { + super(RFC2616_SEPARATORS); + + // special treatment to allow for FWD_SLASH_IS_SEPARATOR property + boolean allowSlash; + String prop = System.getProperty("org.apache.tomcat.util.http.ServerCookie.FWD_SLASH_IS_SEPARATOR"); + if (prop != null) { + allowSlash = !Boolean.parseBoolean(prop); + } else { + allowSlash = !Boolean.getBoolean("org.apache.catalina.STRICT_SERVLET_COMPLIANCE"); + } + if (allowSlash) { + allowed.set('/'); + } + } +} diff --git a/lib/servlet-api/javax/servlet/http/HttpServlet.java b/lib/servlet-api/javax/servlet/http/HttpServlet.java new file mode 100644 index 00000000..f44ebcd8 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpServlet.java @@ -0,0 +1,881 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.io.IOException; +import java.io.OutputStreamWriter; +import java.io.PrintWriter; +import java.io.UnsupportedEncodingException; +import java.lang.reflect.Method; +import java.text.MessageFormat; +import java.util.Enumeration; +import java.util.ResourceBundle; + +import javax.servlet.GenericServlet; +import javax.servlet.ServletException; +import javax.servlet.ServletOutputStream; +import javax.servlet.ServletRequest; +import javax.servlet.ServletResponse; + + +/** + * Provides an abstract class to be subclassed to create + * an HTTP servlet suitable for a Web site. A subclass of + * HttpServlet must override at least + * one method, usually one of these: + * + *

    + *
  • doGet, if the servlet supports HTTP GET requests + *
  • doPost, for HTTP POST requests + *
  • doPut, for HTTP PUT requests + *
  • doDelete, for HTTP DELETE requests + *
  • init and destroy, + * to manage resources that are held for the life of the servlet + *
  • getServletInfo, which the servlet uses to + * provide information about itself + *
+ * + *

There's almost no reason to override the service + * method. service handles standard HTTP + * requests by dispatching them to the handler methods + * for each HTTP request type (the doMethod + * methods listed above). + * + *

Likewise, there's almost no reason to override the + * doOptions and doTrace methods. + * + *

Servlets typically run on multithreaded servers, + * so be aware that a servlet must handle concurrent + * requests and be careful to synchronize access to shared resources. + * Shared resources include in-memory data such as + * instance or class variables and external objects + * such as files, database connections, and network + * connections. + * See the + * + * Java Tutorial on Multithreaded Programming for more + * information on handling multiple threads in a Java program. + */ +public abstract class HttpServlet extends GenericServlet { + + private static final long serialVersionUID = 1L; + + private static final String METHOD_DELETE = "DELETE"; + private static final String METHOD_HEAD = "HEAD"; + private static final String METHOD_GET = "GET"; + private static final String METHOD_OPTIONS = "OPTIONS"; + private static final String METHOD_POST = "POST"; + private static final String METHOD_PUT = "PUT"; + private static final String METHOD_TRACE = "TRACE"; + + private static final String HEADER_IFMODSINCE = "If-Modified-Since"; + private static final String HEADER_LASTMOD = "Last-Modified"; + + private static final String LSTRING_FILE = + "javax.servlet.http.LocalStrings"; + private static final ResourceBundle lStrings = + ResourceBundle.getBundle(LSTRING_FILE); + + + /** + * Does nothing, because this is an abstract class. + */ + public HttpServlet() { + // NOOP + } + + + /** + * Called by the server (via the service method) to + * allow a servlet to handle a GET request. + * + *

Overriding this method to support a GET request also + * automatically supports an HTTP HEAD request. A HEAD + * request is a GET request that returns no body in the + * response, only the request header fields. + * + *

When overriding this method, read the request data, + * write the response headers, get the response's writer or + * output stream object, and finally, write the response data. + * It's best to include content type and encoding. When using + * a PrintWriter object to return the response, + * set the content type before accessing the + * PrintWriter object. + * + *

The servlet container must write the headers before + * committing the response, because in HTTP the headers must be sent + * before the response body. + * + *

Where possible, set the Content-Length header (with the + * {@link javax.servlet.ServletResponse#setContentLength} method), + * to allow the servlet container to use a persistent connection + * to return its response to the client, improving performance. + * The content length is automatically set if the entire response fits + * inside the response buffer. + * + *

When using HTTP 1.1 chunked encoding (which means that the response + * has a Transfer-Encoding header), do not set the Content-Length header. + * + *

The GET method should be safe, that is, without + * any side effects for which users are held responsible. + * For example, most form queries have no side effects. + * If a client request is intended to change stored data, + * the request should use some other HTTP method. + * + *

The GET method should also be idempotent, meaning + * that it can be safely repeated. Sometimes making a + * method safe also makes it idempotent. For example, + * repeating queries is both safe and idempotent, but + * buying a product online or modifying data is neither + * safe nor idempotent. + * + *

If the request is incorrectly formatted, doGet + * returns an HTTP "Bad Request" message. + * + * @param req an {@link HttpServletRequest} object that + * contains the request the client has made + * of the servlet + * + * @param resp an {@link HttpServletResponse} object that + * contains the response the servlet sends + * to the client + * + * @exception IOException if an input or output error is + * detected when the servlet handles + * the GET request + * + * @exception ServletException if the request for the GET + * could not be handled + * + * @see javax.servlet.ServletResponse#setContentType + */ + protected void doGet(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException + { + String protocol = req.getProtocol(); + String msg = lStrings.getString("http.method_get_not_supported"); + if (protocol.endsWith("1.1")) { + resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg); + } else { + resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg); + } + } + + + /** + * Returns the time the HttpServletRequest + * object was last modified, + * in milliseconds since midnight January 1, 1970 GMT. + * If the time is unknown, this method returns a negative + * number (the default). + * + *

Servlets that support HTTP GET requests and can quickly determine + * their last modification time should override this method. + * This makes browser and proxy caches work more effectively, + * reducing the load on server and network resources. + * + * @param req the HttpServletRequest + * object that is sent to the servlet + * + * @return a long integer specifying + * the time the HttpServletRequest + * object was last modified, in milliseconds + * since midnight, January 1, 1970 GMT, or + * -1 if the time is not known + */ + protected long getLastModified(HttpServletRequest req) { + return -1; + } + + + /** + *

Receives an HTTP HEAD request from the protected + * service method and handles the + * request. + * The client sends a HEAD request when it wants + * to see only the headers of a response, such as + * Content-Type or Content-Length. The HTTP HEAD + * method counts the output bytes in the response + * to set the Content-Length header accurately. + * + *

If you override this method, you can avoid computing + * the response body and just set the response headers + * directly to improve performance. Make sure that the + * doHead method you write is both safe + * and idempotent (that is, protects itself from being + * called multiple times for one HTTP HEAD request). + * + *

If the HTTP HEAD request is incorrectly formatted, + * doHead returns an HTTP "Bad Request" + * message. + * + * @param req the request object that is passed to the servlet + * + * @param resp the response object that the servlet + * uses to return the headers to the client + * + * @exception IOException if an input or output error occurs + * + * @exception ServletException if the request for the HEAD + * could not be handled + */ + protected void doHead(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException { + + NoBodyResponse response = new NoBodyResponse(resp); + + doGet(req, response); + response.setContentLength(); + } + + + /** + * Called by the server (via the service method) + * to allow a servlet to handle a POST request. + * + * The HTTP POST method allows the client to send + * data of unlimited length to the Web server a single time + * and is useful when posting information such as + * credit card numbers. + * + *

When overriding this method, read the request data, + * write the response headers, get the response's writer or output + * stream object, and finally, write the response data. It's best + * to include content type and encoding. When using a + * PrintWriter object to return the response, set the + * content type before accessing the PrintWriter object. + * + *

The servlet container must write the headers before committing the + * response, because in HTTP the headers must be sent before the + * response body. + * + *

Where possible, set the Content-Length header (with the + * {@link javax.servlet.ServletResponse#setContentLength} method), + * to allow the servlet container to use a persistent connection + * to return its response to the client, improving performance. + * The content length is automatically set if the entire response fits + * inside the response buffer. + * + *

When using HTTP 1.1 chunked encoding (which means that the response + * has a Transfer-Encoding header), do not set the Content-Length header. + * + *

This method does not need to be either safe or idempotent. + * Operations requested through POST can have side effects for + * which the user can be held accountable, for example, + * updating stored data or buying items online. + * + *

If the HTTP POST request is incorrectly formatted, + * doPost returns an HTTP "Bad Request" message. + * + * + * @param req an {@link HttpServletRequest} object that + * contains the request the client has made + * of the servlet + * + * @param resp an {@link HttpServletResponse} object that + * contains the response the servlet sends + * to the client + * + * @exception IOException if an input or output error is + * detected when the servlet handles + * the request + * + * @exception ServletException if the request for the POST + * could not be handled + * + * @see javax.servlet.ServletOutputStream + * @see javax.servlet.ServletResponse#setContentType + */ + protected void doPost(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException { + + String protocol = req.getProtocol(); + String msg = lStrings.getString("http.method_post_not_supported"); + if (protocol.endsWith("1.1")) { + resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg); + } else { + resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg); + } + } + + + /** + * Called by the server (via the service method) + * to allow a servlet to handle a PUT request. + * + * The PUT operation allows a client to + * place a file on the server and is similar to + * sending a file by FTP. + * + *

When overriding this method, leave intact + * any content headers sent with the request (including + * Content-Length, Content-Type, Content-Transfer-Encoding, + * Content-Encoding, Content-Base, Content-Language, Content-Location, + * Content-MD5, and Content-Range). If your method cannot + * handle a content header, it must issue an error message + * (HTTP 501 - Not Implemented) and discard the request. + * For more information on HTTP 1.1, see RFC 2616 + * . + * + *

This method does not need to be either safe or idempotent. + * Operations that doPut performs can have side + * effects for which the user can be held accountable. When using + * this method, it may be useful to save a copy of the + * affected URL in temporary storage. + * + *

If the HTTP PUT request is incorrectly formatted, + * doPut returns an HTTP "Bad Request" message. + * + * @param req the {@link HttpServletRequest} object that + * contains the request the client made of + * the servlet + * + * @param resp the {@link HttpServletResponse} object that + * contains the response the servlet returns + * to the client + * + * @exception IOException if an input or output error occurs + * while the servlet is handling the + * PUT request + * + * @exception ServletException if the request for the PUT + * cannot be handled + */ + protected void doPut(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException { + + String protocol = req.getProtocol(); + String msg = lStrings.getString("http.method_put_not_supported"); + if (protocol.endsWith("1.1")) { + resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg); + } else { + resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg); + } + } + + + /** + * Called by the server (via the service method) + * to allow a servlet to handle a DELETE request. + * + * The DELETE operation allows a client to remove a document + * or Web page from the server. + * + *

This method does not need to be either safe + * or idempotent. Operations requested through + * DELETE can have side effects for which users + * can be held accountable. When using + * this method, it may be useful to save a copy of the + * affected URL in temporary storage. + * + *

If the HTTP DELETE request is incorrectly formatted, + * doDelete returns an HTTP "Bad Request" + * message. + * + * @param req the {@link HttpServletRequest} object that + * contains the request the client made of + * the servlet + * + * + * @param resp the {@link HttpServletResponse} object that + * contains the response the servlet returns + * to the client + * + * @exception IOException if an input or output error occurs + * while the servlet is handling the + * DELETE request + * + * @exception ServletException if the request for the + * DELETE cannot be handled + */ + protected void doDelete(HttpServletRequest req, + HttpServletResponse resp) + throws ServletException, IOException { + + String protocol = req.getProtocol(); + String msg = lStrings.getString("http.method_delete_not_supported"); + if (protocol.endsWith("1.1")) { + resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg); + } else { + resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg); + } + } + + + private static Method[] getAllDeclaredMethods(Class c) { + + if (c.equals(javax.servlet.http.HttpServlet.class)) { + return null; + } + + Method[] parentMethods = getAllDeclaredMethods(c.getSuperclass()); + Method[] thisMethods = c.getDeclaredMethods(); + + if ((parentMethods != null) && (parentMethods.length > 0)) { + Method[] allMethods = + new Method[parentMethods.length + thisMethods.length]; + System.arraycopy(parentMethods, 0, allMethods, 0, + parentMethods.length); + System.arraycopy(thisMethods, 0, allMethods, parentMethods.length, + thisMethods.length); + + thisMethods = allMethods; + } + + return thisMethods; + } + + + /** + * Called by the server (via the service method) + * to allow a servlet to handle a OPTIONS request. + * + * The OPTIONS request determines which HTTP methods + * the server supports and + * returns an appropriate header. For example, if a servlet + * overrides doGet, this method returns the + * following header: + * + *

Allow: GET, HEAD, TRACE, OPTIONS + * + *

There's no need to override this method unless the + * servlet implements new HTTP methods, beyond those + * implemented by HTTP 1.1. + * + * @param req the {@link HttpServletRequest} object that + * contains the request the client made of + * the servlet + * + * @param resp the {@link HttpServletResponse} object that + * contains the response the servlet returns + * to the client + * + * @exception IOException if an input or output error occurs + * while the servlet is handling the + * OPTIONS request + * + * @exception ServletException if the request for the + * OPTIONS cannot be handled + */ + protected void doOptions(HttpServletRequest req, + HttpServletResponse resp) + throws ServletException, IOException { + + Method[] methods = getAllDeclaredMethods(this.getClass()); + + boolean ALLOW_GET = false; + boolean ALLOW_HEAD = false; + boolean ALLOW_POST = false; + boolean ALLOW_PUT = false; + boolean ALLOW_DELETE = false; + boolean ALLOW_TRACE = true; + boolean ALLOW_OPTIONS = true; + + for (int i=0; iservice method) + * to allow a servlet to handle a TRACE request. + * + * A TRACE returns the headers sent with the TRACE + * request to the client, so that they can be used in + * debugging. There's no need to override this method. + * + * @param req the {@link HttpServletRequest} object that + * contains the request the client made of + * the servlet + * + * @param resp the {@link HttpServletResponse} object that + * contains the response the servlet returns + * to the client + * + * @exception IOException if an input or output error occurs + * while the servlet is handling the + * TRACE request + * + * @exception ServletException if the request for the + * TRACE cannot be handled + */ + protected void doTrace(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException + { + + int responseLength; + + String CRLF = "\r\n"; + StringBuilder buffer = new StringBuilder("TRACE ").append(req.getRequestURI()) + .append(" ").append(req.getProtocol()); + + Enumeration reqHeaderEnum = req.getHeaderNames(); + + while( reqHeaderEnum.hasMoreElements() ) { + String headerName = reqHeaderEnum.nextElement(); + buffer.append(CRLF).append(headerName).append(": ") + .append(req.getHeader(headerName)); + } + + buffer.append(CRLF); + + responseLength = buffer.length(); + + resp.setContentType("message/http"); + resp.setContentLength(responseLength); + ServletOutputStream out = resp.getOutputStream(); + out.print(buffer.toString()); + out.close(); + return; + } + + + /** + * Receives standard HTTP requests from the public + * service method and dispatches + * them to the doMethod methods defined in + * this class. This method is an HTTP-specific version of the + * {@link javax.servlet.Servlet#service} method. There's no + * need to override this method. + * + * @param req the {@link HttpServletRequest} object that + * contains the request the client made of + * the servlet + * + * @param resp the {@link HttpServletResponse} object that + * contains the response the servlet returns + * to the client + * + * @exception IOException if an input or output error occurs + * while the servlet is handling the + * HTTP request + * + * @exception ServletException if the HTTP request + * cannot be handled + * + * @see javax.servlet.Servlet#service + */ + protected void service(HttpServletRequest req, HttpServletResponse resp) + throws ServletException, IOException { + + String method = req.getMethod(); + + if (method.equals(METHOD_GET)) { + long lastModified = getLastModified(req); + if (lastModified == -1) { + // servlet doesn't support if-modified-since, no reason + // to go through further expensive logic + doGet(req, resp); + } else { + long ifModifiedSince; + try { + ifModifiedSince = req.getDateHeader(HEADER_IFMODSINCE); + } catch (IllegalArgumentException iae) { + // Invalid date header - proceed as if none was set + ifModifiedSince = -1; + } + if (ifModifiedSince < (lastModified / 1000 * 1000)) { + // If the servlet mod time is later, call doGet() + // Round down to the nearest second for a proper compare + // A ifModifiedSince of -1 will always be less + maybeSetLastModified(resp, lastModified); + doGet(req, resp); + } else { + resp.setStatus(HttpServletResponse.SC_NOT_MODIFIED); + } + } + + } else if (method.equals(METHOD_HEAD)) { + long lastModified = getLastModified(req); + maybeSetLastModified(resp, lastModified); + doHead(req, resp); + + } else if (method.equals(METHOD_POST)) { + doPost(req, resp); + + } else if (method.equals(METHOD_PUT)) { + doPut(req, resp); + + } else if (method.equals(METHOD_DELETE)) { + doDelete(req, resp); + + } else if (method.equals(METHOD_OPTIONS)) { + doOptions(req,resp); + + } else if (method.equals(METHOD_TRACE)) { + doTrace(req,resp); + + } else { + // + // Note that this means NO servlet supports whatever + // method was requested, anywhere on this server. + // + + String errMsg = lStrings.getString("http.method_not_implemented"); + Object[] errArgs = new Object[1]; + errArgs[0] = method; + errMsg = MessageFormat.format(errMsg, errArgs); + + resp.sendError(HttpServletResponse.SC_NOT_IMPLEMENTED, errMsg); + } + } + + + /* + * Sets the Last-Modified entity header field, if it has not + * already been set and if the value is meaningful. Called before + * doGet, to ensure that headers are set before response data is + * written. A subclass might have set this header already, so we + * check. + */ + private void maybeSetLastModified(HttpServletResponse resp, + long lastModified) { + if (resp.containsHeader(HEADER_LASTMOD)) + return; + if (lastModified >= 0) + resp.setDateHeader(HEADER_LASTMOD, lastModified); + } + + + /** + * Dispatches client requests to the protected + * service method. There's no need to + * override this method. + * + * @param req the {@link HttpServletRequest} object that + * contains the request the client made of + * the servlet + * + * @param res the {@link HttpServletResponse} object that + * contains the response the servlet returns + * to the client + * + * @exception IOException if an input or output error occurs + * while the servlet is handling the + * HTTP request + * + * @exception ServletException if the HTTP request cannot + * be handled + * + * @see javax.servlet.Servlet#service + */ + @Override + public void service(ServletRequest req, ServletResponse res) + throws ServletException, IOException { + + HttpServletRequest request; + HttpServletResponse response; + + try { + request = (HttpServletRequest) req; + response = (HttpServletResponse) res; + } catch (ClassCastException e) { + throw new ServletException("non-HTTP request or response"); + } + service(request, response); + } +} + + +/* + * A response wrapper for use in (dumb) "HEAD" support. + * This just swallows that body, counting the bytes in order to set + * the content length appropriately. All other methods delegate to the + * wrapped HTTP Servlet Response object. + */ +// file private +class NoBodyResponse extends HttpServletResponseWrapper { + private final NoBodyOutputStream noBody; + private PrintWriter writer; + private boolean didSetContentLength; + + // file private + NoBodyResponse(HttpServletResponse r) { + super(r); + noBody = new NoBodyOutputStream(); + } + + // file private + void setContentLength() { + if (!didSetContentLength) { + if (writer != null) { + writer.flush(); + } + super.setContentLength(noBody.getContentLength()); + } + } + + + // SERVLET RESPONSE interface methods + + @Override + public void setContentLength(int len) { + super.setContentLength(len); + didSetContentLength = true; + } + + @Override + public void setContentLengthLong(long len) { + super.setContentLengthLong(len); + didSetContentLength = true; + } + + @Override + public void setHeader(String name, String value) { + super.setHeader(name, value); + checkHeader(name); + } + + @Override + public void addHeader(String name, String value) { + super.addHeader(name, value); + checkHeader(name); + } + + @Override + public void setIntHeader(String name, int value) { + super.setIntHeader(name, value); + checkHeader(name); + } + + @Override + public void addIntHeader(String name, int value) { + super.addIntHeader(name, value); + checkHeader(name); + } + + private void checkHeader(String name) { + if ("content-length".equalsIgnoreCase(name)) { + didSetContentLength = true; + } + } + + @Override + public ServletOutputStream getOutputStream() throws IOException { + return noBody; + } + + @Override + public PrintWriter getWriter() throws UnsupportedEncodingException { + + if (writer == null) { + OutputStreamWriter w; + + w = new OutputStreamWriter(noBody, getCharacterEncoding()); + writer = new PrintWriter(w); + } + return writer; + } +} + + +/* + * Servlet output stream that gobbles up all its data. + */ + +// file private +class NoBodyOutputStream extends ServletOutputStream { + + private static final String LSTRING_FILE = + "javax.servlet.http.LocalStrings"; + private static final ResourceBundle lStrings = + ResourceBundle.getBundle(LSTRING_FILE); + + private int contentLength = 0; + + // file private + NoBodyOutputStream() { + // NOOP + } + + // file private + int getContentLength() { + return contentLength; + } + + @Override + public void write(int b) { + contentLength++; + } + + @Override + public void write(byte buf[], int offset, int len) throws IOException { + if (buf == null) { + throw new NullPointerException( + lStrings.getString("err.io.nullArray")); + } + + if (offset < 0 || len < 0 || offset+len > buf.length) { + String msg = lStrings.getString("err.io.indexOutOfBounds"); + Object[] msgArgs = new Object[3]; + msgArgs[0] = Integer.valueOf(offset); + msgArgs[1] = Integer.valueOf(len); + msgArgs[2] = Integer.valueOf(buf.length); + msg = MessageFormat.format(msg, msgArgs); + throw new IndexOutOfBoundsException(msg); + } + + contentLength += len; + } + + @Override + public boolean isReady() { + // TODO SERVLET 3.1 + return false; + } + + @Override + public void setWriteListener(javax.servlet.WriteListener listener) { + // TODO SERVLET 3.1 + } +} diff --git a/lib/servlet-api/javax/servlet/http/HttpServletRequest.java b/lib/servlet-api/javax/servlet/http/HttpServletRequest.java new file mode 100644 index 00000000..3c1f6a14 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpServletRequest.java @@ -0,0 +1,522 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet.http; + +import java.io.IOException; +import java.util.Collection; +import java.util.Enumeration; + +import javax.servlet.ServletException; +import javax.servlet.ServletRequest; + +/** + * Extends the {@link javax.servlet.ServletRequest} interface to provide request + * information for HTTP servlets. + *

+ * The servlet container creates an HttpServletRequest object and + * passes it as an argument to the servlet's service methods + * (doGet, doPost, etc). + */ +public interface HttpServletRequest extends ServletRequest { + + /** + * String identifier for Basic authentication. Value "BASIC" + */ + public static final String BASIC_AUTH = "BASIC"; + /** + * String identifier for Form authentication. Value "FORM" + */ + public static final String FORM_AUTH = "FORM"; + /** + * String identifier for Client Certificate authentication. Value + * "CLIENT_CERT" + */ + public static final String CLIENT_CERT_AUTH = "CLIENT_CERT"; + /** + * String identifier for Digest authentication. Value "DIGEST" + */ + public static final String DIGEST_AUTH = "DIGEST"; + + /** + * Returns the name of the authentication scheme used to protect the + * servlet. All servlet containers support basic, form and client + * certificate authentication, and may additionally support digest + * authentication. If the servlet is not authenticated null is + * returned. + *

+ * Same as the value of the CGI variable AUTH_TYPE. + * + * @return one of the static members BASIC_AUTH, FORM_AUTH, CLIENT_CERT_AUTH, + * DIGEST_AUTH (suitable for == comparison) or the + * container-specific string indicating the authentication scheme, + * or null if the request was not authenticated. + */ + public String getAuthType(); + + /** + * Returns an array containing all of the Cookie objects the + * client sent with this request. This method returns null if + * no cookies were sent. + * + * @return an array of all the Cookies included with this + * request, or null if the request has no cookies + */ + public Cookie[] getCookies(); + + /** + * Returns the value of the specified request header as a long + * value that represents a Date object. Use this method with + * headers that contain dates, such as If-Modified-Since. + *

+ * The date is returned as the number of milliseconds since January 1, 1970 + * GMT. The header name is case insensitive. + *

+ * If the request did not have a header of the specified name, this method + * returns -1. If the header can't be converted to a date, the method throws + * an IllegalArgumentException. + * + * @param name + * a String specifying the name of the header + * @return a long value representing the date specified in the + * header expressed as the number of milliseconds since January 1, + * 1970 GMT, or -1 if the named header was not included with the + * request + * @exception IllegalArgumentException + * If the header value can't be converted to a date + */ + public long getDateHeader(String name); + + /** + * Returns the value of the specified request header as a + * String. If the request did not include a header of the + * specified name, this method returns null. If there are + * multiple headers with the same name, this method returns the first head + * in the request. The header name is case insensitive. You can use this + * method with any request header. + * + * @param name + * a String specifying the header name + * @return a String containing the value of the requested + * header, or null if the request does not have a + * header of that name + */ + public String getHeader(String name); + + /** + * Returns all the values of the specified request header as an + * Enumeration of String objects. + *

+ * Some headers, such as Accept-Language can be sent by clients + * as several headers each with a different value rather than sending the + * header as a comma separated list. + *

+ * If the request did not include any headers of the specified name, this + * method returns an empty Enumeration. The header name is case + * insensitive. You can use this method with any request header. + * + * @param name + * a String specifying the header name + * @return an Enumeration containing the values of the requested + * header. If the request does not have any headers of that name + * return an empty enumeration. If the container does not allow + * access to header information, return null + */ + public Enumeration getHeaders(String name); + + /** + * Returns an enumeration of all the header names this request contains. If + * the request has no headers, this method returns an empty enumeration. + *

+ * Some servlet containers do not allow servlets to access headers using + * this method, in which case this method returns null + * + * @return an enumeration of all the header names sent with this request; if + * the request has no headers, an empty enumeration; if the servlet + * container does not allow servlets to use this method, + * null + */ + public Enumeration getHeaderNames(); + + /** + * Returns the value of the specified request header as an int. + * If the request does not have a header of the specified name, this method + * returns -1. If the header cannot be converted to an integer, this method + * throws a NumberFormatException. + *

+ * The header name is case insensitive. + * + * @param name + * a String specifying the name of a request header + * @return an integer expressing the value of the request header or -1 if the + * request doesn't have a header of this name + * @exception NumberFormatException + * If the header value can't be converted to an + * int + */ + public int getIntHeader(String name); + + /** + * Returns the name of the HTTP method with which this request was made, for + * example, GET, POST, or PUT. Same as the value of the CGI variable + * REQUEST_METHOD. + * + * @return a String specifying the name of the method with + * which this request was made + */ + public String getMethod(); + + /** + * Returns any extra path information associated with the URL the client + * sent when it made this request. The extra path information follows the + * servlet path but precedes the query string and will start with a "/" + * character. + *

+ * This method returns null if there was no extra path + * information. + *

+ * Same as the value of the CGI variable PATH_INFO. + * + * @return a String, decoded by the web container, specifying + * extra path information that comes after the servlet path but + * before the query string in the request URL; or null + * if the URL does not have any extra path information + */ + public String getPathInfo(); + + /** + * Returns any extra path information after the servlet name but before the + * query string, and translates it to a real path. Same as the value of the + * CGI variable PATH_TRANSLATED. + *

+ * If the URL does not have any extra path information, this method returns + * null or the servlet container cannot translate the virtual + * path to a real path for any reason (such as when the web application is + * executed from an archive). The web container does not decode this string. + * + * @return a String specifying the real path, or + * null if the URL does not have any extra path + * information + */ + public String getPathTranslated(); + + /** + * Returns the portion of the request URI that indicates the context of the + * request. The context path always comes first in a request URI. The path + * starts with a "/" character but does not end with a "/" character. For + * servlets in the default (root) context, this method returns "". The + * container does not decode this string. + * + * @return a String specifying the portion of the request URI + * that indicates the context of the request + */ + public String getContextPath(); + + /** + * Returns the query string that is contained in the request URL after the + * path. This method returns null if the URL does not have a + * query string. Same as the value of the CGI variable QUERY_STRING. + * + * @return a String containing the query string or + * null if the URL contains no query string. The value + * is not decoded by the container. + */ + public String getQueryString(); + + /** + * Returns the login of the user making this request, if the user has been + * authenticated, or null if the user has not been + * authenticated. Whether the user name is sent with each subsequent request + * depends on the browser and type of authentication. Same as the value of + * the CGI variable REMOTE_USER. + * + * @return a String specifying the login of the user making + * this request, or null if the user login is not known + */ + public String getRemoteUser(); + + /** + * Returns a boolean indicating whether the authenticated user is included + * in the specified logical "role". Roles and role membership can be defined + * using deployment descriptors. If the user has not been authenticated, the + * method returns false. + * + * @param role + * a String specifying the name of the role + * @return a boolean indicating whether the user making this + * request belongs to a given role; false if the user + * has not been authenticated + */ + public boolean isUserInRole(String role); + + /** + * Returns a java.security.Principal object containing the name + * of the current authenticated user. If the user has not been + * authenticated, the method returns null. + * + * @return a java.security.Principal containing the name of the + * user making this request; null if the user has not + * been authenticated + */ + public java.security.Principal getUserPrincipal(); + + /** + * Returns the session ID specified by the client. This may not be the same + * as the ID of the current valid session for this request. If the client + * did not specify a session ID, this method returns null. + * + * @return a String specifying the session ID, or + * null if the request did not specify a session ID + * @see #isRequestedSessionIdValid + */ + public String getRequestedSessionId(); + + /** + * Returns the part of this request's URL from the protocol name up to the + * query string in the first line of the HTTP request. The web container + * does not decode this String. For example: + * + * + * + * + * + * + * + *
First line of HTTP requestReturned Value
POST /some/path.html HTTP/1.1 + * + * /some/path.html + *
GET http://foo.bar/a.html HTTP/1.0 + * + * /a.html + *
HEAD /xyz?a=b HTTP/1.1 + * + * /xyz + *
+ *

+ * To reconstruct an URL with a scheme and host, use + * {@link #getRequestURL}. + * + * @return a String containing the part of the URL from the + * protocol name up to the query string + * @see #getRequestURL + */ + public String getRequestURI(); + + /** + * Reconstructs the URL the client used to make the request. The returned + * URL contains a protocol, server name, port number, and server path, but + * it does not include query string parameters. + *

+ * Because this method returns a StringBuffer, not a string, + * you can modify the URL easily, for example, to append query parameters. + *

+ * This method is useful for creating redirect messages and for reporting + * errors. + * + * @return a StringBuffer object containing the reconstructed + * URL + */ + public StringBuffer getRequestURL(); + + /** + * Returns the part of this request's URL that calls the servlet. This path + * starts with a "/" character and includes either the servlet name or a + * path to the servlet, but does not include any extra path information or a + * query string. Same as the value of the CGI variable SCRIPT_NAME. + *

+ * This method will return an empty string ("") if the servlet used to + * process this request was matched using the "/*" pattern. + * + * @return a String containing the name or path of the servlet + * being called, as specified in the request URL, decoded, or an + * empty string if the servlet used to process the request is + * matched using the "/*" pattern. + */ + public String getServletPath(); + + /** + * Returns the current HttpSession associated with this request + * or, if there is no current session and create is true, + * returns a new session. + *

+ * If create is false and the request has no valid + * HttpSession, this method returns null. + *

+ * To make sure the session is properly maintained, you must call this + * method before the response is committed. If the container is using + * cookies to maintain session integrity and is asked to create a new + * session when the response is committed, an IllegalStateException is + * thrown. + * + * @param create + * true to create a new session for this request if + * necessary; false to return null if + * there's no current session + * @return the HttpSession associated with this request or + * null if create is false + * and the request has no valid session + * @see #getSession() + */ + public HttpSession getSession(boolean create); + + /** + * Returns the current session associated with this request, or if the + * request does not have a session, creates one. + * + * @return the HttpSession associated with this request + * @see #getSession(boolean) + */ + public HttpSession getSession(); + + /** + * Changes the session ID of the session associated with this request. This + * method does not create a new session object it only changes the ID of the + * current session. + * + * @return the new session ID allocated to the session + * @see HttpSessionIdListener + * @since Servlet 3.1 + */ + public String changeSessionId(); + + /** + * Checks whether the requested session ID is still valid. + * + * @return true if this request has an id for a valid session + * in the current session context; false otherwise + * @see #getRequestedSessionId + * @see #getSession + */ + public boolean isRequestedSessionIdValid(); + + /** + * Checks whether the requested session ID came in as a cookie. + * + * @return true if the session ID came in as a cookie; + * otherwise, false + * @see #getSession + */ + public boolean isRequestedSessionIdFromCookie(); + + /** + * Checks whether the requested session ID came in as part of the request + * URL. + * + * @return true if the session ID came in as part of a URL; + * otherwise, false + * @see #getSession + */ + public boolean isRequestedSessionIdFromURL(); + + /** + * @deprecated As of Version 2.1 of the Java Servlet API, use + * {@link #isRequestedSessionIdFromURL} instead. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public boolean isRequestedSessionIdFromUrl(); + + /** + * Triggers the same authentication process as would be triggered if the + * request is for a resource that is protected by a security constraint. + * + * @param response The response to use to return any authentication + * challenge + * @return true if the user is successfully authenticated and + * false if not + * + * @since Servlet 3.0 + */ + public boolean authenticate(HttpServletResponse response) + throws IOException, ServletException; + + /** + * Authenticate the provided user name and password and then associated the + * authenticated user with the request. + * + * @param username The user name to authenticate + * @param password The password to use to authenticate the user + * + * @throws ServletException + * If any of {@link #getRemoteUser()}, + * {@link #getUserPrincipal()} or {@link #getAuthType()} are + * non-null, if the configured authenticator does not support + * user name and password authentication or if the + * authentication fails + * @since Servlet 3.0 + */ + public void login(String username, String password) throws ServletException; + + /** + * Removes any authenticated user from the request. + * + * @throws ServletException + * If the logout fails + * @since Servlet 3.0 + */ + public void logout() throws ServletException; + + /** + * Return a collection of all uploaded Parts. + * + * @return A collection of all uploaded Parts. + * @throws IOException + * if an I/O error occurs + * @throws IllegalStateException + * if size limits are exceeded or no multipart configuration is + * provided + * @throws ServletException + * if the request is not multipart/form-data + * @since Servlet 3.0 + */ + public Collection getParts() throws IOException, + ServletException; + + /** + * Gets the named Part or null if the Part does not exist. Triggers upload + * of all Parts. + * + * @param name + * @return The named Part or null if the Part does not exist + * @throws IOException + * if an I/O error occurs + * @throws IllegalStateException + * if size limits are exceeded + * @throws ServletException + * if the request is not multipart/form-data + * @since Servlet 3.0 + */ + public Part getPart(String name) throws IOException, + ServletException; + + /** + * Start the HTTP upgrade process and pass the connection to the provided + * protocol handler once the current request/response pair has completed + * processing. Calling this method sets the response status to {@link + * HttpServletResponse#SC_SWITCHING_PROTOCOLS} and flushes the response. + * Protocol specific headers must have already been set before this method + * is called. + * + * @throws IOException + * if an I/O error occurred during the upgrade + * @throws ServletException + * if the given httpUpgradeHandlerClass fails to be instantiated + * @since Servlet 3.1 + */ + public T upgrade( + Class httpUpgradeHandlerClass) throws java.io.IOException, ServletException; +} diff --git a/lib/servlet-api/javax/servlet/http/HttpServletRequestWrapper.java b/lib/servlet-api/javax/servlet/http/HttpServletRequestWrapper.java new file mode 100644 index 00000000..a72a2440 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpServletRequestWrapper.java @@ -0,0 +1,376 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.io.IOException; +import java.util.Collection; +import java.util.Enumeration; + +import javax.servlet.ServletException; +import javax.servlet.ServletRequestWrapper; + +/** + * Provides a convenient implementation of the HttpServletRequest interface that + * can be subclassed by developers wishing to adapt the request to a Servlet. + * This class implements the Wrapper or Decorator pattern. Methods default to + * calling through to the wrapped request object. + * + * @see javax.servlet.http.HttpServletRequest + * @since v 2.3 + */ +public class HttpServletRequestWrapper extends ServletRequestWrapper implements + HttpServletRequest { + + /** + * Constructs a request object wrapping the given request. + * + * @throws java.lang.IllegalArgumentException + * if the request is null + */ + public HttpServletRequestWrapper(HttpServletRequest request) { + super(request); + } + + private HttpServletRequest _getHttpServletRequest() { + return (HttpServletRequest) super.getRequest(); + } + + /** + * The default behavior of this method is to return getAuthType() on the + * wrapped request object. + */ + @Override + public String getAuthType() { + return this._getHttpServletRequest().getAuthType(); + } + + /** + * The default behavior of this method is to return getCookies() on the + * wrapped request object. + */ + @Override + public Cookie[] getCookies() { + return this._getHttpServletRequest().getCookies(); + } + + /** + * The default behavior of this method is to return getDateHeader(String + * name) on the wrapped request object. + */ + @Override + public long getDateHeader(String name) { + return this._getHttpServletRequest().getDateHeader(name); + } + + /** + * The default behavior of this method is to return getHeader(String name) + * on the wrapped request object. + */ + @Override + public String getHeader(String name) { + return this._getHttpServletRequest().getHeader(name); + } + + /** + * The default behavior of this method is to return getHeaders(String name) + * on the wrapped request object. + */ + @Override + public Enumeration getHeaders(String name) { + return this._getHttpServletRequest().getHeaders(name); + } + + /** + * The default behavior of this method is to return getHeaderNames() on the + * wrapped request object. + */ + @Override + public Enumeration getHeaderNames() { + return this._getHttpServletRequest().getHeaderNames(); + } + + /** + * The default behavior of this method is to return getIntHeader(String + * name) on the wrapped request object. + */ + @Override + public int getIntHeader(String name) { + return this._getHttpServletRequest().getIntHeader(name); + } + + /** + * The default behavior of this method is to return getMethod() on the + * wrapped request object. + */ + @Override + public String getMethod() { + return this._getHttpServletRequest().getMethod(); + } + + /** + * The default behavior of this method is to return getPathInfo() on the + * wrapped request object. + */ + @Override + public String getPathInfo() { + return this._getHttpServletRequest().getPathInfo(); + } + + /** + * The default behavior of this method is to return getPathTranslated() on + * the wrapped request object. + */ + @Override + public String getPathTranslated() { + return this._getHttpServletRequest().getPathTranslated(); + } + + /** + * The default behavior of this method is to return getContextPath() on the + * wrapped request object. + */ + @Override + public String getContextPath() { + return this._getHttpServletRequest().getContextPath(); + } + + /** + * The default behavior of this method is to return getQueryString() on the + * wrapped request object. + */ + @Override + public String getQueryString() { + return this._getHttpServletRequest().getQueryString(); + } + + /** + * The default behavior of this method is to return getRemoteUser() on the + * wrapped request object. + */ + @Override + public String getRemoteUser() { + return this._getHttpServletRequest().getRemoteUser(); + } + + /** + * The default behavior of this method is to return isUserInRole(String + * role) on the wrapped request object. + */ + @Override + public boolean isUserInRole(String role) { + return this._getHttpServletRequest().isUserInRole(role); + } + + /** + * The default behavior of this method is to return getUserPrincipal() on + * the wrapped request object. + */ + @Override + public java.security.Principal getUserPrincipal() { + return this._getHttpServletRequest().getUserPrincipal(); + } + + /** + * The default behavior of this method is to return getRequestedSessionId() + * on the wrapped request object. + */ + @Override + public String getRequestedSessionId() { + return this._getHttpServletRequest().getRequestedSessionId(); + } + + /** + * The default behavior of this method is to return getRequestURI() on the + * wrapped request object. + */ + @Override + public String getRequestURI() { + return this._getHttpServletRequest().getRequestURI(); + } + + /** + * The default behavior of this method is to return getRequestURL() on the + * wrapped request object. + */ + @Override + public StringBuffer getRequestURL() { + return this._getHttpServletRequest().getRequestURL(); + } + + /** + * The default behavior of this method is to return getServletPath() on the + * wrapped request object. + */ + @Override + public String getServletPath() { + return this._getHttpServletRequest().getServletPath(); + } + + /** + * The default behavior of this method is to return getSession(boolean + * create) on the wrapped request object. + */ + @Override + public HttpSession getSession(boolean create) { + return this._getHttpServletRequest().getSession(create); + } + + /** + * The default behavior of this method is to return getSession() on the + * wrapped request object. + */ + @Override + public HttpSession getSession() { + return this._getHttpServletRequest().getSession(); + } + + /** + * The default behavior of this method is to call changeSessionId() on the + * wrapped request object. + */ + @Override + public String changeSessionId() { + return this._getHttpServletRequest().changeSessionId(); + } + + /** + * The default behavior of this method is to return + * isRequestedSessionIdValid() on the wrapped request object. + */ + @Override + public boolean isRequestedSessionIdValid() { + return this._getHttpServletRequest().isRequestedSessionIdValid(); + } + + /** + * The default behavior of this method is to return + * isRequestedSessionIdFromCookie() on the wrapped request object. + */ + @Override + public boolean isRequestedSessionIdFromCookie() { + return this._getHttpServletRequest().isRequestedSessionIdFromCookie(); + } + + /** + * The default behavior of this method is to return + * isRequestedSessionIdFromURL() on the wrapped request object. + */ + @Override + public boolean isRequestedSessionIdFromURL() { + return this._getHttpServletRequest().isRequestedSessionIdFromURL(); + } + + /** + * The default behavior of this method is to return + * isRequestedSessionIdFromUrl() on the wrapped request object. + * + * @deprecated As of Version 3.0 of the Java Servlet API + */ + @Override + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public boolean isRequestedSessionIdFromUrl() { + return this._getHttpServletRequest().isRequestedSessionIdFromUrl(); + } + + /** + * {@inheritDoc} + *

+ * The default behavior of this method is to return + * {@link HttpServletRequest#authenticate(HttpServletResponse)} + * on the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public boolean authenticate(HttpServletResponse response) + throws IOException, ServletException { + return this._getHttpServletRequest().authenticate(response); + } + + /** + * {@inheritDoc} + *

+ * The default behavior of this method is to return + * {@link HttpServletRequest#login(String, String)} + * on the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public void login(String username, String password) throws ServletException { + this._getHttpServletRequest().login(username, password); + } + + /** + * {@inheritDoc} + *

+ * The default behavior of this method is to return + * {@link HttpServletRequest#logout()} + * on the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public void logout() throws ServletException { + this._getHttpServletRequest().logout(); + } + + /** + * {@inheritDoc} + *

+ * The default behavior of this method is to return + * {@link HttpServletRequest#getParts()} + * on the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public Collection getParts() throws IOException, + ServletException { + return this._getHttpServletRequest().getParts(); + } + + /** + * {@inheritDoc} + *

+ * The default behavior of this method is to return + * {@link HttpServletRequest#getPart(String)} + * on the wrapped request object. + * + * @since Servlet 3.0 + */ + @Override + public Part getPart(String name) throws IOException, + ServletException { + return this._getHttpServletRequest().getPart(name); + } + + /** + * {@inheritDoc} + *

+ * The default behavior of this method is to return + * {@link HttpServletRequest#upgrade(Class)} on the wrapped request object. + * + * @since Servlet 3.1 + */ + @Override + public T upgrade( + Class httpUpgradeHandlerClass) throws IOException, ServletException { + return this._getHttpServletRequest().upgrade(httpUpgradeHandlerClass); + } +} diff --git a/lib/servlet-api/javax/servlet/http/HttpServletResponse.java b/lib/servlet-api/javax/servlet/http/HttpServletResponse.java new file mode 100644 index 00000000..c5c6f824 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpServletResponse.java @@ -0,0 +1,597 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.io.IOException; +import java.util.Collection; + +import javax.servlet.ServletResponse; + +/** + * Extends the {@link ServletResponse} interface to provide HTTP-specific + * functionality in sending a response. For example, it has methods to access + * HTTP headers and cookies. + *

+ * The servlet container creates an HttpServletResponse object and + * passes it as an argument to the servlet's service methods (doGet, doPost, etc). + * + * @see javax.servlet.ServletResponse + */ +public interface HttpServletResponse extends ServletResponse { + + /** + * Adds the specified cookie to the response. This method can be called + * multiple times to set more than one cookie. + * + * @param cookie + * the Cookie to return to the client + */ + public void addCookie(Cookie cookie); + + /** + * Returns a boolean indicating whether the named response header has + * already been set. + * + * @param name + * the header name + * @return true if the named response header has already been + * set; false otherwise + */ + public boolean containsHeader(String name); + + /** + * Encodes the specified URL by including the session ID in it, or, if + * encoding is not needed, returns the URL unchanged. The implementation of + * this method includes the logic to determine whether the session ID needs + * to be encoded in the URL. For example, if the browser supports cookies, + * or session tracking is turned off, URL encoding is unnecessary. + *

+ * For robust session tracking, all URLs emitted by a servlet should be run + * through this method. Otherwise, URL rewriting cannot be used with + * browsers which do not support cookies. + * + * @param url + * the url to be encoded. + * @return the encoded URL if encoding is needed; the unchanged URL + * otherwise. + */ + public String encodeURL(String url); + + /** + * Encodes the specified URL for use in the sendRedirect method + * or, if encoding is not needed, returns the URL unchanged. The + * implementation of this method includes the logic to determine whether the + * session ID needs to be encoded in the URL. Because the rules for making + * this determination can differ from those used to decide whether to encode + * a normal link, this method is separated from the encodeURL + * method. + *

+ * All URLs sent to the HttpServletResponse.sendRedirect method + * should be run through this method. Otherwise, URL rewriting cannot be + * used with browsers which do not support cookies. + * + * @param url + * the url to be encoded. + * @return the encoded URL if encoding is needed; the unchanged URL + * otherwise. + * @see #sendRedirect + * @see #encodeUrl + */ + public String encodeRedirectURL(String url); + + /** + * @param url + * the url to be encoded. + * @return the encoded URL if encoding is needed; the unchanged URL + * otherwise. + * @deprecated As of version 2.1, use encodeURL(String url) instead + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String encodeUrl(String url); + + /** + * @param url + * the url to be encoded. + * @return the encoded URL if encoding is needed; the unchanged URL + * otherwise. + * @deprecated As of version 2.1, use encodeRedirectURL(String url) instead + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String encodeRedirectUrl(String url); + + /** + * Sends an error response to the client using the specified status code and + * clears the output buffer. The server defaults to creating the response to + * look like an HTML-formatted server error page containing the specified + * message, setting the content type to "text/html", leaving cookies and + * other headers unmodified. If an error-page declaration has been made for + * the web application corresponding to the status code passed in, it will + * be served back in preference to the suggested msg parameter. + *

+ * If the response has already been committed, this method throws an + * IllegalStateException. After using this method, the response should be + * considered to be committed and should not be written to. + * + * @param sc + * the error status code + * @param msg + * the descriptive message + * @exception IOException + * If an input or output exception occurs + * @exception IllegalStateException + * If the response was committed + */ + public void sendError(int sc, String msg) throws IOException; + + /** + * Sends an error response to the client using the specified status code and + * clears the buffer. This is equivalent to calling {@link #sendError(int, + * String)} with the same status code and null for the message. + * + * @param sc + * the error status code + * @exception IOException + * If an input or output exception occurs + * @exception IllegalStateException + * If the response was committed before this method call + */ + public void sendError(int sc) throws IOException; + + /** + * Sends a temporary redirect response to the client using the specified + * redirect location URL. This method can accept relative URLs; the servlet + * container must convert the relative URL to an absolute URL before sending + * the response to the client. If the location is relative without a leading + * '/' the container interprets it as relative to the current request URI. + * If the location is relative with a leading '/' the container interprets + * it as relative to the servlet container root. + *

+ * If the response has already been committed, this method throws an + * IllegalStateException. After using this method, the response should be + * considered to be committed and should not be written to. + * + * @param location + * the redirect location URL + * @exception IOException + * If an input or output exception occurs + * @exception IllegalStateException + * If the response was committed or if a partial URL is given + * and cannot be converted into a valid URL + */ + public void sendRedirect(String location) throws IOException; + + /** + * Sets a response header with the given name and date-value. The date is + * specified in terms of milliseconds since the epoch. If the header had + * already been set, the new value overwrites the previous one. The + * containsHeader method can be used to test for the presence + * of a header before setting its value. + * + * @param name + * the name of the header to set + * @param date + * the assigned date value + * @see #containsHeader + * @see #addDateHeader + */ + public void setDateHeader(String name, long date); + + /** + * Adds a response header with the given name and date-value. The date is + * specified in terms of milliseconds since the epoch. This method allows + * response headers to have multiple values. + * + * @param name + * the name of the header to set + * @param date + * the additional date value + * @see #setDateHeader + */ + public void addDateHeader(String name, long date); + + /** + * Sets a response header with the given name and value. If the header had + * already been set, the new value overwrites the previous one. The + * containsHeader method can be used to test for the presence + * of a header before setting its value. + * + * @param name + * the name of the header + * @param value + * the header value If it contains octet string, it should be + * encoded according to RFC 2047 + * (http://www.ietf.org/rfc/rfc2047.txt) + * @see #containsHeader + * @see #addHeader + */ + public void setHeader(String name, String value); + + /** + * Adds a response header with the given name and value. This method allows + * response headers to have multiple values. + * + * @param name + * the name of the header + * @param value + * the additional header value If it contains octet string, it + * should be encoded according to RFC 2047 + * (http://www.ietf.org/rfc/rfc2047.txt) + * @see #setHeader + */ + public void addHeader(String name, String value); + + /** + * Sets a response header with the given name and integer value. If the + * header had already been set, the new value overwrites the previous one. + * The containsHeader method can be used to test for the + * presence of a header before setting its value. + * + * @param name + * the name of the header + * @param value + * the assigned integer value + * @see #containsHeader + * @see #addIntHeader + */ + public void setIntHeader(String name, int value); + + /** + * Adds a response header with the given name and integer value. This method + * allows response headers to have multiple values. + * + * @param name + * the name of the header + * @param value + * the assigned integer value + * @see #setIntHeader + */ + public void addIntHeader(String name, int value); + + /** + * Sets the status code for this response. This method is used to set the + * return status code when there is no error (for example, for the status + * codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the + * caller wishes to invoke an error-page defined in the web application, the + * sendError method should be used instead. + *

+ * The container clears the buffer and sets the Location header, preserving + * cookies and other headers. + * + * @param sc + * the status code + * @see #sendError + */ + public void setStatus(int sc); + + /** + * Sets the status code and message for this response. + * + * @param sc + * the status code + * @param sm + * the status message + * @deprecated As of version 2.1, due to ambiguous meaning of the message + * parameter. To set a status code use + * setStatus(int), to send an error with a + * description use sendError(int, String). + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public void setStatus(int sc, String sm); + + /** + * Return the HTTP status code associated with this Response. + * + * @since Servlet 3.0 + */ + public int getStatus(); + + /** + * Return the value for the specified header, or null if this + * header has not been set. If more than one value was added for this + * name, only the first is returned; use {@link #getHeaders(String)} to + * retrieve all of them. + * + * @param name Header name to look up + * + * @since Servlet 3.0 + */ + public String getHeader(String name); + + /** + * Return a Collection of all the header values associated with the + * specified header name. + * + * @param name Header name to look up + * + * @since Servlet 3.0 + */ + public Collection getHeaders(String name); + + /** + * Return an Iterable of all the header names set for this response. + * + * @since Servlet 3.0 + */ + public Collection getHeaderNames(); + + /* + * Server status codes; see RFC 2068. + */ + + /** + * Status code (100) indicating the client can continue. + */ + public static final int SC_CONTINUE = 100; + + /** + * Status code (101) indicating the server is switching protocols according + * to Upgrade header. + */ + public static final int SC_SWITCHING_PROTOCOLS = 101; + + /** + * Status code (200) indicating the request succeeded normally. + */ + public static final int SC_OK = 200; + + /** + * Status code (201) indicating the request succeeded and created a new + * resource on the server. + */ + public static final int SC_CREATED = 201; + + /** + * Status code (202) indicating that a request was accepted for processing, + * but was not completed. + */ + public static final int SC_ACCEPTED = 202; + + /** + * Status code (203) indicating that the meta information presented by the + * client did not originate from the server. + */ + public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203; + + /** + * Status code (204) indicating that the request succeeded but that there + * was no new information to return. + */ + public static final int SC_NO_CONTENT = 204; + + /** + * Status code (205) indicating that the agent SHOULD reset the + * document view which caused the request to be sent. + */ + public static final int SC_RESET_CONTENT = 205; + + /** + * Status code (206) indicating that the server has fulfilled the partial + * GET request for the resource. + */ + public static final int SC_PARTIAL_CONTENT = 206; + + /** + * Status code (300) indicating that the requested resource corresponds to + * any one of a set of representations, each with its own specific location. + */ + public static final int SC_MULTIPLE_CHOICES = 300; + + /** + * Status code (301) indicating that the resource has permanently moved to a + * new location, and that future references should use a new URI with their + * requests. + */ + public static final int SC_MOVED_PERMANENTLY = 301; + + /** + * Status code (302) indicating that the resource has temporarily moved to + * another location, but that future references should still use the + * original URI to access the resource. This definition is being retained + * for backwards compatibility. SC_FOUND is now the preferred definition. + */ + public static final int SC_MOVED_TEMPORARILY = 302; + + /** + * Status code (302) indicating that the resource reside temporarily under a + * different URI. Since the redirection might be altered on occasion, the + * client should continue to use the Request-URI for future + * requests.(HTTP/1.1) To represent the status code (302), it is recommended + * to use this variable. + */ + public static final int SC_FOUND = 302; + + /** + * Status code (303) indicating that the response to the request can be + * found under a different URI. + */ + public static final int SC_SEE_OTHER = 303; + + /** + * Status code (304) indicating that a conditional GET operation found that + * the resource was available and not modified. + */ + public static final int SC_NOT_MODIFIED = 304; + + /** + * Status code (305) indicating that the requested resource MUST be + * accessed through the proxy given by the Location + * field. + */ + public static final int SC_USE_PROXY = 305; + + /** + * Status code (307) indicating that the requested resource resides + * temporarily under a different URI. The temporary URI SHOULD be + * given by the Location field in the response. + */ + public static final int SC_TEMPORARY_REDIRECT = 307; + + /** + * Status code (400) indicating the request sent by the client was + * syntactically incorrect. + */ + public static final int SC_BAD_REQUEST = 400; + + /** + * Status code (401) indicating that the request requires HTTP + * authentication. + */ + public static final int SC_UNAUTHORIZED = 401; + + /** + * Status code (402) reserved for future use. + */ + public static final int SC_PAYMENT_REQUIRED = 402; + + /** + * Status code (403) indicating the server understood the request but + * refused to fulfill it. + */ + public static final int SC_FORBIDDEN = 403; + + /** + * Status code (404) indicating that the requested resource is not + * available. + */ + public static final int SC_NOT_FOUND = 404; + + /** + * Status code (405) indicating that the method specified in the + * Request-Line is not allowed for the resource + * identified by the Request-URI. + */ + public static final int SC_METHOD_NOT_ALLOWED = 405; + + /** + * Status code (406) indicating that the resource identified by the request + * is only capable of generating response entities which have content + * characteristics not acceptable according to the accept headers sent in + * the request. + */ + public static final int SC_NOT_ACCEPTABLE = 406; + + /** + * Status code (407) indicating that the client MUST first + * authenticate itself with the proxy. + */ + public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407; + + /** + * Status code (408) indicating that the client did not produce a request + * within the time that the server was prepared to wait. + */ + public static final int SC_REQUEST_TIMEOUT = 408; + + /** + * Status code (409) indicating that the request could not be completed due + * to a conflict with the current state of the resource. + */ + public static final int SC_CONFLICT = 409; + + /** + * Status code (410) indicating that the resource is no longer available at + * the server and no forwarding address is known. This condition + * SHOULD be considered permanent. + */ + public static final int SC_GONE = 410; + + /** + * Status code (411) indicating that the request cannot be handled without a + * defined Content-Length. + */ + public static final int SC_LENGTH_REQUIRED = 411; + + /** + * Status code (412) indicating that the precondition given in one or more + * of the request-header fields evaluated to false when it was tested on the + * server. + */ + public static final int SC_PRECONDITION_FAILED = 412; + + /** + * Status code (413) indicating that the server is refusing to process the + * request because the request entity is larger than the server is willing + * or able to process. + */ + public static final int SC_REQUEST_ENTITY_TOO_LARGE = 413; + + /** + * Status code (414) indicating that the server is refusing to service the + * request because the Request-URI is longer than the + * server is willing to interpret. + */ + public static final int SC_REQUEST_URI_TOO_LONG = 414; + + /** + * Status code (415) indicating that the server is refusing to service the + * request because the entity of the request is in a format not supported by + * the requested resource for the requested method. + */ + public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415; + + /** + * Status code (416) indicating that the server cannot serve the requested + * byte range. + */ + public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE = 416; + + /** + * Status code (417) indicating that the server could not meet the + * expectation given in the Expect request header. + */ + public static final int SC_EXPECTATION_FAILED = 417; + + /** + * Status code (500) indicating an error inside the HTTP server which + * prevented it from fulfilling the request. + */ + public static final int SC_INTERNAL_SERVER_ERROR = 500; + + /** + * Status code (501) indicating the HTTP server does not support the + * functionality needed to fulfill the request. + */ + public static final int SC_NOT_IMPLEMENTED = 501; + + /** + * Status code (502) indicating that the HTTP server received an invalid + * response from a server it consulted when acting as a proxy or gateway. + */ + public static final int SC_BAD_GATEWAY = 502; + + /** + * Status code (503) indicating that the HTTP server is temporarily + * overloaded, and unable to handle the request. + */ + public static final int SC_SERVICE_UNAVAILABLE = 503; + + /** + * Status code (504) indicating that the server did not receive a timely + * response from the upstream server while acting as a gateway or proxy. + */ + public static final int SC_GATEWAY_TIMEOUT = 504; + + /** + * Status code (505) indicating that the server does not support or refuses + * to support the HTTP protocol version that was used in the request + * message. + */ + public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505; +} diff --git a/lib/servlet-api/javax/servlet/http/HttpServletResponseWrapper.java b/lib/servlet-api/javax/servlet/http/HttpServletResponseWrapper.java new file mode 100644 index 00000000..aafc95fb --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpServletResponseWrapper.java @@ -0,0 +1,270 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.io.IOException; +import java.util.Collection; + +import javax.servlet.ServletResponseWrapper; + +/** + * Provides a convenient implementation of the HttpServletResponse interface + * that can be subclassed by developers wishing to adapt the response from a + * Servlet. This class implements the Wrapper or Decorator pattern. Methods + * default to calling through to the wrapped response object. + * + * @since v 2.3 + * @see javax.servlet.http.HttpServletResponse + */ +public class HttpServletResponseWrapper extends ServletResponseWrapper + implements HttpServletResponse { + + /** + * Constructs a response adaptor wrapping the given response. + * + * @throws java.lang.IllegalArgumentException + * if the response is null + */ + public HttpServletResponseWrapper(HttpServletResponse response) { + super(response); + } + + private HttpServletResponse _getHttpServletResponse() { + return (HttpServletResponse) super.getResponse(); + } + + /** + * The default behavior of this method is to call addCookie(Cookie cookie) + * on the wrapped response object. + */ + @Override + public void addCookie(Cookie cookie) { + this._getHttpServletResponse().addCookie(cookie); + } + + /** + * The default behavior of this method is to call containsHeader(String + * name) on the wrapped response object. + */ + @Override + public boolean containsHeader(String name) { + return this._getHttpServletResponse().containsHeader(name); + } + + /** + * The default behavior of this method is to call encodeURL(String url) on + * the wrapped response object. + */ + @Override + public String encodeURL(String url) { + return this._getHttpServletResponse().encodeURL(url); + } + + /** + * The default behavior of this method is to return encodeRedirectURL(String + * url) on the wrapped response object. + */ + @Override + public String encodeRedirectURL(String url) { + return this._getHttpServletResponse().encodeRedirectURL(url); + } + + /** + * The default behavior of this method is to call encodeUrl(String url) on + * the wrapped response object. + * + * @deprecated As of Version 3.0 of the Java Servlet API + */ + @Override + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String encodeUrl(String url) { + return this._getHttpServletResponse().encodeUrl(url); + } + + /** + * The default behavior of this method is to return encodeRedirectUrl(String + * url) on the wrapped response object. + * + * @deprecated As of Version 3.0 of the Java Servlet API + */ + @Override + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String encodeRedirectUrl(String url) { + return this._getHttpServletResponse().encodeRedirectUrl(url); + } + + /** + * The default behavior of this method is to call sendError(int sc, String + * msg) on the wrapped response object. + */ + @Override + public void sendError(int sc, String msg) throws IOException { + this._getHttpServletResponse().sendError(sc, msg); + } + + /** + * The default behavior of this method is to call sendError(int sc) on the + * wrapped response object. + */ + @Override + public void sendError(int sc) throws IOException { + this._getHttpServletResponse().sendError(sc); + } + + /** + * The default behavior of this method is to return sendRedirect(String + * location) on the wrapped response object. + */ + @Override + public void sendRedirect(String location) throws IOException { + this._getHttpServletResponse().sendRedirect(location); + } + + /** + * The default behavior of this method is to call setDateHeader(String name, + * long date) on the wrapped response object. + */ + @Override + public void setDateHeader(String name, long date) { + this._getHttpServletResponse().setDateHeader(name, date); + } + + /** + * The default behavior of this method is to call addDateHeader(String name, + * long date) on the wrapped response object. + */ + @Override + public void addDateHeader(String name, long date) { + this._getHttpServletResponse().addDateHeader(name, date); + } + + /** + * The default behavior of this method is to return setHeader(String name, + * String value) on the wrapped response object. + */ + @Override + public void setHeader(String name, String value) { + this._getHttpServletResponse().setHeader(name, value); + } + + /** + * The default behavior of this method is to return addHeader(String name, + * String value) on the wrapped response object. + */ + @Override + public void addHeader(String name, String value) { + this._getHttpServletResponse().addHeader(name, value); + } + + /** + * The default behavior of this method is to call setIntHeader(String name, + * int value) on the wrapped response object. + */ + @Override + public void setIntHeader(String name, int value) { + this._getHttpServletResponse().setIntHeader(name, value); + } + + /** + * The default behavior of this method is to call addIntHeader(String name, + * int value) on the wrapped response object. + */ + @Override + public void addIntHeader(String name, int value) { + this._getHttpServletResponse().addIntHeader(name, value); + } + + /** + * The default behavior of this method is to call setStatus(int sc) on the + * wrapped response object. + */ + @Override + public void setStatus(int sc) { + this._getHttpServletResponse().setStatus(sc); + } + + /** + * The default behavior of this method is to call setStatus(int sc, String + * sm) on the wrapped response object. + * + * @deprecated As of Version 3.0 of the Java Servlet API + */ + @Override + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public void setStatus(int sc, String sm) { + this._getHttpServletResponse().setStatus(sc, sm); + } + + /** + * {@inheritDoc} + *

+ * The default implementation is to call + * {@link HttpServletResponse#getStatus()} + * on the wrapper {@link HttpServletResponse}. + * + * @since Servlet 3.0 + */ + @Override + public int getStatus() { + return this._getHttpServletResponse().getStatus(); + } + + /** + * {@inheritDoc} + *

+ * The default implementation is to call + * {@link HttpServletResponse#getHeader(String)} + * on the wrapper {@link HttpServletResponse}. + * + * @since Servlet 3.0 + */ + @Override + public String getHeader(String name) { + return this._getHttpServletResponse().getHeader(name); + } + + /** + * {@inheritDoc} + *

+ * The default implementation is to call + * {@link HttpServletResponse#getHeaders(String)} + * on the wrapper {@link HttpServletResponse}. + * + * @since Servlet 3.0 + */ + @Override + public Collection getHeaders(String name) { + return this._getHttpServletResponse().getHeaders(name); + } + + /** + * {@inheritDoc} + *

+ * The default implementation is to call + * {@link HttpServletResponse#getHeaderNames()} + * on the wrapper {@link HttpServletResponse}. + * + * @since Servlet 3.0 + */ + @Override + public Collection getHeaderNames() { + return this._getHttpServletResponse().getHeaderNames(); + } +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSession.java b/lib/servlet-api/javax/servlet/http/HttpSession.java new file mode 100644 index 00000000..d15b97c1 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSession.java @@ -0,0 +1,284 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.util.Enumeration; + +import javax.servlet.ServletContext; + +/** + * Provides a way to identify a user across more than one page request or visit + * to a Web site and to store information about that user. + *

+ * The servlet container uses this interface to create a session between an HTTP + * client and an HTTP server. The session persists for a specified time period, + * across more than one connection or page request from the user. A session + * usually corresponds to one user, who may visit a site many times. The server + * can maintain a session in many ways such as using cookies or rewriting URLs. + *

+ * This interface allows servlets to + *

    + *
  • View and manipulate information about a session, such as the session + * identifier, creation time, and last accessed time + *
  • Bind objects to sessions, allowing user information to persist across + * multiple user connections + *
+ *

+ * When an application stores an object in or removes an object from a session, + * the session checks whether the object implements + * {@link HttpSessionBindingListener}. If it does, the servlet notifies the + * object that it has been bound to or unbound from the session. Notifications + * are sent after the binding methods complete. For session that are invalidated + * or expire, notifications are sent after the session has been invalidated or + * expired. + *

+ * When container migrates a session between VMs in a distributed container + * setting, all session attributes implementing the + * {@link HttpSessionActivationListener} interface are notified. + *

+ * A servlet should be able to handle cases in which the client does not choose + * to join a session, such as when cookies are intentionally turned off. Until + * the client joins the session, isNew returns true. + * If the client chooses not to join the session, getSession will + * return a different session on each request, and isNew will + * always return true. + *

+ * Session information is scoped only to the current web application ( + * ServletContext), so information stored in one context will not + * be directly visible in another. + * + * @see HttpSessionBindingListener + */ +public interface HttpSession { + + /** + * Returns the time when this session was created, measured in milliseconds + * since midnight January 1, 1970 GMT. + * + * @return a long specifying when this session was created, + * expressed in milliseconds since 1/1/1970 GMT + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public long getCreationTime(); + + /** + * Returns a string containing the unique identifier assigned to this + * session. The identifier is assigned by the servlet container and is + * implementation dependent. + * + * @return a string specifying the identifier assigned to this session + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public String getId(); + + /** + * Returns the last time the client sent a request associated with this + * session, as the number of milliseconds since midnight January 1, 1970 + * GMT, and marked by the time the container received the request. + *

+ * Actions that your application takes, such as getting or setting a value + * associated with the session, do not affect the access time. + * + * @return a long representing the last time the client sent a + * request associated with this session, expressed in milliseconds + * since 1/1/1970 GMT + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public long getLastAccessedTime(); + + /** + * Returns the ServletContext to which this session belongs. + * + * @return The ServletContext object for the web application + * @since 2.3 + */ + public ServletContext getServletContext(); + + /** + * Specifies the time, in seconds, between client requests before the + * servlet container will invalidate this session. A zero or negative time + * indicates that the session should never timeout. + * + * @param interval + * An integer specifying the number of seconds + */ + public void setMaxInactiveInterval(int interval); + + /** + * Returns the maximum time interval, in seconds, that the servlet container + * will keep this session open between client accesses. After this interval, + * the servlet container will invalidate the session. The maximum time + * interval can be set with the setMaxInactiveInterval method. + * A zero or negative time indicates that the session should never timeout. + * + * @return an integer specifying the number of seconds this session remains + * open between client requests + * @see #setMaxInactiveInterval + */ + public int getMaxInactiveInterval(); + + /** + * @deprecated As of Version 2.1, this method is deprecated and has no + * replacement. It will be removed in a future version of the + * Java Servlet API. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public HttpSessionContext getSessionContext(); + + /** + * Returns the object bound with the specified name in this session, or + * null if no object is bound under the name. + * + * @param name + * a string specifying the name of the object + * @return the object with the specified name + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public Object getAttribute(String name); + + /** + * @param name + * a string specifying the name of the object + * @return the object with the specified name + * @exception IllegalStateException + * if this method is called on an invalidated session + * @deprecated As of Version 2.2, this method is replaced by + * {@link #getAttribute}. + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public Object getValue(String name); + + /** + * Returns an Enumeration of String objects + * containing the names of all the objects bound to this session. + * + * @return an Enumeration of String objects + * specifying the names of all the objects bound to this session + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public Enumeration getAttributeNames(); + + /** + * @return an array of String objects specifying the names of + * all the objects bound to this session + * @exception IllegalStateException + * if this method is called on an invalidated session + * @deprecated As of Version 2.2, this method is replaced by + * {@link #getAttributeNames} + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public String[] getValueNames(); + + /** + * Binds an object to this session, using the name specified. If an object + * of the same name is already bound to the session, the object is replaced. + *

+ * After this method executes, and if the new object implements + * HttpSessionBindingListener, the container calls + * HttpSessionBindingListener.valueBound. The container then + * notifies any HttpSessionAttributeListeners in the web + * application. + *

+ * If an object was already bound to this session of this name that + * implements HttpSessionBindingListener, its + * HttpSessionBindingListener.valueUnbound method is called. + *

+ * If the value passed in is null, this has the same effect as calling + * removeAttribute(). + * + * @param name + * the name to which the object is bound; cannot be null + * @param value + * the object to be bound + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public void setAttribute(String name, Object value); + + /** + * @param name + * the name to which the object is bound; cannot be null + * @param value + * the object to be bound; cannot be null + * @exception IllegalStateException + * if this method is called on an invalidated session + * @deprecated As of Version 2.2, this method is replaced by + * {@link #setAttribute} + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public void putValue(String name, Object value); + + /** + * Removes the object bound with the specified name from this session. If + * the session does not have an object bound with the specified name, this + * method does nothing. + *

+ * After this method executes, and if the object implements + * HttpSessionBindingListener, the container calls + * HttpSessionBindingListener.valueUnbound. The container then + * notifies any HttpSessionAttributeListeners in the web + * application. + * + * @param name + * the name of the object to remove from this session + * @exception IllegalStateException + * if this method is called on an invalidated session + */ + public void removeAttribute(String name); + + /** + * @param name + * the name of the object to remove from this session + * @exception IllegalStateException + * if this method is called on an invalidated session + * @deprecated As of Version 2.2, this method is replaced by + * {@link #removeAttribute} + */ + @SuppressWarnings("dep-ann") + // Spec API does not use @Deprecated + public void removeValue(String name); + + /** + * Invalidates this session then unbinds any objects bound to it. + * + * @exception IllegalStateException + * if this method is called on an already invalidated session + */ + public void invalidate(); + + /** + * Returns true if the client does not yet know about the + * session or if the client chooses not to join the session. For example, if + * the server used only cookie-based sessions, and the client had disabled + * the use of cookies, then a session would be new on each request. + * + * @return true if the server has created a session, but the + * client has not yet joined + * @exception IllegalStateException + * if this method is called on an already invalidated session + */ + public boolean isNew(); +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionActivationListener.java b/lib/servlet-api/javax/servlet/http/HttpSessionActivationListener.java new file mode 100644 index 00000000..eace111e --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionActivationListener.java @@ -0,0 +1,37 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet.http; + +import java.util.EventListener; + + /** Objects that are bound to a session may listen to container + ** events notifying them that sessions will be passivated and that + ** session will be activated. A container that migrates session between VMs + ** or persists sessions is required to notify all attributes bound to sessions + ** implementing HttpSessionActivationListener. + ** + * @since 2.3 + */ + +public interface HttpSessionActivationListener extends EventListener { + + /** Notification that the session is about to be passivated.*/ + public void sessionWillPassivate(HttpSessionEvent se); + /** Notification that the session has just been activated.*/ + public void sessionDidActivate(HttpSessionEvent se); +} + diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionAttributeListener.java b/lib/servlet-api/javax/servlet/http/HttpSessionAttributeListener.java new file mode 100644 index 00000000..0c8f9caa --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionAttributeListener.java @@ -0,0 +1,46 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.util.EventListener; + +/** + * This listener interface can be implemented in order to get notifications of + * changes to the attribute lists of sessions within this web application. + * + * @since v 2.3 + */ +public interface HttpSessionAttributeListener extends EventListener { + + /** + * Notification that an attribute has been added to a session. Called after + * the attribute is added. + */ + public void attributeAdded(HttpSessionBindingEvent se); + + /** + * Notification that an attribute has been removed from a session. Called + * after the attribute is removed. + */ + public void attributeRemoved(HttpSessionBindingEvent se); + + /** + * Notification that an attribute has been replaced in a session. Called + * after the attribute is replaced. + */ + public void attributeReplaced(HttpSessionBindingEvent se); +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionBindingEvent.java b/lib/servlet-api/javax/servlet/http/HttpSessionBindingEvent.java new file mode 100644 index 00000000..a921719a --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionBindingEvent.java @@ -0,0 +1,111 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet.http; + +/** + * Events of this type are either sent to an object that implements + * {@link HttpSessionBindingListener} when it is bound or unbound from a + * session, or to a {@link HttpSessionAttributeListener} that has been + * configured in the deployment descriptor when any attribute is bound, unbound + * or replaced in a session. + *

+ * The session binds the object by a call to + * HttpSession.setAttribute and unbinds the object by a call to + * HttpSession.removeAttribute. + * + * @see HttpSession + * @see HttpSessionBindingListener + * @see HttpSessionAttributeListener + */ +public class HttpSessionBindingEvent extends HttpSessionEvent { + + private static final long serialVersionUID = 1L; + + /* The name to which the object is being bound or unbound */ + private final String name; + + /* The object is being bound or unbound */ + private final Object value; + + /** + * Constructs an event that notifies an object that it has been bound to or + * unbound from a session. To receive the event, the object must implement + * {@link HttpSessionBindingListener}. + * + * @param session + * the session to which the object is bound or unbound + * @param name + * the name with which the object is bound or unbound + * @see #getName + * @see #getSession + */ + public HttpSessionBindingEvent(HttpSession session, String name) { + super(session); + this.name = name; + this.value = null; + } + + /** + * Constructs an event that notifies an object that it has been bound to or + * unbound from a session. To receive the event, the object must implement + * {@link HttpSessionBindingListener}. + * + * @param session + * the session to which the object is bound or unbound + * @param name + * the name with which the object is bound or unbound + * @see #getName + * @see #getSession + */ + public HttpSessionBindingEvent(HttpSession session, String name, + Object value) { + super(session); + this.name = name; + this.value = value; + } + + /** Return the session that changed. */ + @Override + public HttpSession getSession() { + return super.getSession(); + } + + /** + * Returns the name with which the attribute is bound to or unbound from the + * session. + * + * @return a string specifying the name with which the object is bound to or + * unbound from the session + */ + public String getName() { + return name; + } + + /** + * Returns the value of the attribute that has been added, removed or + * replaced. If the attribute was added (or bound), this is the value of the + * attribute. If the attribute was removed (or unbound), this is the value + * of the removed attribute. If the attribute was replaced, this is the old + * value of the attribute. + * + * @since 2.3 + */ + public Object getValue() { + return this.value; + } +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionBindingListener.java b/lib/servlet-api/javax/servlet/http/HttpSessionBindingListener.java new file mode 100644 index 00000000..a09845e5 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionBindingListener.java @@ -0,0 +1,53 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet.http; + +import java.util.EventListener; + +/** + * Causes an object to be notified when it is bound to or unbound from a + * session. The object is notified by an {@link HttpSessionBindingEvent} object. + * This may be as a result of a servlet programmer explicitly unbinding an + * attribute from a session, due to a session being invalidated, or due to a + * session timing out. + * + * @see HttpSession + * @see HttpSessionBindingEvent + */ +public interface HttpSessionBindingListener extends EventListener { + + /** + * Notifies the object that it is being bound to a session and identifies + * the session. + * + * @param event + * the event that identifies the session + * @see #valueUnbound + */ + public void valueBound(HttpSessionBindingEvent event); + + /** + * Notifies the object that it is being unbound from a session and + * identifies the session. + * + * @param event + * the event that identifies the session + * @see #valueBound + */ + public void valueUnbound(HttpSessionBindingEvent event); +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionContext.java b/lib/servlet-api/javax/servlet/http/HttpSessionContext.java new file mode 100644 index 00000000..2a7e18b1 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionContext.java @@ -0,0 +1,49 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package javax.servlet.http; + +import java.util.Enumeration; + +/** + * @deprecated As of Java(tm) Servlet API 2.1 for security reasons, with no + * replacement. This interface will be removed in a future version + * of this API. + * @see HttpSession + * @see HttpSessionBindingEvent + * @see HttpSessionBindingListener + */ +@SuppressWarnings("dep-ann") +// Spec API does not use @Deprecated +public interface HttpSessionContext { + + /** + * @deprecated As of Java Servlet API 2.1 with no replacement. This method + * must return null and will be removed in a future version of + * this API. + */ + // Spec API does not use @Deprecated + public HttpSession getSession(String sessionId); + + /** + * @deprecated As of Java Servlet API 2.1 with no replacement. This method + * must return an empty Enumeration and will be + * removed in a future version of this API. + */ + // Spec API does not use @Deprecated + public Enumeration getIds(); +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionEvent.java b/lib/servlet-api/javax/servlet/http/HttpSessionEvent.java new file mode 100644 index 00000000..ef83877f --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionEvent.java @@ -0,0 +1,37 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +/** + * This is the class representing event notifications for changes to sessions + * within a web application. + * + * @since v 2.3 + */ +public class HttpSessionEvent extends java.util.EventObject { + private static final long serialVersionUID = 1L; + + /** Construct a session event from the given source. */ + public HttpSessionEvent(HttpSession source) { + super(source); + } + + /** Return the session that changed. */ + public HttpSession getSession() { + return (HttpSession) super.getSource(); + } +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionIdListener.java b/lib/servlet-api/javax/servlet/http/HttpSessionIdListener.java new file mode 100644 index 00000000..0c3c0c23 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionIdListener.java @@ -0,0 +1,41 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.util.EventListener; + +/** + * Implementations of this interface are notified when an {@link HttpSession}'s + * ID changes. To receive notification events, the implementation class must be + * configured in the deployment descriptor for the web application, annotated + * with {@link javax.servlet.annotation.WebListener} or registered by calling an + * addListener method on the {@link javax.servlet.ServletContext}. + * + * @see HttpSessionEvent + * @see HttpServletRequest#changeSessionId() + * @since Servlet 3.1 + */ +public interface HttpSessionIdListener extends EventListener { + + /** + * Notification that a session ID has been changed. + * + * @param se the notification event + * @param oldSessionId the old session ID + */ + public void sessionIdChanged(HttpSessionEvent se, String oldSessionId); +} diff --git a/lib/servlet-api/javax/servlet/http/HttpSessionListener.java b/lib/servlet-api/javax/servlet/http/HttpSessionListener.java new file mode 100644 index 00000000..a0f10093 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpSessionListener.java @@ -0,0 +1,48 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.util.EventListener; + +/** + * Implementations of this interface are notified of changes to the list of + * active sessions in a web application. To receive notification events, the + * implementation class must be configured in the deployment descriptor for the + * web application. + * + * @see HttpSessionEvent + * @since v 2.3 + */ +public interface HttpSessionListener extends EventListener { + + /** + * Notification that a session was created. + * + * @param se + * the notification event + */ + public void sessionCreated(HttpSessionEvent se); + + /** + * Notification that a session is about to be invalidated. + * + * @param se + * the notification event + */ + public void sessionDestroyed(HttpSessionEvent se); + +} diff --git a/lib/servlet-api/javax/servlet/http/HttpUpgradeHandler.java b/lib/servlet-api/javax/servlet/http/HttpUpgradeHandler.java new file mode 100644 index 00000000..095200cd --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpUpgradeHandler.java @@ -0,0 +1,42 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +/** + * Interface between the HTTP upgrade process and the new protocol. + * + * @since Servlet 3.1 + */ +public interface HttpUpgradeHandler { + + /** + * This method is called once the request/response pair where + * {@link HttpServletRequest#upgrade(Class)} is called has completed + * processing and is the point where control of the connection passes from + * the container to the {@link HttpUpgradeHandler}. + * + * @param connection The connection that has been upgraded + * + * @since Servlet 3.1 + */ + void init(WebConnection connection); + + /** + * This method is called after the upgraded connection has been closed. + */ + void destroy(); +} diff --git a/lib/servlet-api/javax/servlet/http/HttpUtils.java b/lib/servlet-api/javax/servlet/http/HttpUtils.java new file mode 100644 index 00000000..a0b4971d --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/HttpUtils.java @@ -0,0 +1,282 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +package javax.servlet.http; + +import java.io.IOException; +import java.util.Hashtable; +import java.util.ResourceBundle; +import java.util.StringTokenizer; + +import javax.servlet.ServletInputStream; + +/** + * @deprecated As of Java(tm) Servlet API 2.3. + * These methods were only useful + * with the default encoding and have been moved + * to the request interfaces. + */ +@SuppressWarnings("dep-ann") // Spec API does not use @Deprecated +public class HttpUtils { + + private static final String LSTRING_FILE = + "javax.servlet.http.LocalStrings"; + private static final ResourceBundle lStrings = + ResourceBundle.getBundle(LSTRING_FILE); + + + /** + * Constructs an empty HttpUtils object. + * + */ + public HttpUtils() { + // NOOP + } + + + /** + * + * Parses a query string passed from the client to the + * server and builds a HashTable object + * with key-value pairs. + * The query string should be in the form of a string + * packaged by the GET or POST method, that is, it + * should have key-value pairs in the form key=value, + * with each pair separated from the next by a & character. + * + *

A key can appear more than once in the query string + * with different values. However, the key appears only once in + * the hashtable, with its value being + * an array of strings containing the multiple values sent + * by the query string. + * + *

The keys and values in the hashtable are stored in their + * decoded form, so + * any + characters are converted to spaces, and characters + * sent in hexadecimal notation (like %xx) are + * converted to ASCII characters. + * + * @param s a string containing the query to be parsed + * + * @return a HashTable object built + * from the parsed key-value pairs + * + * @exception IllegalArgumentException if the query string + * is invalid + * + */ + public static Hashtable parseQueryString(String s) { + + String valArray[] = null; + + if (s == null) { + throw new IllegalArgumentException(); + } + Hashtable ht = new Hashtable<>(); + StringBuilder sb = new StringBuilder(); + StringTokenizer st = new StringTokenizer(s, "&"); + while (st.hasMoreTokens()) { + String pair = st.nextToken(); + int pos = pair.indexOf('='); + if (pos == -1) { + // XXX + // should give more detail about the illegal argument + throw new IllegalArgumentException(); + } + String key = parseName(pair.substring(0, pos), sb); + String val = parseName(pair.substring(pos+1, pair.length()), sb); + if (ht.containsKey(key)) { + String oldVals[] = ht.get(key); + valArray = new String[oldVals.length + 1]; + for (int i = 0; i < oldVals.length; i++) + valArray[i] = oldVals[i]; + valArray[oldVals.length] = val; + } else { + valArray = new String[1]; + valArray[0] = val; + } + ht.put(key, valArray); + } + return ht; + } + + + /** + * + * Parses data from an HTML form that the client sends to + * the server using the HTTP POST method and the + * application/x-www-form-urlencoded MIME type. + * + *

The data sent by the POST method contains key-value + * pairs. A key can appear more than once in the POST data + * with different values. However, the key appears only once in + * the hashtable, with its value being + * an array of strings containing the multiple values sent + * by the POST method. + * + *

The keys and values in the hashtable are stored in their + * decoded form, so + * any + characters are converted to spaces, and characters + * sent in hexadecimal notation (like %xx) are + * converted to ASCII characters. + * + * + * + * @param len an integer specifying the length, + * in characters, of the + * ServletInputStream + * object that is also passed to this + * method + * + * @param in the ServletInputStream + * object that contains the data sent + * from the client + * + * @return a HashTable object built + * from the parsed key-value pairs + * + * + * @exception IllegalArgumentException if the data + * sent by the POST method is invalid + * + */ + public static Hashtable parsePostData(int len, + ServletInputStream in) { + // XXX + // should a length of 0 be an IllegalArgumentException + + // cheap hack to return an empty hash + if (len <=0) + return new Hashtable<>(); + + if (in == null) { + throw new IllegalArgumentException(); + } + + // Make sure we read the entire POSTed body. + byte[] postedBytes = new byte [len]; + try { + int offset = 0; + + do { + int inputLen = in.read (postedBytes, offset, len - offset); + if (inputLen <= 0) { + String msg = lStrings.getString("err.io.short_read"); + throw new IllegalArgumentException (msg); + } + offset += inputLen; + } while ((len - offset) > 0); + + } catch (IOException e) { + throw new IllegalArgumentException(e.getMessage(), e); + } + + // XXX we shouldn't assume that the only kind of POST body + // is FORM data encoded using ASCII or ISO Latin/1 ... or + // that the body should always be treated as FORM data. + try { + String postedBody = new String(postedBytes, 0, len, "8859_1"); + return parseQueryString(postedBody); + } catch (java.io.UnsupportedEncodingException e) { + // XXX function should accept an encoding parameter & throw this + // exception. Otherwise throw something expected. + throw new IllegalArgumentException(e.getMessage(), e); + } + } + + + /* + * Parse a name in the query string. + */ + private static String parseName(String s, StringBuilder sb) { + sb.setLength(0); + for (int i = 0; i < s.length(); i++) { + char c = s.charAt(i); + switch (c) { + case '+': + sb.append(' '); + break; + case '%': + try { + sb.append((char) Integer.parseInt(s.substring(i+1, i+3), + 16)); + i += 2; + } catch (NumberFormatException e) { + // XXX + // need to be more specific about illegal arg + throw new IllegalArgumentException(); + } catch (StringIndexOutOfBoundsException e) { + String rest = s.substring(i); + sb.append(rest); + if (rest.length()==2) + i++; + } + + break; + default: + sb.append(c); + break; + } + } + return sb.toString(); + } + + + /** + * + * Reconstructs the URL the client used to make the request, + * using information in the HttpServletRequest object. + * The returned URL contains a protocol, server name, port + * number, and server path, but it does not include query + * string parameters. + * + *

Because this method returns a StringBuffer, + * not a string, you can modify the URL easily, for example, + * to append query parameters. + * + *

This method is useful for creating redirect messages + * and for reporting errors. + * + * @param req a HttpServletRequest object + * containing the client's request + * + * @return a StringBuffer object containing + * the reconstructed URL + * + */ + public static StringBuffer getRequestURL (HttpServletRequest req) { + StringBuffer url = new StringBuffer (); + String scheme = req.getScheme (); + int port = req.getServerPort (); + String urlPath = req.getRequestURI(); + + url.append (scheme); // http, https + url.append ("://"); + url.append (req.getServerName ()); + if ((scheme.equals ("http") && port != 80) + || (scheme.equals ("https") && port != 443)) { + url.append (':'); + url.append (req.getServerPort ()); + } + + url.append(urlPath); + return url; + } +} + + + diff --git a/lib/servlet-api/javax/servlet/http/LocalStrings.properties b/lib/servlet-api/javax/servlet/http/LocalStrings.properties new file mode 100644 index 00000000..a9def622 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/LocalStrings.properties @@ -0,0 +1,30 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Default localized string information +# Localized for Locale en_US + +err.cookie_name_is_token=Cookie name \"{0}\" is a reserved token +err.cookie_name_blank=Cookie name may not be null or zero length +err.io.nullArray=Null passed for byte array in write method +err.io.indexOutOfBounds=Invalid offset [{0}] and / or length [{1}] specified for array of size [{2}] +err.io.short_read=Short Read + +http.method_not_implemented=Method {0} is not is not implemented by this servlet for this URI + +http.method_get_not_supported=HTTP method GET is not supported by this URL +http.method_post_not_supported=HTTP method POST is not supported by this URL +http.method_put_not_supported=HTTP method PUT is not supported by this URL +http.method_delete_not_supported=Http method DELETE is not supported by this URL diff --git a/lib/servlet-api/javax/servlet/http/LocalStrings_es.properties b/lib/servlet-api/javax/servlet/http/LocalStrings_es.properties new file mode 100644 index 00000000..31fc0d8b --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/LocalStrings_es.properties @@ -0,0 +1,23 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +err.cookie_name_is_token = El nombre de Cookie {0} es una palabra reservada +err.cookie_name_blank = El nombre del Cookie no puede ser nulo o de longitud cero +err.io.negativelength = Longitud Negativa en el metodo write +err.io.short_read = Lectura Corta +http.method_not_implemented = El Metodo {0} no esta implementado por este servlet para esta URI +http.method_get_not_supported = El Metodo HTTP GET no est\u00E1 soportado por esta URL +http.method_post_not_supported = El Metodo HTTP POST no est\u00E1 soportado por esta URL +http.method_put_not_supported = El Metodo HTTP PUT no est\u00E1 soportado por esta URL +http.method_delete_not_supported = El Metodo HTTP DELETE no es soportado por esta URL diff --git a/lib/servlet-api/javax/servlet/http/LocalStrings_fr.properties b/lib/servlet-api/javax/servlet/http/LocalStrings_fr.properties new file mode 100644 index 00000000..18fd1c09 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/LocalStrings_fr.properties @@ -0,0 +1,28 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Default localized string information +# Localized for Locale fr_FR + +err.cookie_name_is_token=Le nom de cookie \"{0}\" est un \"token\" r\u00e9serv\u00e9 +err.io.negativelength=Taille n\u00e9gative donn\u00e9e dans la m\u00e9thode \"write\" +err.io.short_read=Lecture partielle + +http.method_not_implemented=Le m\u00e9thode {0} n''est pas d\u00e9finie dans la RFC 2068 et n''est pas support\u00e9e par l''API Servlet + +http.method_get_not_supported=La m\u00e9thode HTTP GET n''est pas support\u00e9e par cette URL +http.method_post_not_supported=La m\u00e9thode HTTP POST n''est pas support\u00e9e par cette URL +http.method_put_not_supported=La m\u00e9thode HTTP PUT n''est pas support\u00e9e par cette URL +http.method_delete_not_supported=La m\u00e9thode HTTP DELETE n''est pas support\u00e9e par cette URL diff --git a/lib/servlet-api/javax/servlet/http/LocalStrings_ja.properties b/lib/servlet-api/javax/servlet/http/LocalStrings_ja.properties new file mode 100644 index 00000000..70983d78 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/LocalStrings_ja.properties @@ -0,0 +1,28 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Default localized string information +# Localized for Locale ja_JP + +err.cookie_name_is_token=\u30af\u30c3\u30ad\u30fc\u540d \"{0}\" \u306f\u4e88\u7d04\u6e08\u306e\u30c8\u30fc\u30af\u30f3\u3067\u3059\u3002 +err.io.negativelength=write\u30e1\u30bd\u30c3\u30c9\u306b\u8ca0\u306e\u9577\u3055\u304c\u6307\u5b9a\u3055\u308c\u307e\u3057\u305f\u3002 +err.io.short_read=\u8aad\u307f\u8fbc\u307f\u304c\u3059\u3050\u306b\u7d42\u308f\u308a\u307e\u3057\u305f\u3002 + +http.method_not_implemented=\u30e1\u30bd\u30c3\u30c9 {0} \u306fRFC 2068\u306b\u306f\u5b9a\u7fa9\u3055\u308c\u3066\u304a\u3089\u305a\u3001\u30b5\u30fc\u30d6\u30ec\u30c3\u30c8API\u3067\u306f\u30b5\u30dd\u30fc\u30c8\u3055\u308c\u307e\u305b\u3093\u3002 + +http.method_get_not_supported=HTTP\u306eGET\u30e1\u30bd\u30c3\u30c9\u306f\u3001\u3053\u306eURL\u3067\u306f\u30b5\u30dd\u30fc\u30c8\u3055\u308c\u3066\u3044\u307e\u305b\u3093\u3002 +http.method_post_not_supported=HTTP\u306ePOST\u30e1\u30bd\u30c3\u30c9\u306f\u3001\u3053\u306eURL\u3067\u306f\u30b5\u30dd\u30fc\u30c8\u3055\u308c\u3066\u3044\u307e\u305b\u3093\u3002 +http.method_put_not_supported=HTTP\u306ePUT\u30e1\u30bd\u30c3\u30c9\u306f\u3001\u3053\u306eURL\u3067\u306f\u30b5\u30dd\u30fc\u30c8\u3055\u308c\u3066\u3044\u307e\u305b\u3093\u3002 +http.method_delete_not_supported=HTTP\u306eDELETE\u30e1\u30bd\u30c3\u30c9\u306f\u3001\u3053\u306eURL\u3067\u306f\u30b5\u30dd\u30fc\u30c8\u3055\u308c\u3066\u3044\u307e\u305b\u3093\u3002 diff --git a/lib/servlet-api/javax/servlet/http/Part.java b/lib/servlet-api/javax/servlet/http/Part.java new file mode 100644 index 00000000..6d08de4d --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/Part.java @@ -0,0 +1,118 @@ +/* +* Licensed to the Apache Software Foundation (ASF) under one or more +* contributor license agreements. See the NOTICE file distributed with +* this work for additional information regarding copyright ownership. +* The ASF licenses this file to You under the Apache License, Version 2.0 +* (the "License"); you may not use this file except in compliance with +* the License. You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ +package javax.servlet.http; + +import java.io.IOException; +import java.io.InputStream; +import java.util.Collection; + +/** + * This class represents a part as uploaded to the server as part of a + * multipart/form-data request body. The part may represent either + * an uploaded file or form data. + * + * @since Servlet 3.0 + */ +public interface Part { + + /** + * Obtain an InputStream that can be used to retrieve the + * contents of the file. + */ + public InputStream getInputStream() throws IOException; + + /** + * Obtain the content type passed by the browser or null if not + * defined. + */ + public String getContentType(); + + /** + * Obtain the name of the field in the multipart form corresponding to this + * part. + */ + public String getName(); + + /** + * If this part represents an uploaded file, gets the file name submitted + * in the upload. Returns {@code null} if no file name is available or if + * this part is not a file upload. + * + * @return the submitted file name or {@code null}. + * + * @since Servlet 3.1 + */ + public String getSubmittedFileName(); + + /** + * Obtain the size of this part. + */ + public long getSize(); + + /** + * A convenience method to write an uploaded part to disk. The client code + * is not concerned with whether or not the part is stored in memory, or on + * disk in a temporary location. They just want to write the uploaded part + * to a file. + * + * This method is not guaranteed to succeed if called more than once for + * the same part. This allows a particular implementation to use, for + * example, file renaming, where possible, rather than copying all of the + * underlying data, thus gaining a significant performance benefit. + * + * @param fileName The location into which the uploaded part should be + * stored. Relative locations are relative to {@link + * javax.servlet.MultipartConfigElement#getLocation()} + */ + public void write(String fileName) throws IOException; + + /** + * Deletes the underlying storage for a part, including deleting any + * associated temporary disk file. Although the container will delete this + * storage automatically this method can be used to ensure that this is done + * at an earlier time, thus preserving system resources. + *

+ * Containers are only required to delete the associated storage when the + * Part instance is garbage collected. Apache Tomcat will delete the + * associated storage when the associated request has finished processing. + * Behaviour of other containers may be different. + */ + public void delete() throws IOException; + + /** + * Obtains the value of the specified part header as a String. If there are + * multiple headers with the same name, this method returns the first header + * in the part. The header name is case insensitive. + * + * @param name Header name + * @return The header value or null if the header is not + * present + */ + public String getHeader(String name); + + /** + * Obtain all the values of the specified part header. If the part did not + * include any headers of the specified name, this method returns an empty + * Collection. The header name is case insensitive. + */ + public Collection getHeaders(String name); + + /** + * Returns a Collection of all the header names provided for this part. + */ + public Collection getHeaderNames(); +} diff --git a/lib/servlet-api/javax/servlet/http/WebConnection.java b/lib/servlet-api/javax/servlet/http/WebConnection.java new file mode 100644 index 00000000..06193606 --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/WebConnection.java @@ -0,0 +1,43 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package javax.servlet.http; + +import java.io.IOException; + +import javax.servlet.ServletInputStream; +import javax.servlet.ServletOutputStream; + +/** + * The interface used by a {@link HttpUpgradeHandler} to interact with an upgraded + * HTTP connection. + * + * @since Servlet 3.1 + */ +public interface WebConnection extends AutoCloseable { + + /** + * Provides access to the {@link ServletInputStream} for reading data from + * the client. + */ + ServletInputStream getInputStream() throws IOException; + + /** + * Provides access to the {@link ServletOutputStream} for writing data to + * the client. + */ + ServletOutputStream getOutputStream() throws IOException; +} \ No newline at end of file diff --git a/lib/servlet-api/javax/servlet/http/package.html b/lib/servlet-api/javax/servlet/http/package.html new file mode 100644 index 00000000..08e6692f --- /dev/null +++ b/lib/servlet-api/javax/servlet/http/package.html @@ -0,0 +1,30 @@ + + + + + + + +The javax.servlet.http package contains a number of classes and interfaces +that describe and define the contracts between a servlet class +running under the HTTP protocol and the runtime environment provided +for an instance of such a class by a conforming servlet container. + + + + diff --git a/lib/servlet-api/javax/servlet/package.html b/lib/servlet-api/javax/servlet/package.html new file mode 100644 index 00000000..7336be67 --- /dev/null +++ b/lib/servlet-api/javax/servlet/package.html @@ -0,0 +1,30 @@ + + + + + + + +The javax.servlet package contains a number of classes and interfaces that +describe and define the contracts between a servlet class and the +runtime environment provided for an instance of such a class by a +conforming servlet container. + + + + -- 2.39.2