This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/7.0.x by this push:
new 3f4a457 Fix Javadoc warnings by copying updated Javadoc from 8.5.x
3f4a457 is described below
commit 3f4a45763cd39b01ef3253c95215895d30295d51
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Sat Sep 7 23:45:48 2019 +0100
Fix Javadoc warnings by copying updated Javadoc from 8.5.x
---
java/javax/servlet/FilterChain.java | 4 ++
java/javax/servlet/FilterConfig.java | 6 ++-
java/javax/servlet/FilterRegistration.java | 34 ++++++++++----
java/javax/servlet/HttpConstraintElement.java | 41 +++++++++++++---
java/javax/servlet/Registration.java | 54 +++++++++++++++++-----
.../servlet/ServletContextAttributeEvent.java | 15 ++++--
java/javax/servlet/ServletRequestWrapper.java | 12 +++--
java/javax/servlet/ServletResponse.java | 10 ++--
java/javax/servlet/ServletResponseWrapper.java | 24 ++++++++--
java/javax/servlet/ServletSecurityElement.java | 8 ++--
java/javax/servlet/SessionCookieConfig.java | 48 +++++++++++++------
java/javax/servlet/http/HttpServletRequest.java | 18 ++++++--
.../servlet/http/HttpServletRequestWrapper.java | 2 +
java/javax/servlet/http/HttpServletResponse.java | 16 ++++++-
.../servlet/http/HttpServletResponseWrapper.java | 11 +++--
java/javax/servlet/http/HttpSession.java | 2 +
.../http/HttpSessionActivationListener.java | 31 ++++++++-----
.../servlet/http/HttpSessionAttributeListener.java | 6 +++
.../servlet/http/HttpSessionBindingEvent.java | 27 +++++++----
java/javax/servlet/http/HttpSessionContext.java | 7 ++-
java/javax/servlet/http/HttpSessionEvent.java | 12 ++++-
java/javax/servlet/http/Part.java | 31 ++++++++++---
22 files changed, 313 insertions(+), 106 deletions(-)
diff --git a/java/javax/servlet/FilterChain.java
b/java/javax/servlet/FilterChain.java
index cdc5206..fca19c3 100644
--- a/java/javax/servlet/FilterChain.java
+++ b/java/javax/servlet/FilterChain.java
@@ -41,6 +41,10 @@ public interface FilterChain {
* @param response
* the response to pass along the chain.
*
+ * @throws IOException if an I/O error occurs during the processing of the
+ * request
+ * @throws ServletException if the processing fails for any other reason
+
* @since 2.3
*/
public void doFilter(ServletRequest request, ServletResponse response)
diff --git a/java/javax/servlet/FilterConfig.java
b/java/javax/servlet/FilterConfig.java
index 4a0a65b..5e3c44b 100644
--- a/java/javax/servlet/FilterConfig.java
+++ b/java/javax/servlet/FilterConfig.java
@@ -30,8 +30,10 @@ import java.util.Enumeration;
public interface FilterConfig {
/**
- * Returns the filter-name of this filter as defined in the deployment
- * descriptor.
+ * Get the name of the filter.
+ *
+ * @return The filter-name of this filter as defined in the deployment
+ * descriptor.
*/
public String getFilterName();
diff --git a/java/javax/servlet/FilterRegistration.java
b/java/javax/servlet/FilterRegistration.java
index 52d9596..b9b10ed 100644
--- a/java/javax/servlet/FilterRegistration.java
+++ b/java/javax/servlet/FilterRegistration.java
@@ -26,12 +26,19 @@ import java.util.EnumSet;
public interface FilterRegistration extends Registration {
/**
+ * Add a mapping for this filter to one or more named Servlets.
*
- * @param dispatcherTypes
- * @param isMatchAfter
- * @param servletNames
- * @throws IllegalArgumentException
- * @throws IllegalStateException
+ * @param dispatcherTypes The dispatch types to which this filter should
+ * apply
+ * @param isMatchAfter Should this filter be applied after any mappings
+ * defined in the deployment descriptor
+ * (<code>true</code>) or before?
+ * @param servletNames Requests mapped to these servlets will be
+ * processed by this filter
+ * @throws IllegalArgumentException if the list of servlet names is empty
+ * or null
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void addMappingForServletNames(
EnumSet<DispatcherType> dispatcherTypes,
@@ -43,12 +50,19 @@ public interface FilterRegistration extends Registration {
public Collection<String> getServletNameMappings();
/**
+ * Add a mapping for this filter to one or more URL patterns.
*
- * @param dispatcherTypes
- * @param isMatchAfter
- * @param urlPatterns
- * @throws IllegalArgumentException
- * @throws IllegalStateException
+ * @param dispatcherTypes The dispatch types to which this filter should
+ * apply
+ * @param isMatchAfter Should this filter be applied after any mappings
+ * defined in the deployment descriptor
+ * (<code>true</code>) or before?
+ * @param urlPatterns The URL patterns to which this filter should be
+ * applied
+ * @throws IllegalArgumentException if the list of URL patterns is empty or
+ * null
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void addMappingForUrlPatterns(
EnumSet<DispatcherType> dispatcherTypes,
diff --git a/java/javax/servlet/HttpConstraintElement.java
b/java/javax/servlet/HttpConstraintElement.java
index c7a4f93..389fb73 100644
--- a/java/javax/servlet/HttpConstraintElement.java
+++ b/java/javax/servlet/HttpConstraintElement.java
@@ -22,8 +22,10 @@ import
javax.servlet.annotation.ServletSecurity.EmptyRoleSemantic;
import javax.servlet.annotation.ServletSecurity.TransportGuarantee;
/**
+ * Equivalent of {@link javax.servlet.annotation.HttpConstraint} for
+ * programmatic configuration of security constraints.
+ *
* @since Servlet 3.0
- * TODO SERVLET3 - Add comments
*/
public class HttpConstraintElement {
@@ -46,8 +48,11 @@ public class HttpConstraintElement {
}
/**
- * Convenience constructor for {@link EmptyRoleSemantic#DENY}.
+ * Construct a constraint with an empty role semantic. Typically used with
+ * {@link EmptyRoleSemantic#DENY}.
*
+ * @param emptyRoleSemantic The empty role semantic to apply to the newly
+ * created constraint
*/
public HttpConstraintElement(EmptyRoleSemantic emptyRoleSemantic) {
this.emptyRoleSemantic = emptyRoleSemantic;
@@ -56,7 +61,12 @@ public class HttpConstraintElement {
}
/**
- * Convenience constructor to specify transport guarantee and/or roles.
+ * Construct a constraint with a transport guarantee and roles.
+ *
+ * @param transportGuarantee The transport guarantee to apply to the newly
+ * created constraint
+ * @param rolesAllowed The roles to associate with the newly created
+ * constraint
*/
public HttpConstraintElement(TransportGuarantee transportGuarantee,
String... rolesAllowed) {
@@ -66,10 +76,15 @@ public class HttpConstraintElement {
}
/**
+ * Construct a constraint with an empty role semantic, a transport
guarantee
+ * and roles.
*
- * @param emptyRoleSemantic
- * @param transportGuarantee
- * @param rolesAllowed
+ * @param emptyRoleSemantic The empty role semantic to apply to the newly
+ * created constraint
+ * @param transportGuarantee The transport guarantee to apply to the newly
+ * created constraint
+ * @param rolesAllowed The roles to associate with the newly created
+ * constraint
* @throws IllegalArgumentException if roles are specified when DENY is
used
*/
public HttpConstraintElement(EmptyRoleSemantic emptyRoleSemantic,
@@ -84,15 +99,27 @@ public class HttpConstraintElement {
this.rolesAllowed = rolesAllowed;
}
+ /**
+ * TODO
+ * @return TODO
+ */
public EmptyRoleSemantic getEmptyRoleSemantic() {
return emptyRoleSemantic;
}
+ /**
+ * TODO
+ * @return TODO
+ */
public TransportGuarantee getTransportGuarantee() {
return transportGuarantee;
}
+ /**
+ * TODO
+ * @return TODO
+ */
public String[] getRolesAllowed() {
return rolesAllowed;
}
-}
\ No newline at end of file
+}
diff --git a/java/javax/servlet/Registration.java
b/java/javax/servlet/Registration.java
index fa9f4ec..3eebca5 100644
--- a/java/javax/servlet/Registration.java
+++ b/java/javax/servlet/Registration.java
@@ -20,7 +20,7 @@ import java.util.Map;
import java.util.Set;
/**
- * TODO SERVLET3 - Add comments
+ * Common interface for the registration of Filters and Servlets.
* @since Servlet 3.0
*/
public interface Registration {
@@ -30,34 +30,64 @@ public interface Registration {
public String getClassName();
/**
+ * Add an initialisation parameter if not already added.
*
- * @param name
- * @param value
- * @return TODO
- * @throws IllegalArgumentException
- * @throws IllegalStateException
+ * @param name Name of initialisation parameter
+ * @param value Value of initialisation parameter
+ * @return <code>true</code> if the initialisation parameter was set,
+ * <code>false</code> if the initialisation parameter was not set
+ * because an initialisation parameter of the same name already
+ * existed
+ * @throws IllegalArgumentException if name or value is <code>null</code>
+ * @throws IllegalStateException if the ServletContext associated with this
+ * registration has already been initialised
*/
public boolean setInitParameter(String name, String value);
+ /**
+ * Get the value of an initialisation parameter.
+ *
+ * @param name The initialisation parameter whose value is required
+ *
+ * @return The value of the named initialisation parameter
+ */
public String getInitParameter(String name);
/**
+ * Add multiple initialisation parameters. If any of the supplied
+ * initialisation parameter conflicts with an existing initialisation
+ * parameter, no updates will be performed.
+ *
+ * @param initParameters The initialisation parameters to add
*
- * @param initParameters
- * @return TODO
- * @throws IllegalArgumentException
- * @throws IllegalStateException
+ * @return The set of initialisation parameter names that conflicted with
+ * existing initialisation parameter. If there are no conflicts,
+ * this Set will be empty.
+ * @throws IllegalArgumentException if any of the supplied initialisation
+ * parameters have a null name or value
+ * @throws IllegalStateException if the ServletContext associated with this
+ * registration has already been initialised
*/
public Set<String> setInitParameters(Map<String,String> initParameters);
+ /**
+ * Get the names and values of all the initialisation parameters.
+ *
+ * @return A Map of initialisation parameter names and associated values
+ * keyed by name
+ */
public Map<String, String> getInitParameters();
public interface Dynamic extends Registration {
/**
+ * Mark this Servlet/Filter as supported asynchronous processing.
+ *
+ * @param isAsyncSupported Should this Servlet/Filter support
+ * asynchronous processing
*
- * @param isAsyncSupported
- * @throws IllegalStateException
+ * @throws IllegalStateException if the ServletContext associated with
+ * this registration has already been initialised
*/
public void setAsyncSupported(boolean isAsyncSupported);
}
diff --git a/java/javax/servlet/ServletContextAttributeEvent.java
b/java/javax/servlet/ServletContextAttributeEvent.java
index b1bf727..9373b81 100644
--- a/java/javax/servlet/ServletContextAttributeEvent.java
+++ b/java/javax/servlet/ServletContextAttributeEvent.java
@@ -32,6 +32,10 @@ public class ServletContextAttributeEvent extends
ServletContextEvent {
/**
* Construct a ServletContextAttributeEvent from the given context for the
* given attribute name and attribute value.
+ *
+ * @param source The ServletContext associated with this attribute event
+ * @param name The name of the servlet context attribute
+ * @param value The value of the servlet context attribute
*/
public ServletContextAttributeEvent(ServletContext source, String name,
Object value) {
@@ -42,6 +46,8 @@ public class ServletContextAttributeEvent extends
ServletContextEvent {
/**
* Return the name of the attribute that changed on the ServletContext.
+ *
+ * @return The name of the attribute that changed
*/
public String getName() {
return this.name;
@@ -49,9 +55,12 @@ public class ServletContextAttributeEvent extends
ServletContextEvent {
/**
* 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.
+ * replaced.
+ *
+ * @return 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/java/javax/servlet/ServletRequestWrapper.java
b/java/javax/servlet/ServletRequestWrapper.java
index 4fcbdca..51220e8 100644
--- a/java/javax/servlet/ServletRequestWrapper.java
+++ b/java/javax/servlet/ServletRequestWrapper.java
@@ -28,7 +28,7 @@ import java.util.Map;
* class implements the Wrapper or Decorator pattern. Methods default to
calling
* through to the wrapped request object.
*
- * @since v 2.3
+ * @since Servlet 2.3
* @see javax.servlet.ServletRequest
*/
public class ServletRequestWrapper implements ServletRequest {
@@ -37,6 +37,8 @@ public class ServletRequestWrapper implements ServletRequest {
/**
* Creates a ServletRequest adaptor wrapping the given request object.
*
+ * @param request The request to wrap
+ *
* @throws IllegalArgumentException if the request is null
*/
public ServletRequestWrapper(ServletRequest request) {
@@ -301,7 +303,7 @@ public class ServletRequestWrapper implements
ServletRequest {
* The default behavior of this method is to return getRemotePort() on the
* wrapped request object.
*
- * @since 2.4
+ * @since Servlet 2.4
*/
@Override
public int getRemotePort() {
@@ -312,7 +314,7 @@ public class ServletRequestWrapper implements
ServletRequest {
* The default behavior of this method is to return getLocalName() on the
* wrapped request object.
*
- * @since 2.4
+ * @since Servlet 2.4
*/
@Override
public String getLocalName() {
@@ -323,7 +325,7 @@ public class ServletRequestWrapper implements
ServletRequest {
* The default behavior of this method is to return getLocalAddr() on the
* wrapped request object.
*
- * @since 2.4
+ * @since Servlet 2.4
*/
@Override
public String getLocalAddr() {
@@ -334,7 +336,7 @@ public class ServletRequestWrapper implements
ServletRequest {
* The default behavior of this method is to return getLocalPort() on the
* wrapped request object.
*
- * @since 2.4
+ * @since Servlet 2.4
*/
@Override
public int getLocalPort() {
diff --git a/java/javax/servlet/ServletResponse.java
b/java/javax/servlet/ServletResponse.java
index 51cedc0..b650c8c 100644
--- a/java/javax/servlet/ServletResponse.java
+++ b/java/javax/servlet/ServletResponse.java
@@ -45,7 +45,6 @@ import java.util.Locale;
* RFC 2045</a> for more information on MIME. Protocols such as SMTP and HTTP
* define profiles of MIME, and those standards are still evolving.
*
- * @author Various
* @see ServletOutputStream
*/
public interface ServletResponse {
@@ -243,6 +242,8 @@ public interface ServletResponse {
* this method automatically commits the response, meaning the status code
* and headers will be written.
*
+ * @throws IOException if an I/O occurs during the flushing of the response
+ *
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
@@ -328,8 +329,11 @@ public interface ServletResponse {
/**
* Returns the locale specified for this response using the
* {@link #setLocale} method. Calls made to <code>setLocale</code> after
the
- * response is committed have no effect. If no locale has been specified,
- * the container's default locale is returned.
+ * response is committed have no effect.
+ *
+ * @return The locale specified for this response using the
+ * {@link #setLocale} method. If no locale has been specified, the
+ * container's default locale is returned.
*
* @see #setLocale
*/
diff --git a/java/javax/servlet/ServletResponseWrapper.java
b/java/javax/servlet/ServletResponseWrapper.java
index 3f0940b..56ed652 100644
--- a/java/javax/servlet/ServletResponseWrapper.java
+++ b/java/javax/servlet/ServletResponseWrapper.java
@@ -26,7 +26,6 @@ import java.util.Locale;
* This class implements the Wrapper or Decorator pattern. Methods default to
* calling through to the wrapped response object.
*
- * @author Various
* @since v 2.3
* @see javax.servlet.ServletResponse
*/
@@ -36,6 +35,8 @@ public class ServletResponseWrapper implements
ServletResponse {
/**
* Creates a ServletResponse adaptor wrapping the given response object.
*
+ * @param response The response to wrap
+ *
* @throws java.lang.IllegalArgumentException
* if the response is null.
*/
@@ -48,6 +49,8 @@ public class ServletResponseWrapper implements
ServletResponse {
/**
* Return the wrapped ServletResponse object.
+ *
+ * @return The wrapped ServletResponse object.
*/
public ServletResponse getResponse() {
return this.response;
@@ -56,6 +59,8 @@ public class ServletResponseWrapper implements
ServletResponse {
/**
* Sets the response being wrapped.
*
+ * @param response The new response to wrap
+ *
* @throws java.lang.IllegalArgumentException
* if the response is null.
*/
@@ -206,8 +211,12 @@ public class ServletResponseWrapper implements
ServletResponse {
}
/**
- * @param wrapped
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * TODO SERVLET3 - Add comments
+ * @param wrapped The response to compare to the wrapped response
+ * @return <code>true</code> if the response wrapped by this wrapper (or
+ * series of wrappers) is the same as the supplied response,
+ * otherwise <code>false</code>
+ * @since Servlet 3.0
*/
public boolean isWrapperFor(ServletResponse wrapped) {
if (response == wrapped) {
@@ -220,8 +229,13 @@ public class ServletResponseWrapper implements
ServletResponse {
}
/**
- * @param wrappedType
- * @since Servlet 3.0 TODO SERVLET3 - Add comments
+ * TODO SERVLET3 - Add comments
+ * @param wrappedType The class to compare to the class of the wrapped
+ * response
+ * @return <code>true</code> if the response wrapped by this wrapper (or
+ * series of wrappers) is the same type as the supplied type,
+ * otherwise <code>false</code>
+ * @since Servlet 3.0
*/
@SuppressWarnings("unchecked")
// Spec API does not use generics
diff --git a/java/javax/servlet/ServletSecurityElement.java
b/java/javax/servlet/ServletSecurityElement.java
index 56667b4..59126e6 100644
--- a/java/javax/servlet/ServletSecurityElement.java
+++ b/java/javax/servlet/ServletSecurityElement.java
@@ -47,7 +47,7 @@ public class ServletSecurityElement extends
HttpConstraintElement {
/**
* Use specific constraints for specified methods and default
* HttpConstraintElement for all other methods.
- * @param httpMethodConstraints
+ * @param httpMethodConstraints Method constraints
* @throws IllegalArgumentException if a method name is specified more than
* once
*/
@@ -68,8 +68,8 @@ public class ServletSecurityElement extends
HttpConstraintElement {
/**
* Use specified HttpConstraintElement as default and specific constraints
* for specified methods.
- * @param httpConstraintElement
- * @param httpMethodConstraints
+ * @param httpConstraintElement Default constraint
+ * @param httpMethodConstraints Method constraints
* @throws IllegalArgumentException if a method name is specified more than
*/
public ServletSecurityElement(HttpConstraintElement httpConstraintElement,
@@ -82,7 +82,7 @@ public class ServletSecurityElement extends
HttpConstraintElement {
/**
* Create from an annotation.
- * @param annotation
+ * @param annotation Annotation to use as the basis for the new instance
* @throws IllegalArgumentException if a method name is specified more than
*/
public ServletSecurityElement(ServletSecurity annotation) {
diff --git a/java/javax/servlet/SessionCookieConfig.java
b/java/javax/servlet/SessionCookieConfig.java
index 11567c0..564a4ed 100644
--- a/java/javax/servlet/SessionCookieConfig.java
+++ b/java/javax/servlet/SessionCookieConfig.java
@@ -17,61 +17,80 @@
package javax.servlet;
/**
+ * Configures the session cookies used by the web application associated with
+ * the ServletContext from which this SessionCookieConfig was obtained.
*
- * TODO SERVLET3 - Add comments
* @since Servlet 3.0
*/
public interface SessionCookieConfig {
/**
+ * Sets the session cookie name.
*
- * @param name
- * @throws IllegalStateException
+ * @param name The name of the session cookie
+ *
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setName(String name);
public String getName();
/**
+ * Sets the domain for the session cookie
+ *
+ * @param domain The session cookie domain
*
- * @param domain
- * @throws IllegalStateException
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setDomain(String domain);
public String getDomain();
/**
+ * Sets the path of the session cookie.
+ *
+ * @param path The session cookie path
*
- * @param path
- * @throws IllegalStateException
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setPath(String path);
public String getPath();
/**
+ * Sets the comment for the session cookie
*
- * @param comment
- * @throws IllegalStateException
+ * @param comment The session cookie comment
+ *
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setComment(String comment);
public String getComment();
/**
+ * Sets the httpOnly flag for the session cookie.
+ *
+ * @param httpOnly The httpOnly setting to use for session cookies
*
- * @param httpOnly
- * @throws IllegalStateException
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setHttpOnly(boolean httpOnly);
public boolean isHttpOnly();
/**
+ * Sets the secure flag for the session cookie.
+ *
+ * @param secure The secure setting to use for session cookies
*
- * @param secure
- * @throws IllegalStateException
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setSecure(boolean secure);
@@ -81,7 +100,8 @@ public interface SessionCookieConfig {
* Sets the maximum age.
*
* @param MaxAge the maximum age to set
- * @throws IllegalStateException
+ * @throws IllegalStateException if the associated ServletContext has
+ * already been initialised
*/
public void setMaxAge(int MaxAge);
diff --git a/java/javax/servlet/http/HttpServletRequest.java
b/java/javax/servlet/http/HttpServletRequest.java
index 4c449d1..0c3f7f8 100644
--- a/java/javax/servlet/http/HttpServletRequest.java
+++ b/java/javax/servlet/http/HttpServletRequest.java
@@ -289,8 +289,9 @@ public interface HttpServletRequest extends ServletRequest {
* 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:
- * <table summary="Examples of Returned Values">
- * <tr align=left>
+ * <table>
+ * <caption>Examples of Returned Values</caption>
+ * <tr>
* <th>First line of HTTP request</th>
* <th>Returned Value</th>
* <tr>
@@ -412,6 +413,7 @@ public interface HttpServletRequest extends ServletRequest {
public boolean isRequestedSessionIdFromURL();
/**
+ * @return {@link #isRequestedSessionIdFromURL()}
* @deprecated As of Version 2.1 of the Java Servlet API, use
* {@link #isRequestedSessionIdFromURL} instead.
*/
@@ -428,6 +430,12 @@ public interface HttpServletRequest extends ServletRequest
{
* @return <code>true</code> if the user is successfully authenticated and
* <code>false</code> if not
*
+ * @throws IOException if the authentication process attempted to read from
+ * the request or write to the response and an I/O error occurred
+ * @throws IllegalStateException if the authentication process attempted to
+ * write to the response after it had been committed
+ * @throws ServletException if the authentication failed and the caller is
+ * expected to handle the failure
* @since Servlet 3.0
*/
public boolean authenticate(HttpServletResponse response)
@@ -466,7 +474,8 @@ public interface HttpServletRequest extends ServletRequest {
* @throws IOException
* if an I/O error occurs
* @throws IllegalStateException
- * if size limits are exceeded
+ * 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
@@ -478,7 +487,8 @@ public interface HttpServletRequest extends ServletRequest {
* Gets the named Part or null if the Part does not exist. Triggers upload
* of all Parts.
*
- * @param name
+ * @param name The name of the Part to obtain
+ *
* @return The named Part or null if the Part does not exist
* @throws IOException
* if an I/O error occurs
diff --git a/java/javax/servlet/http/HttpServletRequestWrapper.java
b/java/javax/servlet/http/HttpServletRequestWrapper.java
index a4cf333..e44d92c 100644
--- a/java/javax/servlet/http/HttpServletRequestWrapper.java
+++ b/java/javax/servlet/http/HttpServletRequestWrapper.java
@@ -38,6 +38,8 @@ public class HttpServletRequestWrapper extends
ServletRequestWrapper implements
/**
* Constructs a request object wrapping the given request.
*
+ * @param request The request to wrap
+ *
* @throws java.lang.IllegalArgumentException
* if the request is null
*/
diff --git a/java/javax/servlet/http/HttpServletResponse.java
b/java/javax/servlet/http/HttpServletResponse.java
index c5c6f82..0d48e7f 100644
--- a/java/javax/servlet/http/HttpServletResponse.java
+++ b/java/javax/servlet/http/HttpServletResponse.java
@@ -296,7 +296,9 @@ public interface HttpServletResponse extends
ServletResponse {
public void setStatus(int sc, String sm);
/**
- * Return the HTTP status code associated with this Response.
+ * Get the HTTP status code for this Response.
+ *
+ * @return The HTTP status code for this Response
*
* @since Servlet 3.0
*/
@@ -310,6 +312,10 @@ public interface HttpServletResponse extends
ServletResponse {
*
* @param name Header name to look up
*
+ * @return The first value for the specified header. This is the raw value
+ * so if multiple values are specified in the first header then
they
+ * will be returned as a single header value .
+ *
* @since Servlet 3.0
*/
public String getHeader(String name);
@@ -320,12 +326,18 @@ public interface HttpServletResponse extends
ServletResponse {
*
* @param name Header name to look up
*
+ * @return The values for the specified header. These are the raw values so
+ * if multiple values are specified in a single header that will be
+ * returned as a single header value.
+ *
* @since Servlet 3.0
*/
public Collection<String> getHeaders(String name);
/**
- * Return an Iterable of all the header names set for this response.
+ * Get the header names set for this HTTP response.
+ *
+ * @return The header names set for this HTTP response.
*
* @since Servlet 3.0
*/
diff --git a/java/javax/servlet/http/HttpServletResponseWrapper.java
b/java/javax/servlet/http/HttpServletResponseWrapper.java
index 451c1f6..df98416 100644
--- a/java/javax/servlet/http/HttpServletResponseWrapper.java
+++ b/java/javax/servlet/http/HttpServletResponseWrapper.java
@@ -27,7 +27,6 @@ import javax.servlet.ServletResponseWrapper;
* Servlet. This class implements the Wrapper or Decorator pattern. Methods
* default to calling through to the wrapped response object.
*
- * @author Various
* @since v 2.3
* @see javax.servlet.http.HttpServletResponse
*/
@@ -37,6 +36,8 @@ public class HttpServletResponseWrapper extends
ServletResponseWrapper
/**
* Constructs a response adaptor wrapping the given response.
*
+ * @param response The response to be wrapped
+ *
* @throws java.lang.IllegalArgumentException
* if the response is null
*/
@@ -218,7 +219,7 @@ public class HttpServletResponseWrapper extends
ServletResponseWrapper
* <p>
* The default implementation is to call
* {@link HttpServletResponse#getStatus()}
- * on the wrapper {@link HttpServletResponse}.
+ * on the wrapped {@link HttpServletResponse}.
*
* @since Servlet 3.0
*/
@@ -232,7 +233,7 @@ public class HttpServletResponseWrapper extends
ServletResponseWrapper
* <p>
* The default implementation is to call
* {@link HttpServletResponse#getHeader(String)}
- * on the wrapper {@link HttpServletResponse}.
+ * on the wrapped {@link HttpServletResponse}.
*
* @since Servlet 3.0
*/
@@ -246,7 +247,7 @@ public class HttpServletResponseWrapper extends
ServletResponseWrapper
* <p>
* The default implementation is to call
* {@link HttpServletResponse#getHeaders(String)}
- * on the wrapper {@link HttpServletResponse}.
+ * on the wrapped {@link HttpServletResponse}.
*
* @since Servlet 3.0
*/
@@ -260,7 +261,7 @@ public class HttpServletResponseWrapper extends
ServletResponseWrapper
* <p>
* The default implementation is to call
* {@link HttpServletResponse#getHeaderNames()}
- * on the wrapper {@link HttpServletResponse}.
+ * on the wrapped {@link HttpServletResponse}.
*
* @since Servlet 3.0
*/
diff --git a/java/javax/servlet/http/HttpSession.java
b/java/javax/servlet/http/HttpSession.java
index d15b97c..2a731f5 100644
--- a/java/javax/servlet/http/HttpSession.java
+++ b/java/javax/servlet/http/HttpSession.java
@@ -135,6 +135,8 @@ public interface HttpSession {
public int getMaxInactiveInterval();
/**
+ * Do not use.
+ * @return A dummy implementation of HttpSessionContext
* @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.
diff --git a/java/javax/servlet/http/HttpSessionActivationListener.java
b/java/javax/servlet/http/HttpSessionActivationListener.java
index eace111..6caa070 100644
--- a/java/javax/servlet/http/HttpSessionActivationListener.java
+++ b/java/javax/servlet/http/HttpSessionActivationListener.java
@@ -18,20 +18,29 @@ 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
- */
-
+/**
+ * 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.*/
+ /**
+ * Notification that the session is about to be passivated.
+ *
+ * @param se Information about the session this is about to be passivated
+ */
public void sessionWillPassivate(HttpSessionEvent se);
- /** Notification that the session has just been activated.*/
+
+ /**
+ * Notification that the session has just been activated.
+ *
+ * @param se Information about the session this has just been activated
+ */
public void sessionDidActivate(HttpSessionEvent se);
}
diff --git a/java/javax/servlet/http/HttpSessionAttributeListener.java
b/java/javax/servlet/http/HttpSessionAttributeListener.java
index 0c8f9ca..a44dd0d 100644
--- a/java/javax/servlet/http/HttpSessionAttributeListener.java
+++ b/java/javax/servlet/http/HttpSessionAttributeListener.java
@@ -29,18 +29,24 @@ public interface HttpSessionAttributeListener extends
EventListener {
/**
* Notification that an attribute has been added to a session. Called after
* the attribute is added.
+ *
+ * @param se Information about the added attribute
*/
public void attributeAdded(HttpSessionBindingEvent se);
/**
* Notification that an attribute has been removed from a session. Called
* after the attribute is removed.
+ *
+ * @param se Information about the removed attribute
*/
public void attributeRemoved(HttpSessionBindingEvent se);
/**
* Notification that an attribute has been replaced in a session. Called
* after the attribute is replaced.
+ *
+ * @param se Information about the replaced attribute
*/
public void attributeReplaced(HttpSessionBindingEvent se);
}
diff --git a/java/javax/servlet/http/HttpSessionBindingEvent.java
b/java/javax/servlet/http/HttpSessionBindingEvent.java
index 1bc7814..91e5167 100644
--- a/java/javax/servlet/http/HttpSessionBindingEvent.java
+++ b/java/javax/servlet/http/HttpSessionBindingEvent.java
@@ -28,7 +28,6 @@ package javax.servlet.http;
* <code>HttpSession.setAttribute</code> and unbinds the object by a call to
* <code>HttpSession.removeAttribute</code>.
*
- * @author Various
* @see HttpSession
* @see HttpSessionBindingListener
* @see HttpSessionAttributeListener
@@ -52,8 +51,8 @@ public class HttpSessionBindingEvent extends HttpSessionEvent
{
* 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
+ * @see #getName()
+ * @see #getSession()
*/
public HttpSessionBindingEvent(HttpSession session, String name) {
super(session);
@@ -70,8 +69,11 @@ public class HttpSessionBindingEvent extends
HttpSessionEvent {
* 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
+ * @param value
+ * the object that is bound or unbound
+ * @see #getName()
+ * @see #getSession()
+ * @see #getValue()
*/
public HttpSessionBindingEvent(HttpSession session, String name,
Object value) {
@@ -80,7 +82,10 @@ public class HttpSessionBindingEvent extends
HttpSessionEvent {
this.value = value;
}
- /** Return the session that changed. */
+ /**
+ * Get the session that changed.
+ * @return The session that changed
+ */
@Override
public HttpSession getSession() {
return super.getSession();
@@ -99,10 +104,12 @@ public class HttpSessionBindingEvent extends
HttpSessionEvent {
/**
* 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.
+ * replaced.
+ *
+ * @return 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
*/
diff --git a/java/javax/servlet/http/HttpSessionContext.java
b/java/javax/servlet/http/HttpSessionContext.java
index 0ffbcec..13fb133 100644
--- a/java/javax/servlet/http/HttpSessionContext.java
+++ b/java/javax/servlet/http/HttpSessionContext.java
@@ -20,7 +20,7 @@ package javax.servlet.http;
import java.util.Enumeration;
/**
- * @author Various
+ * Do not use.
* @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.
@@ -33,6 +33,9 @@ import java.util.Enumeration;
public interface HttpSessionContext {
/**
+ * Do not use.
+ * @param sessionId Ignored
+ * @return Always <code>null</code>
* @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.
@@ -42,6 +45,8 @@ public interface HttpSessionContext {
public HttpSession getSession(String sessionId);
/**
+ * Do not use.
+ * @return Always an empty Enumeration
* @deprecated As of Java Servlet API 2.1 with no replacement. This method
* must return an empty <code>Enumeration</code> and will be
* removed in a future version of this API.
diff --git a/java/javax/servlet/http/HttpSessionEvent.java
b/java/javax/servlet/http/HttpSessionEvent.java
index ef83877..3a6ffcf 100644
--- a/java/javax/servlet/http/HttpSessionEvent.java
+++ b/java/javax/servlet/http/HttpSessionEvent.java
@@ -25,12 +25,20 @@ package javax.servlet.http;
public class HttpSessionEvent extends java.util.EventObject {
private static final long serialVersionUID = 1L;
- /** Construct a session event from the given source. */
+ /**
+ * Construct a session event from the given source.
+ *
+ * @param source The HTTP session where the change took place
+ */
public HttpSessionEvent(HttpSession source) {
super(source);
}
- /** Return the session that changed. */
+ /**
+ * Get the session that changed.
+ *
+ * @return The session that changed
+ */
public HttpSession getSession() {
return (HttpSession) super.getSource();
}
diff --git a/java/javax/servlet/http/Part.java
b/java/javax/servlet/http/Part.java
index 390c31e..870eec4 100644
--- a/java/javax/servlet/http/Part.java
+++ b/java/javax/servlet/http/Part.java
@@ -32,23 +32,34 @@ public interface Part {
/**
* Obtain an <code>InputStream</code> that can be used to retrieve the
* contents of the file.
+ *
+ * @return An InputStream for the contents of the file
+ *
+ * @throws IOException if an I/O occurs while obtaining the stream
*/
public InputStream getInputStream() throws IOException;
/**
- * Obtain the content type passed by the browser or <code>null</code> if
not
- * defined.
+ * Obtain the content type passed by the browser.
+ *
+ * @return The content type passed by the browser or <code>null</code> if
+ * not defined.
*/
public String getContentType();
/**
* Obtain the name of the field in the multipart form corresponding to this
* part.
+ *
+ * @return The name of the field in the multipart form corresponding to
this
+ * part.
*/
public String getName();
/**
* Obtain the size of this part.
+ *
+ * @return The size of the part if bytes
*/
public long getSize();
@@ -66,6 +77,8 @@ public interface Part {
* @param fileName The location into which the uploaded part should be
* stored. Relative locations are relative to {@link
* javax.servlet.MultipartConfigElement#getLocation()}
+ *
+ * @throws IOException if an I/O occurs while attempting to write the part
*/
public void write(String fileName) throws IOException;
@@ -79,6 +92,8 @@ public interface Part {
* 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.
+ *
+ * @throws IOException if an I/O occurs while attempting to delete the part
*/
public void delete() throws IOException;
@@ -94,14 +109,18 @@ public interface Part {
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.
+ * Obtain all the values of the specified part header.
+ * @param name The name of the header of interest. The header name is case
+ * insensitive.
+ * @return 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.
*/
public Collection<String> getHeaders(String name);
/**
- * Returns a Collection of all the header names provided for this part.
+ * Get the header names provided for this part.
+ * @return a Collection of all the header names provided for this part.
*/
public Collection<String> getHeaderNames();
}
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
