You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2024/06/13 12:20:25 UTC
(tomcat) branch 10.1.x updated: Code clean-up - formatting. No functional change.
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 10.1.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/10.1.x by this push:
new 62dd7de599 Code clean-up - formatting. No functional change.
62dd7de599 is described below
commit 62dd7de599d42436442f1e5c8886bc1adb392cc4
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Thu Jun 13 13:20:19 2024 +0100
Code clean-up - formatting. No functional change.
---
java/org/apache/catalina/AccessLog.java | 71 +-
java/org/apache/catalina/AsyncDispatcher.java | 13 +-
java/org/apache/catalina/Authenticator.java | 24 +-
java/org/apache/catalina/Cluster.java | 35 +-
java/org/apache/catalina/Contained.java | 15 +-
java/org/apache/catalina/Container.java | 274 +++----
java/org/apache/catalina/ContainerEvent.java | 12 +-
java/org/apache/catalina/ContainerListener.java | 5 +-
java/org/apache/catalina/ContainerServlet.java | 8 +-
java/org/apache/catalina/Context.java | 908 +++++++++------------
java/org/apache/catalina/CredentialHandler.java | 15 +-
java/org/apache/catalina/DistributedManager.java | 21 +-
java/org/apache/catalina/Engine.java | 30 +-
java/org/apache/catalina/Globals.java | 131 ++-
java/org/apache/catalina/Group.java | 17 +-
java/org/apache/catalina/Host.java | 129 ++-
java/org/apache/catalina/JmxEnabled.java | 16 +-
java/org/apache/catalina/Lifecycle.java | 143 ++--
java/org/apache/catalina/LifecycleEvent.java | 7 +-
java/org/apache/catalina/LifecycleException.java | 12 +-
java/org/apache/catalina/LifecycleListener.java | 7 +-
java/org/apache/catalina/LifecycleState.java | 12 +-
java/org/apache/catalina/Loader.java | 53 +-
java/org/apache/catalina/Manager.java | 242 +++---
java/org/apache/catalina/Pipeline.java | 107 ++-
java/org/apache/catalina/Realm.java | 165 ++--
java/org/apache/catalina/Role.java | 13 +-
java/org/apache/catalina/Server.java | 69 +-
java/org/apache/catalina/Service.java | 40 +-
java/org/apache/catalina/Session.java | 142 ++--
java/org/apache/catalina/SessionEvent.java | 4 +-
java/org/apache/catalina/SessionIdGenerator.java | 13 +-
java/org/apache/catalina/Store.java | 33 +-
java/org/apache/catalina/StoreManager.java | 10 +-
.../org/apache/catalina/ThreadBindingListener.java | 5 +-
java/org/apache/catalina/TomcatPrincipal.java | 68 +-
java/org/apache/catalina/TrackedWebResource.java | 1 +
java/org/apache/catalina/User.java | 29 +-
java/org/apache/catalina/UserDatabase.java | 54 +-
java/org/apache/catalina/Valve.java | 106 ++-
java/org/apache/catalina/WebResource.java | 53 +-
java/org/apache/catalina/WebResourceRoot.java | 353 ++++----
java/org/apache/catalina/WebResourceSet.java | 110 ++-
java/org/apache/catalina/Wrapper.java | 121 ++-
44 files changed, 1534 insertions(+), 2162 deletions(-)
diff --git a/java/org/apache/catalina/AccessLog.java b/java/org/apache/catalina/AccessLog.java
index 046facc265..9751a8ee67 100644
--- a/java/org/apache/catalina/AccessLog.java
+++ b/java/org/apache/catalina/AccessLog.java
@@ -21,71 +21,53 @@ import org.apache.catalina.connector.Response;
/**
- * Intended for use by a {@link Valve} to indicate that the {@link Valve}
- * provides access logging. It is used by the Tomcat internals to identify a
- * Valve that logs access requests so requests that are rejected
- * earlier in the processing chain can still be added to the access log.
- * Implementations of this interface should be robust against the provided
- * {@link Request} and {@link Response} objects being null, having null
- * attributes or any other 'oddness' that may result from attempting to log
- * a request that was almost certainly rejected because it was mal-formed.
+ * Intended for use by a {@link Valve} to indicate that the {@link Valve} provides access logging. It is used by the
+ * Tomcat internals to identify a Valve that logs access requests so requests that are rejected earlier in the
+ * processing chain can still be added to the access log. Implementations of this interface should be robust against the
+ * provided {@link Request} and {@link Response} objects being null, having null attributes or any other 'oddness' that
+ * may result from attempting to log a request that was almost certainly rejected because it was mal-formed.
*/
public interface AccessLog {
/**
- * Name of request attribute used to override the remote address recorded by
- * the AccessLog.
+ * Name of request attribute used to override the remote address recorded by the AccessLog.
*/
- String REMOTE_ADDR_ATTRIBUTE =
- "org.apache.catalina.AccessLog.RemoteAddr";
+ String REMOTE_ADDR_ATTRIBUTE = "org.apache.catalina.AccessLog.RemoteAddr";
/**
- * Name of request attribute used to override remote host name recorded by
- * the AccessLog.
+ * Name of request attribute used to override remote host name recorded by the AccessLog.
*/
- String REMOTE_HOST_ATTRIBUTE =
- "org.apache.catalina.AccessLog.RemoteHost";
+ String REMOTE_HOST_ATTRIBUTE = "org.apache.catalina.AccessLog.RemoteHost";
/**
- * Name of request attribute used to override the protocol recorded by the
- * AccessLog.
+ * Name of request attribute used to override the protocol recorded by the AccessLog.
*/
- String PROTOCOL_ATTRIBUTE =
- "org.apache.catalina.AccessLog.Protocol";
+ String PROTOCOL_ATTRIBUTE = "org.apache.catalina.AccessLog.Protocol";
/**
- * Name of request attribute used to override the server name recorded by
- * the AccessLog.
+ * Name of request attribute used to override the server name recorded by the AccessLog.
*/
- String SERVER_NAME_ATTRIBUTE =
- "org.apache.catalina.AccessLog.ServerName";
+ String SERVER_NAME_ATTRIBUTE = "org.apache.catalina.AccessLog.ServerName";
/**
- * Name of request attribute used to override the server port recorded by
- * the AccessLog.
+ * Name of request attribute used to override the server port recorded by the AccessLog.
*/
- String SERVER_PORT_ATTRIBUTE =
- "org.apache.catalina.AccessLog.ServerPort";
+ String SERVER_PORT_ATTRIBUTE = "org.apache.catalina.AccessLog.ServerPort";
/**
- * Add the request/response to the access log using the specified processing
- * time.
+ * Add the request/response to the access log using the specified processing time.
*
- * @param request Request (associated with the response) to log
- * @param response Response (associated with the request) to log
- * @param time Time taken to process the request/response in
- * nanoseconds (use 0 if not known); in Tomcat
- * versions prior to 10, the time unit was
- * milliseconds
+ * @param request Request (associated with the response) to log
+ * @param response Response (associated with the request) to log
+ * @param time Time taken to process the request/response in nanoseconds (use 0 if not known); in Tomcat
+ * versions prior to 10, the time unit was milliseconds
*/
void log(Request request, Response response, long time);
/**
- * Should this valve use request attributes for IP address, hostname,
- * protocol and port used for the request?
- *
- * The attributes used are:
+ * Should this valve use request attributes for IP address, hostname, protocol and port used for the request? The
+ * attributes used are:
* <ul>
* <li>org.apache.catalina.RemoteAddr</li>
* <li>org.apache.catalina.RemoteHost</li>
@@ -94,16 +76,15 @@ public interface AccessLog {
* <li>org.apache.catalina.ServerPost</li>
* </ul>
*
- * @param requestAttributesEnabled <code>true</code> causes the attributes
- * to be used, <code>false</code> causes
- * the original values to be used.
+ * @param requestAttributesEnabled <code>true</code> causes the attributes to be used, <code>false</code> causes the
+ * original values to be used.
*/
void setRequestAttributesEnabled(boolean requestAttributesEnabled);
/**
* @see #setRequestAttributesEnabled(boolean)
- * @return <code>true</code> if the attributes will be logged, otherwise
- * <code>false</code>
+ *
+ * @return <code>true</code> if the attributes will be logged, otherwise <code>false</code>
*/
boolean getRequestAttributesEnabled();
}
diff --git a/java/org/apache/catalina/AsyncDispatcher.java b/java/org/apache/catalina/AsyncDispatcher.java
index 84271d8519..3783fd1c69 100644
--- a/java/org/apache/catalina/AsyncDispatcher.java
+++ b/java/org/apache/catalina/AsyncDispatcher.java
@@ -25,15 +25,14 @@ import jakarta.servlet.ServletResponse;
public interface AsyncDispatcher {
/**
- * Perform an asynchronous dispatch. The method does not check if the
- * request is in an appropriate state for this; it is the caller's
- * responsibility to check this.
+ * Perform an asynchronous dispatch. The method does not check if the request is in an appropriate state for this;
+ * it is the caller's responsibility to check this.
+ *
* @param request The request object to pass to the dispatch target
* @param response The response object to pass to the dispatch target
+ *
* @throws ServletException if thrown by the dispatch target
- * @throws IOException if an I/O error occurs while processing the
- * dispatch
+ * @throws IOException if an I/O error occurs while processing the dispatch
*/
- void dispatch(ServletRequest request, ServletResponse response)
- throws ServletException, IOException;
+ void dispatch(ServletRequest request, ServletResponse response) throws ServletException, IOException;
}
diff --git a/java/org/apache/catalina/Authenticator.java b/java/org/apache/catalina/Authenticator.java
index 1a050d4c16..e314b5dd84 100644
--- a/java/org/apache/catalina/Authenticator.java
+++ b/java/org/apache/catalina/Authenticator.java
@@ -25,33 +25,29 @@ import org.apache.catalina.connector.Request;
/**
- * An <b>Authenticator</b> is a component (usually a Valve or Container) that
- * provides some sort of authentication service.
+ * An <b>Authenticator</b> is a component (usually a Valve or Container) that provides some sort of authentication
+ * service.
*
* @author Craig R. McClanahan
*/
public interface Authenticator {
/**
- * Authenticate the user making this request, based on the login
- * configuration of the {@link Context} with which this Authenticator is
- * associated.
+ * Authenticate the user making this request, based on the login configuration of the {@link Context} with which
+ * this Authenticator is associated.
*
- * @param request Request we are processing
+ * @param request Request we are processing
* @param response Response we are populating
*
- * @return <code>true</code> if any specified constraints have been
- * satisfied, or <code>false</code> if one more constraints were not
- * satisfied (in which case an authentication challenge will have
- * been written to the response).
+ * @return <code>true</code> if any specified constraints have been satisfied, or <code>false</code> if one more
+ * constraints were not satisfied (in which case an authentication challenge will have been written to
+ * the response).
*
* @exception IOException if an input/output error occurs
*/
- boolean authenticate(Request request, HttpServletResponse response)
- throws IOException;
+ boolean authenticate(Request request, HttpServletResponse response) throws IOException;
- void login(String userName, String password, Request request)
- throws ServletException;
+ void login(String userName, String password, Request request) throws ServletException;
void logout(Request request);
}
diff --git a/java/org/apache/catalina/Cluster.java b/java/org/apache/catalina/Cluster.java
index 6e216800ba..fc798d8f8f 100644
--- a/java/org/apache/catalina/Cluster.java
+++ b/java/org/apache/catalina/Cluster.java
@@ -17,13 +17,10 @@
package org.apache.catalina;
/**
- * A <b>Cluster</b> works as a Cluster client/server for the local host
- * Different Cluster implementations can be used to support different
- * ways to communicate within the Cluster. A Cluster implementation is
- * responsible for setting up a way to communicate within the Cluster
- * and also supply "ClientApplications" with <code>ClusterSender</code>
- * used when sending information in the Cluster and
- * <code>ClusterInfo</code> used for receiving information in the Cluster.
+ * A <b>Cluster</b> works as a Cluster client/server for the local host Different Cluster implementations can be used to
+ * support different ways to communicate within the Cluster. A Cluster implementation is responsible for setting up a
+ * way to communicate within the Cluster and also supply "ClientApplications" with <code>ClusterSender</code> used when
+ * sending information in the Cluster and <code>ClusterInfo</code> used for receiving information in the Cluster.
*
* @author Bip Thelin
* @author Remy Maucherat
@@ -31,8 +28,7 @@ package org.apache.catalina;
public interface Cluster extends Contained {
/**
- * Return the name of the cluster that this Server is currently
- * configured to operate within.
+ * Return the name of the cluster that this Server is currently configured to operate within.
*
* @return The name of the cluster associated with this server
*/
@@ -40,8 +36,7 @@ public interface Cluster extends Contained {
/**
- * Set the name of the cluster to join, if no cluster with
- * this name is present create one.
+ * Set the name of the cluster to join, if no cluster with this name is present create one.
*
* @param clusterName The clustername to join
*/
@@ -49,11 +44,9 @@ public interface Cluster extends Contained {
/**
- * Create a new manager which will use this cluster to replicate its
- * sessions.
+ * Create a new manager which will use this cluster to replicate its sessions.
*
- * @param name Name (key) of the application with which the manager is
- * associated
+ * @param name Name (key) of the application with which the manager is associated
*
* @return The newly created Manager instance
*/
@@ -61,9 +54,9 @@ public interface Cluster extends Contained {
/**
- * Register a manager with the cluster. If the cluster is not responsible
- * for creating a manager, then the container will at least notify the
- * cluster that this manager is participating in the cluster.
+ * Register a manager with the cluster. If the cluster is not responsible for creating a manager, then the container
+ * will at least notify the cluster that this manager is participating in the cluster.
+ *
* @param manager Manager
*/
void registerManager(Manager manager);
@@ -71,15 +64,15 @@ public interface Cluster extends Contained {
/**
* Removes a manager from the cluster
+ *
* @param manager Manager
*/
void removeManager(Manager manager);
/**
- * Execute a periodic task, such as reloading, etc. This method will be
- * invoked inside the classloading context of this container. Unexpected
- * throwables will be caught and logged.
+ * Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of
+ * this container. Unexpected throwables will be caught and logged.
*/
void backgroundProcess();
}
diff --git a/java/org/apache/catalina/Contained.java b/java/org/apache/catalina/Contained.java
index 72888938e7..891026e55e 100644
--- a/java/org/apache/catalina/Contained.java
+++ b/java/org/apache/catalina/Contained.java
@@ -17,8 +17,10 @@
package org.apache.catalina;
/**
- * <p>Decoupling interface which specifies that an implementing class is
- * associated with at most one <strong>Container</strong> instance.</p>
+ * <p>
+ * Decoupling interface which specifies that an implementing class is associated with at most one
+ * <strong>Container</strong> instance.
+ * </p>
*
* @author Craig R. McClanahan
* @author Peter Donald
@@ -28,8 +30,8 @@ public interface Contained {
/**
* Get the {@link Container} with which this instance is associated.
*
- * @return The Container with which this instance is associated or
- * <code>null</code> if not associated with a Container
+ * @return The Container with which this instance is associated or <code>null</code> if not associated with a
+ * Container
*/
Container getContainer();
@@ -37,9 +39,8 @@ public interface Contained {
/**
* Set the <code>Container</code> with which this instance is associated.
*
- * @param container The Container instance with which this instance is to
- * be associated, or <code>null</code> to disassociate this instance
- * from any Container
+ * @param container The Container instance with which this instance is to be associated, or <code>null</code> to
+ * disassociate this instance from any Container
*/
void setContainer(Container container);
}
diff --git a/java/org/apache/catalina/Container.java b/java/org/apache/catalina/Container.java
index fd897dc0f9..ede48b7984 100644
--- a/java/org/apache/catalina/Container.java
+++ b/java/org/apache/catalina/Container.java
@@ -27,48 +27,38 @@ import org.apache.juli.logging.Log;
/**
- * A <b>Container</b> is an object that can execute requests received from
- * a client, and return responses based on those requests. A Container may
- * optionally support a pipeline of Valves that process the request in an
- * order configured at runtime, by implementing the <b>Pipeline</b> interface
- * as well.
+ * A <b>Container</b> is an object that can execute requests received from a client, and return responses based on those
+ * requests. A Container may optionally support a pipeline of Valves that process the request in an order configured at
+ * runtime, by implementing the <b>Pipeline</b> interface as well.
* <p>
- * Containers will exist at several conceptual levels within Catalina. The
- * following examples represent common cases:
+ * Containers will exist at several conceptual levels within Catalina. The following examples represent common cases:
* <ul>
- * <li><b>Engine</b> - Representation of the entire Catalina servlet engine,
- * most likely containing one or more subcontainers that are either Host
- * or Context implementations, or other custom groups.
- * <li><b>Host</b> - Representation of a virtual host containing a number
- * of Contexts.
- * <li><b>Context</b> - Representation of a single ServletContext, which will
- * typically contain one or more Wrappers for the supported servlets.
+ * <li><b>Engine</b> - Representation of the entire Catalina servlet engine, most likely containing one or more
+ * subcontainers that are either Host or Context implementations, or other custom groups.
+ * <li><b>Host</b> - Representation of a virtual host containing a number of Contexts.
+ * <li><b>Context</b> - Representation of a single ServletContext, which will typically contain one or more Wrappers for
+ * the supported servlets.
* <li><b>Wrapper</b> - Representation of an individual servlet definition.
* </ul>
- * A given deployment of Catalina need not include Containers at all of the
- * levels described above. For example, an administration application
- * embedded within a network device (such as a router) might only contain
- * a single Context and a few Wrappers, or even a single Wrapper if the
- * application is relatively small. Therefore, Container implementations
- * need to be designed so that they will operate correctly in the absence
- * of parent Containers in a given deployment.
+ * A given deployment of Catalina need not include Containers at all of the levels described above. For example, an
+ * administration application embedded within a network device (such as a router) might only contain a single Context
+ * and a few Wrappers, or even a single Wrapper if the application is relatively small. Therefore, Container
+ * implementations need to be designed so that they will operate correctly in the absence of parent Containers in a
+ * given deployment.
* <p>
- * A Container may also be associated with a number of support components
- * that provide functionality which might be shared (by attaching it to a
- * parent Container) or individually customized. The following support
- * components are currently recognized:
+ * A Container may also be associated with a number of support components that provide functionality which might be
+ * shared (by attaching it to a parent Container) or individually customized. The following support components are
+ * currently recognized:
* <ul>
- * <li><b>Loader</b> - Class loader to use for integrating new Java classes
- * for this Container into the JVM in which Catalina is running.
- * <li><b>Logger</b> - Implementation of the <code>log()</code> method
- * signatures of the <code>ServletContext</code> interface.
- * <li><b>Manager</b> - Manager for the pool of Sessions associated with
- * this Container.
- * <li><b>Realm</b> - Read-only interface to a security domain, for
- * authenticating user identities and their corresponding roles.
- * <li><b>Resources</b> - JNDI directory context enabling access to static
- * resources, enabling custom linkages to existing server components when
- * Catalina is embedded in a larger server.
+ * <li><b>Loader</b> - Class loader to use for integrating new Java classes for this Container into the JVM in which
+ * Catalina is running.
+ * <li><b>Logger</b> - Implementation of the <code>log()</code> method signatures of the <code>ServletContext</code>
+ * interface.
+ * <li><b>Manager</b> - Manager for the pool of Sessions associated with this Container.
+ * <li><b>Realm</b> - Read-only interface to a security domain, for authenticating user identities and their
+ * corresponding roles.
+ * <li><b>Resources</b> - JNDI directory context enabling access to static resources, enabling custom linkages to
+ * existing server components when Catalina is embedded in a larger server.
* </ul>
*
* @author Craig R. McClanahan
@@ -81,29 +71,27 @@ public interface Container extends Lifecycle {
/**
- * The ContainerEvent event type sent when a child container is added
- * by <code>addChild()</code>.
+ * The ContainerEvent event type sent when a child container is added by <code>addChild()</code>.
*/
String ADD_CHILD_EVENT = "addChild";
/**
- * The ContainerEvent event type sent when a valve is added
- * by <code>addValve()</code>, if this Container supports pipelines.
+ * The ContainerEvent event type sent when a valve is added by <code>addValve()</code>, if this Container supports
+ * pipelines.
*/
String ADD_VALVE_EVENT = "addValve";
/**
- * The ContainerEvent event type sent when a child container is removed
- * by <code>removeChild()</code>.
+ * The ContainerEvent event type sent when a child container is removed by <code>removeChild()</code>.
*/
String REMOVE_CHILD_EVENT = "removeChild";
/**
- * The ContainerEvent event type sent when a valve is removed
- * by <code>removeValve()</code>, if this Container supports pipelines.
+ * The ContainerEvent event type sent when a valve is removed by <code>removeValve()</code>, if this Container
+ * supports pipelines.
*/
String REMOVE_VALVE_EVENT = "removeValve";
@@ -113,15 +101,15 @@ public interface Container extends Lifecycle {
/**
* Obtain the log to which events for this container should be logged.
*
- * @return The Logger with which this Container is associated. If there is
- * no associated Logger, return the Logger associated with the
- * parent Container (if any); otherwise return <code>null</code>.
+ * @return The Logger with which this Container is associated. If there is no associated Logger, return the Logger
+ * associated with the parent Container (if any); otherwise return <code>null</code>.
*/
Log getLogger();
/**
* Return the logger name that the container will use.
+ *
* @return the abbreviated name of this container for logging messages
*/
String getLogName();
@@ -136,8 +124,7 @@ public interface Container extends Lifecycle {
/**
- * Obtain the JMX domain under which this container will be / has been
- * registered.
+ * Obtain the JMX domain under which this container will be / has been registered.
*
* @return The JMX domain name
*/
@@ -145,18 +132,16 @@ public interface Container extends Lifecycle {
/**
- * Calculate the key properties string to be added to an object's
- * {@link ObjectName} to indicate that it is associated with this container.
- *
- * @return A string suitable for appending to the ObjectName
+ * Calculate the key properties string to be added to an object's {@link ObjectName} to indicate that it is
+ * associated with this container.
*
+ * @return A string suitable for appending to the ObjectName
*/
String getMBeanKeyProperties();
/**
- * Return the Pipeline object that manages the Valves associated with
- * this Container.
+ * Return the Pipeline object that manages the Valves associated with this Container.
*
* @return The Pipeline
*/
@@ -166,9 +151,8 @@ public interface Container extends Lifecycle {
/**
* Get the Cluster for this container.
*
- * @return The Cluster with which this Container is associated. If there is
- * no associated Cluster, return the Cluster associated with our
- * parent Container (if any); otherwise return <code>null</code>.
+ * @return The Cluster with which this Container is associated. If there is no associated Cluster, return the
+ * Cluster associated with our parent Container (if any); otherwise return <code>null</code>.
*/
Cluster getCluster();
@@ -182,36 +166,29 @@ public interface Container extends Lifecycle {
/**
- * Get the delay between the invocation of the backgroundProcess method on
- * this container and its children. Child containers will not be invoked if
- * their delay value is positive (which would mean they are using their own
- * thread). Setting this to a positive value will cause a thread to be
- * spawned. After waiting the specified amount of time, the thread will
- * invoke the {@link #backgroundProcess()} method on this container and all
- * children with non-positive delay values.
+ * Get the delay between the invocation of the backgroundProcess method on this container and its children. Child
+ * containers will not be invoked if their delay value is positive (which would mean they are using their own
+ * thread). Setting this to a positive value will cause a thread to be spawned. After waiting the specified amount
+ * of time, the thread will invoke the {@link #backgroundProcess()} method on this container and all children with
+ * non-positive delay values.
*
- * @return The delay between the invocation of the backgroundProcess method
- * on this container and its children. A non-positive value
- * indicates that background processing will be managed by the
- * parent.
+ * @return The delay between the invocation of the backgroundProcess method on this container and its children. A
+ * non-positive value indicates that background processing will be managed by the parent.
*/
int getBackgroundProcessorDelay();
/**
- * Set the delay between the invocation of the execute method on this
- * container and its children.
+ * Set the delay between the invocation of the execute method on this container and its children.
*
- * @param delay The delay in seconds between the invocation of
- * backgroundProcess methods
+ * @param delay The delay in seconds between the invocation of backgroundProcess methods
*/
void setBackgroundProcessorDelay(int delay);
/**
- * Return a name string (suitable for use by humans) that describes this
- * Container. Within the set of child containers belonging to a particular
- * parent, Container names must be unique.
+ * Return a name string (suitable for use by humans) that describes this Container. Within the set of child
+ * containers belonging to a particular parent, Container names must be unique.
*
* @return The human readable name of this container.
*/
@@ -219,15 +196,13 @@ public interface Container extends Lifecycle {
/**
- * Set a name string (suitable for use by humans) that describes this
- * Container. Within the set of child containers belonging to a particular
- * parent, Container names must be unique.
+ * Set a name string (suitable for use by humans) that describes this Container. Within the set of child containers
+ * belonging to a particular parent, Container names must be unique.
*
* @param name New name of this container
*
- * @exception IllegalStateException if this Container has already been
- * added to the children of a parent Container (after which the name
- * may not be changed)
+ * @exception IllegalStateException if this Container has already been added to the children of a parent Container
+ * (after which the name may not be changed)
*/
void setName(String name);
@@ -235,23 +210,19 @@ public interface Container extends Lifecycle {
/**
* Get the parent container.
*
- * @return Return the Container for which this Container is a child, if
- * there is one. If there is no defined parent, return
- * <code>null</code>.
+ * @return Return the Container for which this Container is a child, if there is one. If there is no defined parent,
+ * return <code>null</code>.
*/
Container getParent();
/**
- * Set the parent Container to which this Container is being added as a
- * child. This Container may refuse to become attached to the specified
- * Container by throwing an exception.
+ * Set the parent Container to which this Container is being added as a child. This Container may refuse to become
+ * attached to the specified Container by throwing an exception.
*
- * @param container Container to which this Container is being added
- * as a child
+ * @param container Container to which this Container is being added as a child
*
- * @exception IllegalArgumentException if this Container refuses to become
- * attached to the specified Container
+ * @exception IllegalArgumentException if this Container refuses to become attached to the specified Container
*/
void setParent(Container container);
@@ -260,17 +231,16 @@ public interface Container extends Lifecycle {
* Get the parent class loader.
*
* @return the parent class loader for this component. If not set, return
- * {@link #getParent()}.{@link #getParentClassLoader()}. If no
- * parent has been set, return the system class loader.
+ * {@link #getParent()}.{@link #getParentClassLoader()}. If no parent has been set, return the system
+ * class loader.
*/
ClassLoader getParentClassLoader();
/**
- * Set the parent class loader for this component. For {@link Context}s
- * this call is meaningful only <strong>before</strong> a Loader has
- * been configured, and the specified value (if non-null) should be
- * passed as an argument to the class loader constructor.
+ * Set the parent class loader for this component. For {@link Context}s this call is meaningful only
+ * <strong>before</strong> a Loader has been configured, and the specified value (if non-null) should be passed as
+ * an argument to the class loader constructor.
*
* @param parent The new parent class loader
*/
@@ -280,9 +250,8 @@ public interface Container extends Lifecycle {
/**
* Obtain the Realm with which this Container is associated.
*
- * @return The associated Realm; if there is no associated Realm, the
- * Realm associated with the parent Container (if any); otherwise
- * return <code>null</code>.
+ * @return The associated Realm; if there is no associated Realm, the Realm associated with the parent Container (if
+ * any); otherwise return <code>null</code>.
*/
Realm getRealm();
@@ -296,10 +265,11 @@ public interface Container extends Lifecycle {
/**
- * Find the configuration path where a configuration resource
- * is located.
- * @param container The container
+ * Find the configuration path where a configuration resource is located.
+ *
+ * @param container The container
* @param resourceName The resource file name
+ *
* @return the configuration path
*/
static String getConfigPath(Container container, String resourceName) {
@@ -332,7 +302,9 @@ public interface Container extends Lifecycle {
/**
* Return the Service to which this container belongs.
+ *
* @param container The container to start from
+ *
* @return the Service, or null if not found
*/
static Service getService(Container container) {
@@ -350,29 +322,25 @@ public interface Container extends Lifecycle {
/**
- * Execute a periodic task, such as reloading, etc. This method will be
- * invoked inside the classloading context of this container. Unexpected
- * throwables will be caught and logged.
+ * Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of
+ * this container. Unexpected throwables will be caught and logged.
*/
void backgroundProcess();
/**
- * Add a new child Container to those associated with this Container,
- * if supported. Prior to adding this Container to the set of children,
- * the child's <code>setParent()</code> method must be called, with this
- * Container as an argument. This method may thrown an
- * <code>IllegalArgumentException</code> if this Container chooses not
- * to be attached to the specified Container, in which case it is not added
+ * Add a new child Container to those associated with this Container, if supported. Prior to adding this Container
+ * to the set of children, the child's <code>setParent()</code> method must be called, with this Container as an
+ * argument. This method may thrown an <code>IllegalArgumentException</code> if this Container chooses not to be
+ * attached to the specified Container, in which case it is not added
*
* @param child New child Container to be added
*
- * @exception IllegalArgumentException if this exception is thrown by
- * the <code>setParent()</code> method of the child Container
- * @exception IllegalArgumentException if the new child does not have
- * a name unique from that of existing children of this Container
- * @exception IllegalStateException if this Container does not support
- * child Containers
+ * @exception IllegalArgumentException if this exception is thrown by the <code>setParent()</code> method of the
+ * child Container
+ * @exception IllegalArgumentException if the new child does not have a name unique from that of existing children
+ * of this Container
+ * @exception IllegalStateException if this Container does not support child Containers
*/
void addChild(Container child);
@@ -398,8 +366,7 @@ public interface Container extends Lifecycle {
*
* @param name Name of the child Container to be retrieved
*
- * @return The child Container with the given name or <code>null</code> if
- * no such child exists.
+ * @return The child Container with the given name or <code>null</code> if no such child exists.
*/
Container findChild(String name);
@@ -407,8 +374,8 @@ public interface Container extends Lifecycle {
/**
* Obtain the child Containers associated with this Container.
*
- * @return An array containing all children of this container. If this
- * Container has no children, a zero-length array is returned.
+ * @return An array containing all children of this container. If this Container has no children, a zero-length
+ * array is returned.
*/
Container[] findChildren();
@@ -416,16 +383,14 @@ public interface Container extends Lifecycle {
/**
* Obtain the container listeners associated with this Container.
*
- * @return An array containing the container listeners associated with this
- * Container. If this Container has no registered container
- * listeners, a zero-length array is returned.
+ * @return An array containing the container listeners associated with this Container. If this Container has no
+ * registered container listeners, a zero-length array is returned.
*/
ContainerListener[] findContainerListeners();
/**
- * Remove an existing child Container from association with this parent
- * Container.
+ * Remove an existing child Container from association with this parent Container.
*
* @param child Existing child Container to be removed
*/
@@ -449,9 +414,8 @@ public interface Container extends Lifecycle {
/**
- * Notify all container event listeners that a particular event has
- * occurred for this Container. The default implementation performs
- * this notification synchronously using the calling thread.
+ * Notify all container event listeners that a particular event has occurred for this Container. The default
+ * implementation performs this notification synchronously using the calling thread.
*
* @param type Event type
* @param data Event data
@@ -460,48 +424,42 @@ public interface Container extends Lifecycle {
/**
- * Log a request/response that was destined for this container but has been
- * handled earlier in the processing chain so that the request/response
- * still appears in the correct access logs.
- * @param request Request (associated with the response) to log
- * @param response Response (associated with the request) to log
- * @param time Time taken to process the request/response in
- * milliseconds (use 0 if not known)
- * @param useDefault Flag that indicates that the request/response should
- * be logged in the engine's default access log
+ * Log a request/response that was destined for this container but has been handled earlier in the processing chain
+ * so that the request/response still appears in the correct access logs.
+ *
+ * @param request Request (associated with the response) to log
+ * @param response Response (associated with the request) to log
+ * @param time Time taken to process the request/response in milliseconds (use 0 if not known)
+ * @param useDefault Flag that indicates that the request/response should be logged in the engine's default access
+ * log
*/
- void logAccess(Request request, Response response, long time,
- boolean useDefault);
+ void logAccess(Request request, Response response, long time, boolean useDefault);
/**
- * Obtain the AccessLog to use to log a request/response that is destined
- * for this container. This is typically used when the request/response was
- * handled (and rejected) earlier in the processing chain so that the
- * request/response still appears in the correct access logs.
+ * Obtain the AccessLog to use to log a request/response that is destined for this container. This is typically used
+ * when the request/response was handled (and rejected) earlier in the processing chain so that the request/response
+ * still appears in the correct access logs.
*
- * @return The AccessLog to use for a request/response destined for this
- * container
+ * @return The AccessLog to use for a request/response destined for this container
*/
AccessLog getAccessLog();
/**
- * Obtain the number of threads available for starting and stopping any
- * children associated with this container. This allows start/stop calls to
- * children to be processed in parallel.
+ * Obtain the number of threads available for starting and stopping any children associated with this container.
+ * This allows start/stop calls to children to be processed in parallel.
*
- * @return The currently configured number of threads used to start/stop
- * children associated with this container
+ * @return The currently configured number of threads used to start/stop children associated with this container
*/
int getStartStopThreads();
/**
- * Sets the number of threads available for starting and stopping any
- * children associated with this container. This allows start/stop calls to
- * children to be processed in parallel.
- * @param startStopThreads The new number of threads to be used
+ * Sets the number of threads available for starting and stopping any children associated with this container. This
+ * allows start/stop calls to children to be processed in parallel.
+ *
+ * @param startStopThreads The new number of threads to be used
*/
void setStartStopThreads(int startStopThreads);
@@ -509,7 +467,7 @@ public interface Container extends Lifecycle {
/**
* Obtain the location of CATALINA_BASE.
*
- * @return The location of CATALINA_BASE.
+ * @return The location of CATALINA_BASE.
*/
File getCatalinaBase();
diff --git a/java/org/apache/catalina/ContainerEvent.java b/java/org/apache/catalina/ContainerEvent.java
index b651356cc1..fb9ed80680 100644
--- a/java/org/apache/catalina/ContainerEvent.java
+++ b/java/org/apache/catalina/ContainerEvent.java
@@ -43,8 +43,8 @@ public final class ContainerEvent extends EventObject {
* Construct a new ContainerEvent with the specified parameters.
*
* @param container Container on which this event occurred
- * @param type Event type
- * @param data Event data
+ * @param type Event type
+ * @param data Event data
*/
public ContainerEvent(Container container, String type, Object data) {
super(container);
@@ -76,9 +76,8 @@ public final class ContainerEvent extends EventObject {
/**
* Return the event type of this event.
*
- * @return The event type of this event. Although this is a String, it is
- * safe to rely on the value returned by this method remaining
- * consistent between point releases.
+ * @return The event type of this event. Although this is a String, it is safe to rely on the value returned by this
+ * method remaining consistent between point releases.
*/
public String getType() {
return this.type;
@@ -90,7 +89,6 @@ public final class ContainerEvent extends EventObject {
*/
@Override
public String toString() {
- return "ContainerEvent['" + getContainer() + "','" +
- getType() + "','" + getData() + "']";
+ return "ContainerEvent['" + getContainer() + "','" + getType() + "','" + getData() + "']";
}
}
diff --git a/java/org/apache/catalina/ContainerListener.java b/java/org/apache/catalina/ContainerListener.java
index ae7275836c..81c063f9b0 100644
--- a/java/org/apache/catalina/ContainerListener.java
+++ b/java/org/apache/catalina/ContainerListener.java
@@ -18,9 +18,8 @@ package org.apache.catalina;
/**
- * Interface defining a listener for significant Container generated events.
- * Note that "container start" and "container stop" events are normally
- * LifecycleEvents, not ContainerEvents.
+ * Interface defining a listener for significant Container generated events. Note that "container start" and "container
+ * stop" events are normally LifecycleEvents, not ContainerEvents.
*
* @author Craig R. McClanahan
*/
diff --git a/java/org/apache/catalina/ContainerServlet.java b/java/org/apache/catalina/ContainerServlet.java
index 3db927d25f..c69bc5ea83 100644
--- a/java/org/apache/catalina/ContainerServlet.java
+++ b/java/org/apache/catalina/ContainerServlet.java
@@ -17,11 +17,9 @@
package org.apache.catalina;
/**
- * A <b>ContainerServlet</b> is a servlet that has access to Catalina
- * internal functionality, and is loaded from the Catalina class loader
- * instead of the web application class loader. The property setter
- * methods must be called by the container whenever a new instance of
- * this servlet is put into service.
+ * A <b>ContainerServlet</b> is a servlet that has access to Catalina internal functionality, and is loaded from the
+ * Catalina class loader instead of the web application class loader. The property setter methods must be called by the
+ * container whenever a new instance of this servlet is put into service.
*
* @author Craig R. McClanahan
*/
diff --git a/java/org/apache/catalina/Context.java b/java/org/apache/catalina/Context.java
index d91556cb25..1e142c3bcb 100644
--- a/java/org/apache/catalina/Context.java
+++ b/java/org/apache/catalina/Context.java
@@ -47,19 +47,17 @@ import org.apache.tomcat.util.file.ConfigurationSource.Resource;
import org.apache.tomcat.util.http.CookieProcessor;
/**
- * A <b>Context</b> is a Container that represents a servlet context, and
- * therefore an individual web application, in the Catalina servlet engine.
- * It is therefore useful in almost every deployment of Catalina (even if a
- * Connector attached to a web server (such as Apache) uses the web server's
- * facilities to identify the appropriate Wrapper to handle this request.
- * It also provides a convenient mechanism to use Interceptors that see
- * every request processed by this particular web application.
+ * A <b>Context</b> is a Container that represents a servlet context, and therefore an individual web application, in
+ * the Catalina servlet engine. It is therefore useful in almost every deployment of Catalina (even if a Connector
+ * attached to a web server (such as Apache) uses the web server's facilities to identify the appropriate Wrapper to
+ * handle this request. It also provides a convenient mechanism to use Interceptors that see every request processed by
+ * this particular web application.
* <p>
- * The parent Container attached to a Context is generally a Host, but may
- * be some other implementation, or may be omitted if it is not necessary.
+ * The parent Container attached to a Context is generally a Host, but may be some other implementation, or may be
+ * omitted if it is not necessary.
* <p>
- * The child containers attached to a Context are generally implementations
- * of Wrapper (representing individual servlet definitions).
+ * The child containers attached to a Context are generally implementations of Wrapper (representing individual servlet
+ * definitions).
* <p>
*
* @author Craig R. McClanahan
@@ -82,7 +80,7 @@ public interface Context extends Container, ContextBind {
/**
* Container event for clearing welcome files.
*/
- String CLEAR_WELCOME_FILES_EVENT = "clearWelcomeFiles";
+ String CLEAR_WELCOME_FILES_EVENT = "clearWelcomeFiles";
/**
* Container event for changing the ID of a session.
@@ -99,24 +97,20 @@ public interface Context extends Container, ContextBind {
// ------------------------------------------------------------- Properties
/**
- * Returns <code>true</code> if requests mapped to servlets without
- * "multipart config" to parse multipart/form-data requests anyway.
+ * Returns <code>true</code> if requests mapped to servlets without "multipart config" to parse multipart/form-data
+ * requests anyway.
*
- * @return <code>true</code> if requests mapped to servlets without
- * "multipart config" to parse multipart/form-data requests,
- * <code>false</code> otherwise.
+ * @return <code>true</code> if requests mapped to servlets without "multipart config" to parse multipart/form-data
+ * requests, <code>false</code> otherwise.
*/
boolean getAllowCasualMultipartParsing();
- /**
- * Set to <code>true</code> to allow requests mapped to servlets that
- * do not explicitly declare @MultipartConfig or have
- * <multipart-config> specified in web.xml to parse
- * multipart/form-data requests.
+ /**
+ * Set to <code>true</code> to allow requests mapped to servlets that do not explicitly declare @MultipartConfig or
+ * have <multipart-config> specified in web.xml to parse multipart/form-data requests.
*
- * @param allowCasualMultipartParsing <code>true</code> to allow such
- * casual parsing, <code>false</code> otherwise.
+ * @param allowCasualMultipartParsing <code>true</code> to allow such casual parsing, <code>false</code> otherwise.
*/
void setAllowCasualMultipartParsing(boolean allowCasualMultipartParsing);
@@ -124,17 +118,15 @@ public interface Context extends Container, ContextBind {
/**
* Obtain the registered application event listeners.
*
- * @return An array containing the application event listener instances for
- * this web application in the order they were specified in the web
- * application deployment descriptor
+ * @return An array containing the application event listener instances for this web application in the order they
+ * were specified in the web application deployment descriptor
*/
Object[] getApplicationEventListeners();
/**
- * Store the set of initialized application event listener objects,
- * in the order they were specified in the web application deployment
- * descriptor, for this application.
+ * Store the set of initialized application event listener objects, in the order they were specified in the web
+ * application deployment descriptor, for this application.
*
* @param listeners The set of instantiated listener objects.
*/
@@ -144,17 +136,15 @@ public interface Context extends Container, ContextBind {
/**
* Obtain the registered application lifecycle listeners.
*
- * @return An array containing the application lifecycle listener instances
- * for this web application in the order they were specified in the
- * web application deployment descriptor
+ * @return An array containing the application lifecycle listener instances for this web application in the order
+ * they were specified in the web application deployment descriptor
*/
Object[] getApplicationLifecycleListeners();
/**
- * Store the set of initialized application lifecycle listener objects,
- * in the order they were specified in the web application deployment
- * descriptor, for this application.
+ * Store the set of initialized application lifecycle listener objects, in the order they were specified in the web
+ * application deployment descriptor, for this application.
*
* @param listeners The set of instantiated listener objects.
*/
@@ -162,12 +152,10 @@ public interface Context extends Container, ContextBind {
/**
- * Obtain the character set name to use with the given Locale. Note that
- * different Contexts may have different mappings of Locale to character
- * set.
+ * Obtain the character set name to use with the given Locale. Note that different Contexts may have different
+ * mappings of Locale to character set.
*
- * @param locale The locale for which the mapped character set should be
- * returned
+ * @param locale The locale for which the mapped character set should be returned
*
* @return The name of the character set to use with the given Locale
*/
@@ -193,16 +181,14 @@ public interface Context extends Container, ContextBind {
/**
* Return the "correctly configured" flag for this Context.
*
- * @return <code>true</code> if the Context has been correctly configured,
- * otherwise <code>false</code>
+ * @return <code>true</code> if the Context has been correctly configured, otherwise <code>false</code>
*/
boolean getConfigured();
/**
- * Set the "correctly configured" flag for this Context. This can be
- * set to false by startup listeners that detect a fatal configuration
- * error to avoid the application from being made available.
+ * Set the "correctly configured" flag for this Context. This can be set to false by startup listeners that detect a
+ * fatal configuration error to avoid the application from being made available.
*
* @param configured The new correctly configured flag
*/
@@ -212,9 +198,8 @@ public interface Context extends Container, ContextBind {
/**
* Return the "use cookies for session ids" flag.
*
- * @return <code>true</code> if it is permitted to use cookies to track
- * session IDs for this web application, otherwise
- * <code>false</code>
+ * @return <code>true</code> if it is permitted to use cookies to track session IDs for this web application,
+ * otherwise <code>false</code>
*/
boolean getCookies();
@@ -228,20 +213,17 @@ public interface Context extends Container, ContextBind {
/**
- * Gets the name to use for session cookies. Overrides any setting that
- * may be specified by the application.
+ * Gets the name to use for session cookies. Overrides any setting that may be specified by the application.
*
- * @return The value of the default session cookie name or null if not
- * specified
+ * @return The value of the default session cookie name or null if not specified
*/
String getSessionCookieName();
/**
- * Sets the name to use for session cookies. Overrides any setting that
- * may be specified by the application.
+ * Sets the name to use for session cookies. Overrides any setting that may be specified by the application.
*
- * @param sessionCookieName The name to use
+ * @param sessionCookieName The name to use
*/
void setSessionCookieName(String sessionCookieName);
@@ -249,8 +231,7 @@ public interface Context extends Container, ContextBind {
/**
* Gets the value of the use HttpOnly cookies for session cookies flag.
*
- * @return <code>true</code> if the HttpOnly flag should be set on session
- * cookies
+ * @return <code>true</code> if the HttpOnly flag should be set on session cookies
*/
boolean getUseHttpOnly();
@@ -258,8 +239,7 @@ public interface Context extends Container, ContextBind {
/**
* Sets the use HttpOnly cookies for session cookies flag.
*
- * @param useHttpOnly Set to <code>true</code> to use HttpOnly cookies
- * for session cookies
+ * @param useHttpOnly Set to <code>true</code> to use HttpOnly cookies for session cookies
*/
void setUseHttpOnly(boolean useHttpOnly);
@@ -292,72 +272,61 @@ public interface Context extends Container, ContextBind {
/**
- * Gets the domain to use for session cookies. Overrides any setting that
- * may be specified by the application.
+ * Gets the domain to use for session cookies. Overrides any setting that may be specified by the application.
*
- * @return The value of the default session cookie domain or null if not
- * specified
+ * @return The value of the default session cookie domain or null if not specified
*/
String getSessionCookieDomain();
/**
- * Sets the domain to use for session cookies. Overrides any setting that
- * may be specified by the application.
+ * Sets the domain to use for session cookies. Overrides any setting that may be specified by the application.
*
- * @param sessionCookieDomain The domain to use
+ * @param sessionCookieDomain The domain to use
*/
void setSessionCookieDomain(String sessionCookieDomain);
/**
- * Gets the path to use for session cookies. Overrides any setting that
- * may be specified by the application.
+ * Gets the path to use for session cookies. Overrides any setting that may be specified by the application.
*
- * @return The value of the default session cookie path or null if not
- * specified
+ * @return The value of the default session cookie path or null if not specified
*/
String getSessionCookiePath();
/**
- * Sets the path to use for session cookies. Overrides any setting that
- * may be specified by the application.
+ * Sets the path to use for session cookies. Overrides any setting that may be specified by the application.
*
- * @param sessionCookiePath The path to use
+ * @param sessionCookiePath The path to use
*/
void setSessionCookiePath(String sessionCookiePath);
/**
- * Is a / added to the end of the session cookie path to ensure browsers,
- * particularly IE, don't send a session cookie for context /foo with
- * requests intended for context /foobar.
+ * Is a / added to the end of the session cookie path to ensure browsers, particularly IE, don't send a session
+ * cookie for context /foo with requests intended for context /foobar.
*
- * @return <code>true</code> if the slash is added, otherwise
- * <code>false</code>
+ * @return <code>true</code> if the slash is added, otherwise <code>false</code>
*/
boolean getSessionCookiePathUsesTrailingSlash();
/**
- * Configures if a / is added to the end of the session cookie path to
- * ensure browsers, particularly IE, don't send a session cookie for context
- * /foo with requests intended for context /foobar.
+ * Configures if a / is added to the end of the session cookie path to ensure browsers, particularly IE, don't send
+ * a session cookie for context /foo with requests intended for context /foobar.
*
- * @param sessionCookiePathUsesTrailingSlash <code>true</code> if the
- * slash is should be added,
- * otherwise <code>false</code>
+ * @param sessionCookiePathUsesTrailingSlash <code>true</code> if the slash is should be added, otherwise
+ * <code>false</code>
*/
- void setSessionCookiePathUsesTrailingSlash(
- boolean sessionCookiePathUsesTrailingSlash);
+ void setSessionCookiePathUsesTrailingSlash(boolean sessionCookiePathUsesTrailingSlash);
/**
* Return the "allow crossing servlet contexts" flag.
*
- * @return <code>true</code> if cross-contest requests are allowed from this
- * web applications, otherwise <code>false</code>
+ * @return <code>true</code> if cross-contest requests are allowed from this web applications, otherwise
+ * <code>false</code>
*/
boolean getCrossContext();
@@ -375,7 +344,7 @@ public interface Context extends Container, ContextBind {
*
* @param altDDName The new name
*/
- void setAltDDName(String altDDName) ;
+ void setAltDDName(String altDDName);
/**
@@ -437,16 +406,14 @@ public interface Context extends Container, ContextBind {
/**
* Obtain the document root for this Context.
*
- * @return An absolute pathname or a relative (to the Host's appBase)
- * pathname.
+ * @return An absolute pathname or a relative (to the Host's appBase) pathname.
*/
String getDocBase();
/**
- * Set the document root for this Context. This can be either an absolute
- * pathname or a relative pathname. Relative pathnames are relative to the
- * containing Host's appBase.
+ * Set the document root for this Context. This can be either an absolute pathname or a relative pathname. Relative
+ * pathnames are relative to the containing Host's appBase.
*
* @param docBase The new document root
*/
@@ -464,15 +431,13 @@ public interface Context extends Container, ContextBind {
/**
* Determine if annotations parsing is currently disabled
*
- * @return {@code true} if annotation parsing is disabled for this web
- * application
+ * @return {@code true} if annotation parsing is disabled for this web application
*/
boolean getIgnoreAnnotations();
/**
- * Set the boolean on the annotations parsing for this web
- * application.
+ * Set the boolean on the annotations parsing for this web application.
*
* @param ignoreAnnotations The boolean on the annotations parsing
*/
@@ -522,15 +487,13 @@ public interface Context extends Container, ContextBind {
/**
- * @return the public identifier of the deployment descriptor DTD that is
- * currently being parsed.
+ * @return the public identifier of the deployment descriptor DTD that is currently being parsed.
*/
String getPublicId();
/**
- * Set the public identifier of the deployment descriptor DTD that is
- * currently being parsed.
+ * Set the public identifier of the deployment descriptor DTD that is currently being parsed.
*
* @param publicId The public identifier
*/
@@ -586,15 +549,13 @@ public interface Context extends Container, ContextBind {
/**
- * @return the default session timeout (in minutes) for this
- * web application.
+ * @return the default session timeout (in minutes) for this web application.
*/
int getSessionTimeout();
/**
- * Set the default session timeout (in minutes) for this
- * web application.
+ * Set the default session timeout (in minutes) for this web application.
*
* @param timeout The new default session timeout
*/
@@ -602,21 +563,18 @@ public interface Context extends Container, ContextBind {
/**
- * Returns <code>true</code> if remaining request data will be read
- * (swallowed) even the request violates a data size constraint.
+ * Returns <code>true</code> if remaining request data will be read (swallowed) even the request violates a data
+ * size constraint.
*
- * @return <code>true</code> if data will be swallowed (default),
- * <code>false</code> otherwise.
+ * @return <code>true</code> if data will be swallowed (default), <code>false</code> otherwise.
*/
boolean getSwallowAbortedUploads();
/**
- * Set to <code>false</code> to disable request data swallowing
- * after an upload was aborted due to size constraints.
+ * Set to <code>false</code> to disable request data swallowing after an upload was aborted due to size constraints.
*
- * @param swallowAbortedUploads <code>false</code> to disable
- * swallowing, <code>true</code> otherwise (default).
+ * @param swallowAbortedUploads <code>false</code> to disable swallowing, <code>true</code> otherwise (default).
*/
void setSwallowAbortedUploads(boolean swallowAbortedUploads);
@@ -627,9 +585,8 @@ public interface Context extends Container, ContextBind {
/**
- * Set the value of the swallowOutput flag. If set to true, the system.out
- * and system.err will be redirected to the logger during a servlet
- * execution.
+ * Set the value of the swallowOutput flag. If set to true, the system.out and system.err will be redirected to the
+ * logger during a servlet execution.
*
* @param swallowOutput The new value
*/
@@ -637,15 +594,13 @@ public interface Context extends Container, ContextBind {
/**
- * @return the Java class name of the Wrapper implementation used
- * for servlets registered in this Context.
+ * @return the Java class name of the Wrapper implementation used for servlets registered in this Context.
*/
String getWrapperClass();
/**
- * Set the Java class name of the Wrapper implementation used
- * for servlets registered in this Context.
+ * Set the Java class name of the Wrapper implementation used for servlets registered in this Context.
*
* @param wrapperClass The new wrapper class
*/
@@ -653,8 +608,7 @@ public interface Context extends Container, ContextBind {
/**
- * Will the parsing of web.xml and web-fragment.xml files for this Context
- * be performed by a namespace aware parser?
+ * Will the parsing of web.xml and web-fragment.xml files for this Context be performed by a namespace aware parser?
*
* @return true if namespace awareness is enabled.
*/
@@ -662,8 +616,8 @@ public interface Context extends Container, ContextBind {
/**
- * Controls whether the parsing of web.xml and web-fragment.xml files for
- * this Context will be performed by a namespace aware parser.
+ * Controls whether the parsing of web.xml and web-fragment.xml files for this Context will be performed by a
+ * namespace aware parser.
*
* @param xmlNamespaceAware true to enable namespace awareness
*/
@@ -671,8 +625,7 @@ public interface Context extends Container, ContextBind {
/**
- * Will the parsing of web.xml and web-fragment.xml files for this Context
- * be performed by a validating parser?
+ * Will the parsing of web.xml and web-fragment.xml files for this Context be performed by a validating parser?
*
* @return true if validation is enabled.
*/
@@ -680,8 +633,8 @@ public interface Context extends Container, ContextBind {
/**
- * Controls whether the parsing of web.xml and web-fragment.xml files
- * for this Context will be performed by a validating parser.
+ * Controls whether the parsing of web.xml and web-fragment.xml files for this Context will be performed by a
+ * validating parser.
*
* @param xmlValidation true to enable xml validation
*/
@@ -689,8 +642,8 @@ public interface Context extends Container, ContextBind {
/**
- * Will the parsing of web.xml, web-fragment.xml, *.tld, *.jspx, *.tagx and
- * tagplugin.xml files for this Context block the use of external entities?
+ * Will the parsing of web.xml, web-fragment.xml, *.tld, *.jspx, *.tagx and tagplugin.xml files for this Context
+ * block the use of external entities?
*
* @return true if access to external entities is blocked
*/
@@ -698,9 +651,8 @@ public interface Context extends Container, ContextBind {
/**
- * Controls whether the parsing of web.xml, web-fragment.xml, *.tld, *.jspx,
- * *.tagx and tagplugin.xml files for this Context will block the use of
- * external entities.
+ * Controls whether the parsing of web.xml, web-fragment.xml, *.tld, *.jspx, *.tagx and tagplugin.xml files for this
+ * Context will block the use of external entities.
*
* @param xmlBlockExternal true to block external entities
*/
@@ -708,8 +660,7 @@ public interface Context extends Container, ContextBind {
/**
- * Will the parsing of *.tld files for this Context be performed by a
- * validating parser?
+ * Will the parsing of *.tld files for this Context be performed by a validating parser?
*
* @return true if validation is enabled.
*/
@@ -717,8 +668,7 @@ public interface Context extends Container, ContextBind {
/**
- * Controls whether the parsing of *.tld files for this Context will be
- * performed by a validating parser.
+ * Controls whether the parsing of *.tld files for this Context will be performed by a validating parser.
*
* @param tldValidation true to enable xml validation
*/
@@ -726,39 +676,36 @@ public interface Context extends Container, ContextBind {
/**
- * Get the Jar Scanner to be used to scan for JAR resources for this
- * context.
- * @return The Jar Scanner configured for this context.
+ * Get the Jar Scanner to be used to scan for JAR resources for this context.
+ *
+ * @return The Jar Scanner configured for this context.
*/
JarScanner getJarScanner();
/**
- * Set the Jar Scanner to be used to scan for JAR resources for this
- * context.
- * @param jarScanner The Jar Scanner to be used for this context.
+ * Set the Jar Scanner to be used to scan for JAR resources for this context.
+ *
+ * @param jarScanner The Jar Scanner to be used for this context.
*/
void setJarScanner(JarScanner jarScanner);
/**
- * @return the {@link Authenticator} that is used by this context. This is
- * always non-{@code null} for a started Context
+ * @return the {@link Authenticator} that is used by this context. This is always non-{@code null} for a started
+ * Context
*/
Authenticator getAuthenticator();
/**
- * Set whether or not the effective web.xml for this context should be
- * logged on context start.
+ * Set whether or not the effective web.xml for this context should be logged on context start.
*
- * @param logEffectiveWebXml set to <code>true</code> to log the complete
- * web.xml that will be used for the webapp
+ * @param logEffectiveWebXml set to <code>true</code> to log the complete web.xml that will be used for the webapp
*/
void setLogEffectiveWebXml(boolean logEffectiveWebXml);
/**
* Should the effective web.xml for this context be logged on context start?
*
- * @return true if the reconstructed web.xml that will be used for the
- * webapp should be logged
+ * @return true if the reconstructed web.xml that will be used for the webapp should be logged
*/
boolean getLogEffectiveWebXml();
@@ -775,34 +722,30 @@ public interface Context extends Container, ContextBind {
void setInstanceManager(InstanceManager instanceManager);
/**
- * Sets the regular expression that specifies which container provided SCIs
- * should be filtered out and not used for this context. Matching uses
- * {@link java.util.regex.Matcher#find()} so the regular expression only has
- * to match a sub-string of the fully qualified class name of the container
- * provided SCI for it to be filtered out.
+ * Sets the regular expression that specifies which container provided SCIs should be filtered out and not used for
+ * this context. Matching uses {@link java.util.regex.Matcher#find()} so the regular expression only has to match a
+ * sub-string of the fully qualified class name of the container provided SCI for it to be filtered out.
*
- * @param containerSciFilter The regular expression against which the fully
- * qualified class name of each container provided
- * SCI should be checked
+ * @param containerSciFilter The regular expression against which the fully qualified class name of each container
+ * provided SCI should be checked
*/
void setContainerSciFilter(String containerSciFilter);
/**
- * Obtains the regular expression that specifies which container provided
- * SCIs should be filtered out and not used for this context. Matching uses
- * {@link java.util.regex.Matcher#find()} so the regular expression only has
- * to match a sub-string of the fully qualified class name of the container
- * provided SCI for it to be filtered out.
+ * Obtains the regular expression that specifies which container provided SCIs should be filtered out and not used
+ * for this context. Matching uses {@link java.util.regex.Matcher#find()} so the regular expression only has to
+ * match a sub-string of the fully qualified class name of the container provided SCI for it to be filtered out.
*
- * @return The regular expression against which the fully qualified class
- * name of each container provided SCI will be checked
+ * @return The regular expression against which the fully qualified class name of each container provided SCI will
+ * be checked
*/
String getContainerSciFilter();
/**
- * @return the value of the parallel annotation scanning flag. If true,
- * it will dispatch scanning to the utility executor.
+ * @return the value of the parallel annotation scanning flag. If true, it will dispatch scanning to the utility
+ * executor.
+ *
* @deprecated This method will be removed in Tomcat 11 onwards
*/
@Deprecated
@@ -811,8 +754,8 @@ public interface Context extends Container, ContextBind {
}
/**
- * @return the value of the parallel annotation scanning flag. If true,
- * it will dispatch scanning to the utility executor.
+ * @return the value of the parallel annotation scanning flag. If true, it will dispatch scanning to the utility
+ * executor.
*/
boolean getParallelAnnotationScanning();
@@ -827,8 +770,7 @@ public interface Context extends Container, ContextBind {
// --------------------------------------------------------- Public Methods
/**
- * Add a new Listener class name to the set of Listeners
- * configured for this application.
+ * Add a new Listener class name to the set of Listeners configured for this application.
*
* @param listener Java class name of a listener class
*/
@@ -875,14 +817,13 @@ public interface Context extends Container, ContextBind {
void addFilterMap(FilterMap filterMap);
/**
- * Add a filter mapping to this Context before the mappings defined in the
- * deployment descriptor but after any other mappings added via this method.
+ * Add a filter mapping to this Context before the mappings defined in the deployment descriptor but after any other
+ * mappings added via this method.
*
* @param filterMap The filter mapping to be added
*
- * @exception IllegalArgumentException if the specified filter name
- * does not match an existing filter definition, or the filter mapping
- * is malformed
+ * @exception IllegalArgumentException if the specified filter name does not match an existing filter definition, or
+ * the filter mapping is malformed
*/
void addFilterMapBefore(FilterMap filterMap);
@@ -890,28 +831,26 @@ public interface Context extends Container, ContextBind {
/**
* Add a Locale Encoding Mapping (see Sec 5.4 of Servlet spec 2.4)
*
- * @param locale locale to map an encoding for
+ * @param locale locale to map an encoding for
* @param encoding encoding to be used for a give locale
*/
void addLocaleEncodingMappingParameter(String locale, String encoding);
/**
- * Add a new MIME mapping, replacing any existing mapping for
- * the specified extension.
+ * Add a new MIME mapping, replacing any existing mapping for the specified extension.
*
* @param extension Filename extension being mapped
- * @param mimeType Corresponding MIME type
+ * @param mimeType Corresponding MIME type
*/
void addMimeMapping(String extension, String mimeType);
/**
- * Add a new context initialization parameter, replacing any existing
- * value for the specified name.
+ * Add a new context initialization parameter, replacing any existing value for the specified name.
*
- * @param name Name of the new parameter
- * @param value Value of the new parameter
+ * @param name Name of the new parameter
+ * @param value Value of the new parameter
*/
void addParameter(String name, String value);
@@ -934,11 +873,10 @@ public interface Context extends Container, ContextBind {
/**
- * Add a new servlet mapping, replacing any existing mapping for
- * the specified pattern.
+ * Add a new servlet mapping, replacing any existing mapping for the specified pattern.
*
* @param pattern URL pattern to be mapped
- * @param name Name of the corresponding servlet to execute
+ * @param name Name of the corresponding servlet to execute
*/
default void addServletMappingDecoded(String pattern, String name) {
addServletMappingDecoded(pattern, name, false);
@@ -946,21 +884,18 @@ public interface Context extends Container, ContextBind {
/**
- * Add a new servlet mapping, replacing any existing mapping for
- * the specified pattern.
+ * Add a new servlet mapping, replacing any existing mapping for the specified pattern.
*
- * @param pattern URL pattern to be mapped
- * @param name Name of the corresponding servlet to execute
- * @param jspWildcard true if name identifies the JspServlet
- * and pattern contains a wildcard; false otherwise
+ * @param pattern URL pattern to be mapped
+ * @param name Name of the corresponding servlet to execute
+ * @param jspWildcard true if name identifies the JspServlet and pattern contains a wildcard; false otherwise
*/
- void addServletMappingDecoded(String pattern, String name,
- boolean jspWildcard);
+ void addServletMappingDecoded(String pattern, String name, boolean jspWildcard);
/**
- * Add a resource which will be watched for reloading by the host auto
- * deployer. Note: this will not be used in embedded mode.
+ * Add a resource which will be watched for reloading by the host auto deployer. Note: this will not be used in
+ * embedded mode.
*
* @param name Path to the resource, relative to docBase
*/
@@ -976,8 +911,7 @@ public interface Context extends Container, ContextBind {
/**
- * Add the classname of a LifecycleListener to be added to each
- * Wrapper appended to this Context.
+ * Add the classname of a LifecycleListener to be added to each Wrapper appended to this Context.
*
* @param listener Java class name of a LifecycleListener class
*/
@@ -985,8 +919,7 @@ public interface Context extends Container, ContextBind {
/**
- * Add the classname of a ContainerListener to be added to each
- * Wrapper appended to this Context.
+ * Add the classname of a ContainerListener to be added to each Wrapper appended to this Context.
*
* @param listener Java class name of a ContainerListener class
*/
@@ -994,18 +927,17 @@ public interface Context extends Container, ContextBind {
/**
- * Factory method to create and return a new InstanceManager
- * instance. This can be used for framework integration or easier
- * configuration with custom Context implementations.
+ * Factory method to create and return a new InstanceManager instance. This can be used for framework integration or
+ * easier configuration with custom Context implementations.
+ *
* @return the instance manager
*/
InstanceManager createInstanceManager();
/**
- * Factory method to create and return a new Wrapper instance, of
- * the Java implementation class appropriate for this Context
- * implementation. The constructor of the instantiated Wrapper
- * will have been called, but no properties will have been set.
+ * Factory method to create and return a new Wrapper instance, of the Java implementation class appropriate for this
+ * Context implementation. The constructor of the instantiated Wrapper will have been called, but no properties will
+ * have been set.
*
* @return a newly created wrapper instance that is used to wrap a Servlet
*/
@@ -1013,8 +945,7 @@ public interface Context extends Container, ContextBind {
/**
- * @return the set of application listener class names configured
- * for this application.
+ * @return the set of application listener class names configured for this application.
*/
String[] findApplicationListeners();
@@ -1026,15 +957,14 @@ public interface Context extends Container, ContextBind {
/**
- * @return the set of security constraints for this web application.
- * If there are none, a zero-length array is returned.
+ * @return the set of security constraints for this web application. If there are none, a zero-length array is
+ * returned.
*/
SecurityConstraint[] findConstraints();
/**
- * @return the error page entry for the specified HTTP error code,
- * if any; otherwise return <code>null</code>.
+ * @return the error page entry for the specified HTTP error code, if any; otherwise return <code>null</code>.
*
* @param errorCode Error code to look up
*/
@@ -1042,29 +972,25 @@ public interface Context extends Container, ContextBind {
/**
- * Find and return the ErrorPage instance for the specified exception's
- * class, or an ErrorPage instance for the closest superclass for which
- * there is such a definition. If no associated ErrorPage instance is
- * found, return <code>null</code>.
+ * Find and return the ErrorPage instance for the specified exception's class, or an ErrorPage instance for the
+ * closest superclass for which there is such a definition. If no associated ErrorPage instance is found, return
+ * <code>null</code>.
*
* @param throwable The exception type for which to find an ErrorPage
*
- * @return the error page entry for the specified Java exception type,
- * if any; otherwise return {@code null}.
+ * @return the error page entry for the specified Java exception type, if any; otherwise return {@code null}.
*/
ErrorPage findErrorPage(Throwable throwable);
/**
- * @return the set of defined error pages for all specified error codes
- * and exception types.
+ * @return the set of defined error pages for all specified error codes and exception types.
*/
ErrorPage[] findErrorPages();
/**
- * @return the filter definition for the specified filter name, if any;
- * otherwise return <code>null</code>.
+ * @return the filter definition for the specified filter name, if any; otherwise return <code>null</code>.
*
* @param filterName Filter name to look up
*/
@@ -1084,8 +1010,7 @@ public interface Context extends Container, ContextBind {
/**
- * @return the MIME type to which the specified extension is mapped,
- * if any; otherwise return <code>null</code>.
+ * @return the MIME type to which the specified extension is mapped, if any; otherwise return <code>null</code>.
*
* @param extension Extension to map to a MIME type
*/
@@ -1093,15 +1018,14 @@ public interface Context extends Container, ContextBind {
/**
- * @return the extensions for which MIME mappings are defined. If there
- * are none, a zero-length array is returned.
+ * @return the extensions for which MIME mappings are defined. If there are none, a zero-length array is returned.
*/
String[] findMimeMappings();
/**
- * @return the value for the specified context initialization
- * parameter name, if any; otherwise return <code>null</code>.
+ * @return the value for the specified context initialization parameter name, if any; otherwise return
+ * <code>null</code>.
*
* @param name Name of the parameter to return
*/
@@ -1109,27 +1033,26 @@ public interface Context extends Container, ContextBind {
/**
- * @return the names of all defined context initialization parameters
- * for this Context. If no parameters are defined, a zero-length
- * array is returned.
+ * @return the names of all defined context initialization parameters for this Context. If no parameters are
+ * defined, a zero-length array is returned.
*/
String[] findParameters();
/**
- * For the given security role (as used by an application), return the
- * corresponding role name (as defined by the underlying Realm) if there
- * is one. Otherwise, return the specified role unchanged.
+ * For the given security role (as used by an application), return the corresponding role name (as defined by the
+ * underlying Realm) if there is one. Otherwise, return the specified role unchanged.
*
* @param role Security role to map
+ *
* @return The role name that was mapped to the specified role
*/
String findRoleMapping(String role);
/**
- * @return <code>true</code> if the specified security role is defined
- * for this application; otherwise return <code>false</code>.
+ * @return <code>true</code> if the specified security role is defined for this application; otherwise return
+ * <code>false</code>.
*
* @param role Security role to verify
*/
@@ -1137,15 +1060,14 @@ public interface Context extends Container, ContextBind {
/**
- * @return the security roles defined for this application. If none
- * have been defined, a zero-length array is returned.
+ * @return the security roles defined for this application. If none have been defined, a zero-length array is
+ * returned.
*/
String[] findSecurityRoles();
/**
- * @return the servlet name mapped by the specified pattern (if any);
- * otherwise return <code>null</code>.
+ * @return the servlet name mapped by the specified pattern (if any); otherwise return <code>null</code>.
*
* @param pattern Pattern for which a mapping is requested
*/
@@ -1153,8 +1075,8 @@ public interface Context extends Container, ContextBind {
/**
- * @return the patterns of all defined servlet mappings for this
- * Context. If no mappings are defined, a zero-length array is returned.
+ * @return the patterns of all defined servlet mappings for this Context. If no mappings are defined, a zero-length
+ * array is returned.
*/
String[] findServletMappings();
@@ -1168,22 +1090,21 @@ public interface Context extends Container, ContextBind {
/**
* Get the associated ThreadBindingListener.
*
- * @param threadBindingListener Set the listener that will receive
- * notifications when entering and exiting the application scope
+ * @param threadBindingListener Set the listener that will receive notifications when entering and exiting the
+ * application scope
*/
void setThreadBindingListener(ThreadBindingListener threadBindingListener);
/**
- * @return the set of watched resources for this Context. If none are
- * defined, a zero length array will be returned.
+ * @return the set of watched resources for this Context. If none are defined, a zero length array will be returned.
*/
String[] findWatchedResources();
/**
- * @return <code>true</code> if the specified welcome file is defined
- * for this Context; otherwise return <code>false</code>.
+ * @return <code>true</code> if the specified welcome file is defined for this Context; otherwise return
+ * <code>false</code>.
*
* @param name Welcome file to verify
*/
@@ -1191,58 +1112,51 @@ public interface Context extends Container, ContextBind {
/**
- * @return the set of welcome files defined for this Context. If none are
- * defined, a zero-length array is returned.
+ * @return the set of welcome files defined for this Context. If none are defined, a zero-length array is returned.
*/
String[] findWelcomeFiles();
/**
- * @return the set of LifecycleListener classes that will be added to
- * newly created Wrappers automatically.
+ * @return the set of LifecycleListener classes that will be added to newly created Wrappers automatically.
*/
String[] findWrapperLifecycles();
/**
- * @return the set of ContainerListener classes that will be added to
- * newly created Wrappers automatically.
+ * @return the set of ContainerListener classes that will be added to newly created Wrappers automatically.
*/
String[] findWrapperListeners();
/**
- * Notify all {@link jakarta.servlet.ServletRequestListener}s that a request
- * has started.
+ * Notify all {@link jakarta.servlet.ServletRequestListener}s that a request has started.
*
* @param request The request object that will be passed to the listener
- * @return <code>true</code> if the listeners fire successfully, else
- * <code>false</code>
+ *
+ * @return <code>true</code> if the listeners fire successfully, else <code>false</code>
*/
boolean fireRequestInitEvent(ServletRequest request);
/**
- * Notify all {@link jakarta.servlet.ServletRequestListener}s that a request
- * has ended.
+ * Notify all {@link jakarta.servlet.ServletRequestListener}s that a request has ended.
*
* @param request The request object that will be passed to the listener
- * @return <code>true</code> if the listeners fire successfully, else
- * <code>false</code>
+ *
+ * @return <code>true</code> if the listeners fire successfully, else <code>false</code>
*/
boolean fireRequestDestroyEvent(ServletRequest request);
/**
* Reload this web application, if reloading is supported.
*
- * @exception IllegalStateException if the <code>reloadable</code>
- * property is set to <code>false</code>.
+ * @exception IllegalStateException if the <code>reloadable</code> property is set to <code>false</code>.
*/
void reload();
/**
- * Remove the specified application listener class from the set of
- * listeners for this application.
+ * Remove the specified application listener class from the set of listeners for this application.
*
* @param listener Java class name of the listener to be removed
*/
@@ -1250,8 +1164,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the application parameter with the specified name from
- * the set for this application.
+ * Remove the application parameter with the specified name from the set for this application.
*
* @param name Name of the application parameter to remove
*/
@@ -1267,8 +1180,8 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the error page for the specified error code or
- * Java language exception, if it exists; otherwise, no action is taken.
+ * Remove the error page for the specified error code or Java language exception, if it exists; otherwise, no action
+ * is taken.
*
* @param errorPage The error page definition to be removed
*/
@@ -1276,8 +1189,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the specified filter definition from this Context, if it exists;
- * otherwise, no action is taken.
+ * Remove the specified filter definition from this Context, if it exists; otherwise, no action is taken.
*
* @param filterDef Filter definition to be removed
*/
@@ -1293,8 +1205,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the MIME mapping for the specified extension, if it exists;
- * otherwise, no action is taken.
+ * Remove the MIME mapping for the specified extension, if it exists; otherwise, no action is taken.
*
* @param extension Extension to remove the mapping for
*/
@@ -1302,8 +1213,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the context initialization parameter with the specified
- * name, if it exists; otherwise, no action is taken.
+ * Remove the context initialization parameter with the specified name, if it exists; otherwise, no action is taken.
*
* @param name Name of the parameter to remove
*/
@@ -1327,8 +1237,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove any servlet mapping for the specified pattern, if it exists;
- * otherwise, no action is taken.
+ * Remove any servlet mapping for the specified pattern, if it exists; otherwise, no action is taken.
*
* @param pattern URL pattern of the mapping to remove
*/
@@ -1336,8 +1245,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the specified watched resource name from the list associated
- * with this Context.
+ * Remove the specified watched resource name from the list associated with this Context.
*
* @param name Name of the watched resource to be removed
*/
@@ -1345,8 +1253,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove the specified welcome file name from the list recognized
- * by this Context.
+ * Remove the specified welcome file name from the list recognized by this Context.
*
* @param name Name of the welcome file to be removed
*/
@@ -1354,8 +1261,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove a class name from the set of LifecycleListener classes that
- * will be added to newly created Wrappers.
+ * Remove a class name from the set of LifecycleListener classes that will be added to newly created Wrappers.
*
* @param listener Class name of a LifecycleListener class to be removed
*/
@@ -1363,8 +1269,7 @@ public interface Context extends Container, ContextBind {
/**
- * Remove a class name from the set of ContainerListener classes that
- * will be added to newly created Wrappers.
+ * Remove a class name from the set of ContainerListener classes that will be added to newly created Wrappers.
*
* @param listener Class name of a ContainerListener class to be removed
*/
@@ -1372,8 +1277,7 @@ public interface Context extends Container, ContextBind {
/**
- * @return the real path for a given virtual path, if possible; otherwise
- * return <code>null</code>.
+ * @return the real path for a given virtual path, if possible; otherwise return <code>null</code>.
*
* @param path The path to the desired resource
*/
@@ -1381,15 +1285,13 @@ public interface Context extends Container, ContextBind {
/**
- * @return the effective major version of the Servlet spec used by this
- * context.
+ * @return the effective major version of the Servlet spec used by this context.
*/
int getEffectiveMajorVersion();
/**
- * Set the effective major version of the Servlet spec used by this
- * context.
+ * Set the effective major version of the Servlet spec used by this context.
*
* @param major Set the version number
*/
@@ -1397,15 +1299,13 @@ public interface Context extends Container, ContextBind {
/**
- * @return the effective minor version of the Servlet spec used by this
- * context.
+ * @return the effective minor version of the Servlet spec used by this context.
*/
int getEffectiveMinorVersion();
/**
- * Set the effective minor version of the Servlet spec used by this
- * context.
+ * Set the effective minor version of the Servlet spec used by this context.
*
* @param minor Set the version number
*/
@@ -1413,15 +1313,13 @@ public interface Context extends Container, ContextBind {
/**
- * @return the JSP configuration for this context.
- * Will be null if there is no JSP configuration.
+ * @return the JSP configuration for this context. Will be null if there is no JSP configuration.
*/
JspConfigDescriptor getJspConfigDescriptor();
/**
- * Set the JspConfigDescriptor for this context.
- * A null value indicates there is not JSP configuration.
+ * Set the JspConfigDescriptor for this context. A null value indicates there is not JSP configuration.
*
* @param descriptor the new JSP configuration
*/
@@ -1431,12 +1329,10 @@ public interface Context extends Container, ContextBind {
/**
* Add a ServletContainerInitializer instance to this web application.
*
- * @param sci The instance to add
- * @param classes The classes in which the initializer expressed an
- * interest
+ * @param sci The instance to add
+ * @param classes The classes in which the initializer expressed an interest
*/
- void addServletContainerInitializer(
- ServletContainerInitializer sci, Set<Class<?>> classes);
+ void addServletContainerInitializer(ServletContainerInitializer sci, Set<Class<?>> classes);
/**
@@ -1458,18 +1354,18 @@ public interface Context extends Container, ContextBind {
/**
* Notification that Servlet security has been dynamically set in a
* {@link jakarta.servlet.ServletRegistration.Dynamic}
- * @param registration Servlet security was modified for
+ *
+ * @param registration Servlet security was modified for
* @param servletSecurityElement new security constraints for this Servlet
- * @return urls currently mapped to this registration that are already
- * present in web.xml
+ *
+ * @return urls currently mapped to this registration that are already present in web.xml
*/
Set<String> addServletSecurity(ServletRegistration.Dynamic registration,
ServletSecurityElement servletSecurityElement);
/**
- * Sets the (comma separated) list of Servlets that expect a resource to be
- * present. Used to ensure that welcome files associated with Servlets that
- * expect a resource to be present are not mapped when there is no resource.
+ * Sets the (comma separated) list of Servlets that expect a resource to be present. Used to ensure that welcome
+ * files associated with Servlets that expect a resource to be present are not mapped when there is no resource.
*
* @param resourceOnlyServlets The Servlet names comma separated list
*/
@@ -1478,84 +1374,73 @@ public interface Context extends Container, ContextBind {
/**
* Obtains the list of Servlets that expect a resource to be present.
*
- * @return A comma separated list of Servlet names as used in web.xml
+ * @return A comma separated list of Servlet names as used in web.xml
*/
String getResourceOnlyServlets();
/**
* Checks the named Servlet to see if it expects a resource to be present.
*
- * @param servletName Name of the Servlet (as per web.xml) to check
- * @return <code>true</code> if the Servlet expects a resource,
- * otherwise <code>false</code>
+ * @param servletName Name of the Servlet (as per web.xml) to check
+ *
+ * @return <code>true</code> if the Servlet expects a resource, otherwise <code>false</code>
*/
boolean isResourceOnlyServlet(String servletName);
/**
- * @return the base name to use for WARs, directories or context.xml files
- * for this context.
+ * @return the base name to use for WARs, directories or context.xml files for this context.
*/
String getBaseName();
/**
- * Set the version of this web application - used to differentiate
- * different versions of the same web application when using parallel
- * deployment.
+ * Set the version of this web application - used to differentiate different versions of the same web application
+ * when using parallel deployment.
*
- * @param webappVersion The webapp version associated with the context,
- * which should be unique
+ * @param webappVersion The webapp version associated with the context, which should be unique
*/
void setWebappVersion(String webappVersion);
/**
- * @return The version of this web application, used to differentiate
- * different versions of the same web application when using parallel
- * deployment. If not specified, defaults to the empty string.
+ * @return The version of this web application, used to differentiate different versions of the same web application
+ * when using parallel deployment. If not specified, defaults to the empty string.
*/
String getWebappVersion();
/**
- * Configure whether or not requests listeners will be fired on forwards for
- * this Context.
+ * Configure whether or not requests listeners will be fired on forwards for this Context.
*
* @param enable <code>true</code> to fire request listeners when forwarding
*/
void setFireRequestListenersOnForwards(boolean enable);
/**
- * @return whether or not requests listeners will be fired on forwards for
- * this Context.
+ * @return whether or not requests listeners will be fired on forwards for this Context.
*/
boolean getFireRequestListenersOnForwards();
/**
- * Configures if a user presents authentication credentials, whether the
- * context will process them when the request is for a non-protected
- * resource.
+ * Configures if a user presents authentication credentials, whether the context will process them when the request
+ * is for a non-protected resource.
*
- * @param enable <code>true</code> to perform authentication even outside
- * security constraints
+ * @param enable <code>true</code> to perform authentication even outside security constraints
*/
void setPreemptiveAuthentication(boolean enable);
/**
- * @return if a user presents authentication credentials, will the
- * context will process them when the request is for a non-protected
- * resource.
+ * @return if a user presents authentication credentials, will the context will process them when the request is for
+ * a non-protected resource.
*/
boolean getPreemptiveAuthentication();
/**
- * Configures if a response body is included when a redirect response is
- * sent to the client.
+ * Configures if a response body is included when a redirect response is sent to the client.
*
* @param enable <code>true</code> to send a response body for redirects
*/
void setSendRedirectBody(boolean enable);
/**
- * @return if the context is configured to include a response body as
- * part of a redirect response.
+ * @return if the context is configured to include a response body as part of a redirect response.
*/
boolean getSendRedirectBody();
@@ -1584,8 +1469,8 @@ public interface Context extends Container, ContextBind {
void setResources(WebResourceRoot resources);
/**
- * @return the Manager with which this Context is associated. If there is
- * no associated Manager, return <code>null</code>.
+ * @return the Manager with which this Context is associated. If there is no associated Manager, return
+ * <code>null</code>.
*/
Manager getManager();
@@ -1598,163 +1483,134 @@ public interface Context extends Container, ContextBind {
void setManager(Manager manager);
/**
- * Sets the flag that indicates if /WEB-INF/classes should be treated like
- * an exploded JAR and JAR resources made available as if they were in a
- * JAR.
+ * Sets the flag that indicates if /WEB-INF/classes should be treated like an exploded JAR and JAR resources made
+ * available as if they were in a JAR.
*
* @param addWebinfClassesResources The new value for the flag
*/
void setAddWebinfClassesResources(boolean addWebinfClassesResources);
/**
- * @return the flag that indicates if /WEB-INF/classes should be treated like
- * an exploded JAR and JAR resources made available as if they were in a
- * JAR.
+ * @return the flag that indicates if /WEB-INF/classes should be treated like an exploded JAR and JAR resources made
+ * available as if they were in a JAR.
*/
boolean getAddWebinfClassesResources();
/**
- * Add a post construct method definition for the given class, if there is
- * an existing definition for the specified class - IllegalArgumentException
- * will be thrown.
+ * Add a post construct method definition for the given class, if there is an existing definition for the specified
+ * class - IllegalArgumentException will be thrown.
*
- * @param clazz Fully qualified class name
- * @param method
- * Post construct method name
- * @throws IllegalArgumentException
- * if the fully qualified class name or method name are
- * <code>NULL</code>; if there is already post construct method
- * definition for the given class
+ * @param clazz Fully qualified class name
+ * @param method Post construct method name
+ *
+ * @throws IllegalArgumentException if the fully qualified class name or method name are <code>NULL</code>; if there
+ * is already post construct method definition for the given class
*/
void addPostConstructMethod(String clazz, String method);
/**
- * Add a pre destroy method definition for the given class, if there is an
- * existing definition for the specified class - IllegalArgumentException
- * will be thrown.
+ * Add a pre destroy method definition for the given class, if there is an existing definition for the specified
+ * class - IllegalArgumentException will be thrown.
*
- * @param clazz Fully qualified class name
- * @param method
- * Post construct method name
- * @throws IllegalArgumentException
- * if the fully qualified class name or method name are
- * <code>NULL</code>; if there is already pre destroy method
- * definition for the given class
+ * @param clazz Fully qualified class name
+ * @param method Post construct method name
+ *
+ * @throws IllegalArgumentException if the fully qualified class name or method name are <code>NULL</code>; if there
+ * is already pre destroy method definition for the given class
*/
void addPreDestroyMethod(String clazz, String method);
/**
- * Removes the post construct method definition for the given class, if it
- * exists; otherwise, no action is taken.
+ * Removes the post construct method definition for the given class, if it exists; otherwise, no action is taken.
*
- * @param clazz
- * Fully qualified class name
+ * @param clazz Fully qualified class name
*/
void removePostConstructMethod(String clazz);
/**
- * Removes the pre destroy method definition for the given class, if it
- * exists; otherwise, no action is taken.
+ * Removes the pre destroy method definition for the given class, if it exists; otherwise, no action is taken.
*
- * @param clazz
- * Fully qualified class name
+ * @param clazz Fully qualified class name
*/
void removePreDestroyMethod(String clazz);
/**
- * Returns the method name that is specified as post construct method for
- * the given class, if it exists; otherwise <code>NULL</code> will be
- * returned.
+ * Returns the method name that is specified as post construct method for the given class, if it exists; otherwise
+ * <code>NULL</code> will be returned.
*
- * @param clazz
- * Fully qualified class name
+ * @param clazz Fully qualified class name
*
- * @return the method name that is specified as post construct method for
- * the given class, if it exists; otherwise <code>NULL</code> will
- * be returned.
+ * @return the method name that is specified as post construct method for the given class, if it exists; otherwise
+ * <code>NULL</code> will be returned.
*/
String findPostConstructMethod(String clazz);
/**
- * Returns the method name that is specified as pre destroy method for the
- * given class, if it exists; otherwise <code>NULL</code> will be returned.
+ * Returns the method name that is specified as pre destroy method for the given class, if it exists; otherwise
+ * <code>NULL</code> will be returned.
*
- * @param clazz
- * Fully qualified class name
+ * @param clazz Fully qualified class name
*
- * @return the method name that is specified as pre destroy method for the
- * given class, if it exists; otherwise <code>NULL</code> will be
- * returned.
+ * @return the method name that is specified as pre destroy method for the given class, if it exists; otherwise
+ * <code>NULL</code> will be returned.
*/
String findPreDestroyMethod(String clazz);
/**
- * Returns a map with keys - fully qualified class names of the classes that
- * have post construct methods and the values are the corresponding method
- * names. If there are no such classes an empty map will be returned.
+ * Returns a map with keys - fully qualified class names of the classes that have post construct methods and the
+ * values are the corresponding method names. If there are no such classes an empty map will be returned.
*
- * @return a map with keys - fully qualified class names of the classes that
- * have post construct methods and the values are the corresponding
- * method names.
+ * @return a map with keys - fully qualified class names of the classes that have post construct methods and the
+ * values are the corresponding method names.
*/
- Map<String, String> findPostConstructMethods();
+ Map<String,String> findPostConstructMethods();
/**
- * Returns a map with keys - fully qualified class names of the classes that
- * have pre destroy methods and the values are the corresponding method
- * names. If there are no such classes an empty map will be returned.
+ * Returns a map with keys - fully qualified class names of the classes that have pre destroy methods and the values
+ * are the corresponding method names. If there are no such classes an empty map will be returned.
*
- * @return a map with keys - fully qualified class names of the classes that
- * have pre destroy methods and the values are the corresponding
- * method names.
+ * @return a map with keys - fully qualified class names of the classes that have pre destroy methods and the values
+ * are the corresponding method names.
*/
- Map<String, String> findPreDestroyMethods();
+ Map<String,String> findPreDestroyMethods();
/**
- * @return the token necessary for operations on the associated JNDI naming
- * context.
+ * @return the token necessary for operations on the associated JNDI naming context.
*/
Object getNamingToken();
/**
- * Sets the {@link CookieProcessor} that will be used to process cookies
- * for this Context.
+ * Sets the {@link CookieProcessor} that will be used to process cookies for this Context.
*
- * @param cookieProcessor The new cookie processor
+ * @param cookieProcessor The new cookie processor
*
- * @throws IllegalArgumentException If a {@code null} CookieProcessor is
- * specified
+ * @throws IllegalArgumentException If a {@code null} CookieProcessor is specified
*/
void setCookieProcessor(CookieProcessor cookieProcessor);
/**
- * @return the {@link CookieProcessor} that will be used to process cookies
- * for this Context.
+ * @return the {@link CookieProcessor} that will be used to process cookies for this Context.
*/
CookieProcessor getCookieProcessor();
/**
- * When a client provides the ID for a new session, should that ID be
- * validated? The only use case for using a client provided session ID is to
- * have a common session ID across multiple web applications. Therefore,
- * any client provided session ID should already exist in another web
- * application. If this check is enabled, the client provided session ID
- * will only be used if the session ID exists in at least one other web
- * application for the current host. Note that the following additional
- * tests are always applied, irrespective of this setting:
+ * When a client provides the ID for a new session, should that ID be validated? The only use case for using a
+ * client provided session ID is to have a common session ID across multiple web applications. Therefore, any client
+ * provided session ID should already exist in another web application. If this check is enabled, the client
+ * provided session ID will only be used if the session ID exists in at least one other web application for the
+ * current host. Note that the following additional tests are always applied, irrespective of this setting:
* <ul>
* <li>The session ID is provided by a cookie</li>
* <li>The session cookie has a path of {@code /}</li>
* </ul>
*
- * @param validateClientProvidedNewSessionId
- * {@code true} if validation should be applied
+ * @param validateClientProvidedNewSessionId {@code true} if validation should be applied
*/
void setValidateClientProvidedNewSessionId(boolean validateClientProvidedNewSessionId);
/**
- * Will client provided session IDs be validated (see {@link
- * #setValidateClientProvidedNewSessionId(boolean)}) before use?
+ * Will client provided session IDs be validated (see {@link #setValidateClientProvidedNewSessionId(boolean)})
+ * before use?
*
* @return {@code true} if validation will be applied. Otherwise, {@code
* false}
@@ -1762,96 +1618,77 @@ public interface Context extends Container, ContextBind {
boolean getValidateClientProvidedNewSessionId();
/**
- * If enabled, requests for a web application context root will be
- * redirected (adding a trailing slash) by the Mapper. This is more
- * efficient but has the side effect of confirming that the context path is
- * valid.
+ * If enabled, requests for a web application context root will be redirected (adding a trailing slash) by the
+ * Mapper. This is more efficient but has the side effect of confirming that the context path is valid.
*
* @param mapperContextRootRedirectEnabled Should the redirects be enabled?
*/
void setMapperContextRootRedirectEnabled(boolean mapperContextRootRedirectEnabled);
/**
- * Determines if requests for a web application context root will be
- * redirected (adding a trailing slash) by the Mapper. This is more
- * efficient but has the side effect of confirming that the context path is
- * valid.
+ * Determines if requests for a web application context root will be redirected (adding a trailing slash) by the
+ * Mapper. This is more efficient but has the side effect of confirming that the context path is valid.
*
- * @return {@code true} if the Mapper level redirect is enabled for this
- * Context.
+ * @return {@code true} if the Mapper level redirect is enabled for this Context.
*/
boolean getMapperContextRootRedirectEnabled();
/**
- * If enabled, requests for a directory will be redirected (adding a
- * trailing slash) by the Mapper. This is more efficient but has the
- * side effect of confirming that the directory is valid.
+ * If enabled, requests for a directory will be redirected (adding a trailing slash) by the Mapper. This is more
+ * efficient but has the side effect of confirming that the directory is valid.
*
* @param mapperDirectoryRedirectEnabled Should the redirects be enabled?
*/
void setMapperDirectoryRedirectEnabled(boolean mapperDirectoryRedirectEnabled);
/**
- * Determines if requests for a directory will be redirected (adding a
- * trailing slash) by the Mapper. This is more efficient but has the
- * side effect of confirming that the directory is valid.
+ * Determines if requests for a directory will be redirected (adding a trailing slash) by the Mapper. This is more
+ * efficient but has the side effect of confirming that the directory is valid.
*
- * @return {@code true} if the Mapper level redirect is enabled for this
- * Context.
+ * @return {@code true} if the Mapper level redirect is enabled for this Context.
*/
boolean getMapperDirectoryRedirectEnabled();
/**
- * Controls whether HTTP 1.1 and later location headers generated by a call
- * to {@link jakarta.servlet.http.HttpServletResponse#sendRedirect(String)}
- * will use relative or absolute redirects.
+ * Controls whether HTTP 1.1 and later location headers generated by a call to
+ * {@link jakarta.servlet.http.HttpServletResponse#sendRedirect(String)} will use relative or absolute redirects.
* <p>
- * Relative redirects are more efficient but may not work with reverse
- * proxies that change the context path. It should be noted that it is not
- * recommended to use a reverse proxy to change the context path because of
- * the multiple issues it creates.
+ * Relative redirects are more efficient but may not work with reverse proxies that change the context path. It
+ * should be noted that it is not recommended to use a reverse proxy to change the context path because of the
+ * multiple issues it creates.
* <p>
- * Absolute redirects should work with reverse proxies that change the
- * context path but may cause issues with the
- * {@link org.apache.catalina.filters.RemoteIpFilter} if the filter is
- * changing the scheme and/or port.
+ * Absolute redirects should work with reverse proxies that change the context path but may cause issues with the
+ * {@link org.apache.catalina.filters.RemoteIpFilter} if the filter is changing the scheme and/or port.
*
- * @param useRelativeRedirects {@code true} to use relative redirects and
- * {@code false} to use absolute redirects
+ * @param useRelativeRedirects {@code true} to use relative redirects and {@code false} to use absolute redirects
*/
void setUseRelativeRedirects(boolean useRelativeRedirects);
/**
* Will HTTP 1.1 and later location headers generated by a call to
- * {@link jakarta.servlet.http.HttpServletResponse#sendRedirect(String)} use
- * relative or absolute redirects.
+ * {@link jakarta.servlet.http.HttpServletResponse#sendRedirect(String)} use relative or absolute redirects.
*
- * @return {@code true} if relative redirects will be used {@code false} if
- * absolute redirects are used.
+ * @return {@code true} if relative redirects will be used {@code false} if absolute redirects are used.
*
* @see #setUseRelativeRedirects(boolean)
*/
boolean getUseRelativeRedirects();
/**
- * Are paths used in calls to obtain a request dispatcher expected to be
- * encoded? This affects both how Tomcat handles calls to obtain a request
- * dispatcher as well as how Tomcat generates paths used to obtain request
+ * Are paths used in calls to obtain a request dispatcher expected to be encoded? This affects both how Tomcat
+ * handles calls to obtain a request dispatcher as well as how Tomcat generates paths used to obtain request
* dispatchers internally.
*
- * @param dispatchersUseEncodedPaths {@code true} to use encoded paths,
- * otherwise {@code false}
+ * @param dispatchersUseEncodedPaths {@code true} to use encoded paths, otherwise {@code false}
*/
void setDispatchersUseEncodedPaths(boolean dispatchersUseEncodedPaths);
/**
- * Are paths used in calls to obtain a request dispatcher expected to be
- * encoded? This applies to both how Tomcat handles calls to obtain a request
- * dispatcher as well as how Tomcat generates paths used to obtain request
+ * Are paths used in calls to obtain a request dispatcher expected to be encoded? This applies to both how Tomcat
+ * handles calls to obtain a request dispatcher as well as how Tomcat generates paths used to obtain request
* dispatchers internally.
*
- * @return {@code true} if encoded paths will be used, otherwise
- * {@code false}
+ * @return {@code true} if encoded paths will be used, otherwise {@code false}
*/
boolean getDispatchersUseEncodedPaths();
@@ -1884,22 +1721,19 @@ public interface Context extends Container, ContextBind {
String getResponseCharacterEncoding();
/**
- * Configure if, when returning a context path from {@link
- * jakarta.servlet.http.HttpServletRequest#getContextPath()}, the return value
- * is allowed to contain multiple leading '/' characters.
+ * Configure if, when returning a context path from
+ * {@link jakarta.servlet.http.HttpServletRequest#getContextPath()}, the return value is allowed to contain multiple
+ * leading '/' characters.
*
* @param allowMultipleLeadingForwardSlashInPath The new value for the flag
*/
- void setAllowMultipleLeadingForwardSlashInPath(
- boolean allowMultipleLeadingForwardSlashInPath);
+ void setAllowMultipleLeadingForwardSlashInPath(boolean allowMultipleLeadingForwardSlashInPath);
/**
- * When returning a context path from {@link
- * jakarta.servlet.http.HttpServletRequest#getContextPath()}, is it allowed to
- * contain multiple leading '/' characters?
+ * When returning a context path from {@link jakarta.servlet.http.HttpServletRequest#getContextPath()}, is it
+ * allowed to contain multiple leading '/' characters?
*
- * @return <code>true</code> if multiple leading '/' characters are allowed,
- * otherwise <code>false</code>
+ * @return <code>true</code> if multiple leading '/' characters are allowed, otherwise <code>false</code>
*/
boolean getAllowMultipleLeadingForwardSlashInPath();
@@ -1911,34 +1745,30 @@ public interface Context extends Container, ContextBind {
/**
- * Configure whether Tomcat will attempt to create an upload target used by
- * this web application if it does not exist when the web application
- * attempts to use it.
+ * Configure whether Tomcat will attempt to create an upload target used by this web application if it does not
+ * exist when the web application attempts to use it.
*
- * @param createUploadTargets {@code true} if Tomcat should attempt to
- * create the upload target, otherwise {@code false}
+ * @param createUploadTargets {@code true} if Tomcat should attempt to create the upload target, otherwise
+ * {@code false}
*/
void setCreateUploadTargets(boolean createUploadTargets);
/**
- * Will Tomcat attempt to create an upload target used by this web
- * application if it does not exist when the web application attempts to use
- * it?
+ * Will Tomcat attempt to create an upload target used by this web application if it does not exist when the web
+ * application attempts to use it?
*
- * @return {@code true} if Tomcat will attempt to create an upload target
- * otherwise {@code false}
+ * @return {@code true} if Tomcat will attempt to create an upload target otherwise {@code false}
*/
boolean getCreateUploadTargets();
/**
- * If this is <code>true</code>, every request that is associated with a
- * session will cause the session's last accessed time to be updated
- * regardless of whether or not the request explicitly accesses the session.
- * If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
- * <code>true</code>, the default of this setting will be <code>true</code>,
- * else the default value will be <code>false</code>.
+ * If this is <code>true</code>, every request that is associated with a session will cause the session's last
+ * accessed time to be updated regardless of whether or not the request explicitly accesses the session. If
+ * <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to <code>true</code>, the default of this
+ * setting will be <code>true</code>, else the default value will be <code>false</code>.
+ *
* @return the flag value
*/
boolean getAlwaysAccessSession();
@@ -1946,42 +1776,39 @@ public interface Context extends Container, ContextBind {
/**
* Set the session access behavior.
+ *
* @param alwaysAccessSession the new flag value
*/
void setAlwaysAccessSession(boolean alwaysAccessSession);
/**
- * If this is <code>true</code> then the path passed to
- * <code>ServletContext.getResource()</code> or
- * <code>ServletContext.getResourceAsStream()</code> must start with
- * "/". If <code>false</code>, code like
- * <code>getResource("myfolder/myresource.txt")</code> will work as Tomcat
- * will prepend "/" to the provided path.
- * If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
- * <code>true</code>, the default of this setting will be <code>true</code>,
- * else the default value will be <code>false</code>.
+ * If this is <code>true</code> then the path passed to <code>ServletContext.getResource()</code> or
+ * <code>ServletContext.getResourceAsStream()</code> must start with "/". If <code>false</code>, code like
+ * <code>getResource("myfolder/myresource.txt")</code> will work as Tomcat will prepend "/" to the
+ * provided path. If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to <code>true</code>, the
+ * default of this setting will be <code>true</code>, else the default value will be <code>false</code>.
+ *
* @return the flag value
*/
boolean getContextGetResourceRequiresSlash();
/**
- * Allow using <code>ServletContext.getResource()</code> or
- * <code>ServletContext.getResourceAsStream()</code> without
- * a leading "/".
+ * Allow using <code>ServletContext.getResource()</code> or <code>ServletContext.getResourceAsStream()</code>
+ * without a leading "/".
+ *
* @param contextGetResourceRequiresSlash the new flag value
*/
void setContextGetResourceRequiresSlash(boolean contextGetResourceRequiresSlash);
/**
- * If this is <code>true</code> then any wrapped request or response
- * object passed to an application dispatcher will be checked to ensure that
- * it has wrapped the original request or response.
- * If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
- * <code>true</code>, the default of this setting will be <code>true</code>,
- * else the default value will be <code>false</code>.
+ * If this is <code>true</code> then any wrapped request or response object passed to an application dispatcher will
+ * be checked to ensure that it has wrapped the original request or response. If
+ * <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to <code>true</code>, the default of this
+ * setting will be <code>true</code>, else the default value will be <code>false</code>.
+ *
* @return the flag value
*/
boolean getDispatcherWrapsSameObject();
@@ -1989,36 +1816,38 @@ public interface Context extends Container, ContextBind {
/**
* Allow disabling the object wrap check in the request dispatcher.
+ *
* @param dispatcherWrapsSameObject the new flag value
*/
void setDispatcherWrapsSameObject(boolean dispatcherWrapsSameObject);
/**
- * If this is <code>true</code>, then following a forward the response will
- * be unwrapped to suspend the Catalina response instead of simply closing
- * the top level response. The default value is <code>false</code>.
+ * If this is <code>true</code>, then following a forward the response will be unwrapped to suspend the Catalina
+ * response instead of simply closing the top level response. The default value is <code>false</code>.
+ *
* @return the flag value
*/
boolean getSuspendWrappedResponseAfterForward();
/**
- * Allows unwrapping the response object to suspend the response following
- * a forward.
+ * Allows unwrapping the response object to suspend the response following a forward.
+ *
* @param suspendWrappedResponseAfterForward the new flag value
*/
void setSuspendWrappedResponseAfterForward(boolean suspendWrappedResponseAfterForward);
/**
- * Find configuration file with the specified path, first looking into the
- * webapp resources, then delegating to
- * <code>ConfigFileLoader.getSource().getResource</code>. The
- * <code>WEBAPP_PROTOCOL</code> constant prefix is used to denote webapp
- * resources.
+ * Find configuration file with the specified path, first looking into the webapp resources, then delegating to
+ * <code>ConfigFileLoader.getSource().getResource</code>. The <code>WEBAPP_PROTOCOL</code> constant prefix is used
+ * to denote webapp resources.
+ *
* @param name The resource name
+ *
* @return the resource
+ *
* @throws IOException if an error occurs or if the resource does not exist
*/
default Resource findConfigFileResource(String name) throws IOException {
@@ -2040,21 +1869,22 @@ public interface Context extends Container, ContextBind {
/**
- * @return <code>true</code> if the resources archive lookup will
- * use a bloom filter.
+ * @return <code>true</code> if the resources archive lookup will use a bloom filter.
*
- * @deprecated This method will be removed in Tomcat 11 onwards.
- * Use {@link WebResourceRoot#getArchiveIndexStrategy()}
+ * @deprecated This method will be removed in Tomcat 11 onwards. Use
+ * {@link WebResourceRoot#getArchiveIndexStrategy()}
*/
- @Deprecated boolean getUseBloomFilterForArchives();
+ @Deprecated
+ boolean getUseBloomFilterForArchives();
/**
* Set bloom filter flag value.
*
* @param useBloomFilterForArchives The new fast class path scan flag
*
- * @deprecated This method will be removed in Tomcat 11 onwards
- * Use {@link WebResourceRoot#setArchiveIndexStrategy(String)}
+ * @deprecated This method will be removed in Tomcat 11 onwards Use
+ * {@link WebResourceRoot#setArchiveIndexStrategy(String)}
*/
- @Deprecated void setUseBloomFilterForArchives(boolean useBloomFilterForArchives);
+ @Deprecated
+ void setUseBloomFilterForArchives(boolean useBloomFilterForArchives);
}
diff --git a/java/org/apache/catalina/CredentialHandler.java b/java/org/apache/catalina/CredentialHandler.java
index e3dc221cff..6ecf7eb6c1 100644
--- a/java/org/apache/catalina/CredentialHandler.java
+++ b/java/org/apache/catalina/CredentialHandler.java
@@ -17,8 +17,8 @@
package org.apache.catalina;
/**
- * This interface is used by the {@link Realm} to compare the user provided
- * credentials with the credentials stored in the {@link Realm} for that user.
+ * This interface is used by the {@link Realm} to compare the user provided credentials with the credentials stored in
+ * the {@link Realm} for that user.
*/
public interface CredentialHandler {
@@ -28,19 +28,16 @@ public interface CredentialHandler {
* @param inputCredentials User provided credentials
* @param storedCredentials Credentials stored in the {@link Realm}
*
- * @return <code>true</code> if the inputCredentials match the
- * storedCredentials, otherwise <code>false</code>
+ * @return <code>true</code> if the inputCredentials match the storedCredentials, otherwise <code>false</code>
*/
boolean matches(String inputCredentials, String storedCredentials);
/**
- * Generates the equivalent stored credentials for the given input
- * credentials.
+ * Generates the equivalent stored credentials for the given input credentials.
*
- * @param inputCredentials User provided credentials
+ * @param inputCredentials User provided credentials
*
- * @return The equivalent stored credentials for the given input
- * credentials
+ * @return The equivalent stored credentials for the given input credentials
*/
String mutate(String inputCredentials);
}
diff --git a/java/org/apache/catalina/DistributedManager.java b/java/org/apache/catalina/DistributedManager.java
index 2ac5fd4e59..ccf4f24072 100644
--- a/java/org/apache/catalina/DistributedManager.java
+++ b/java/org/apache/catalina/DistributedManager.java
@@ -19,32 +19,29 @@ package org.apache.catalina;
import java.util.Set;
/**
- * Interface implemented by session managers that do not keep a complete copy
- * of all sessions in memory but do know where every session is. The
- * BackupManager is an example of such a Manager as are implementations of the
- * StoreManager interface.
+ * Interface implemented by session managers that do not keep a complete copy of all sessions in memory but do know
+ * where every session is. The BackupManager is an example of such a Manager as are implementations of the StoreManager
+ * interface.
* <p>
- * With the BackupManager, sessions can be primary (primary copy on this node),
- * backup (backup copy on this node) or proxy (only the session ID on this
- * node). The identity of the primary and backup nodes are known for all
- * sessions, including proxy sessions.
+ * With the BackupManager, sessions can be primary (primary copy on this node), backup (backup copy on this node) or
+ * proxy (only the session ID on this node). The identity of the primary and backup nodes are known for all sessions,
+ * including proxy sessions.
* <p>
- * With StoreManager implementations, sessions can be primary (session is in
- * memory) or proxy (session is in the Store).
+ * With StoreManager implementations, sessions can be primary (session is in memory) or proxy (session is in the Store).
*/
public interface DistributedManager {
/**
* Returns the total session count for primary, backup and proxy.
*
- * @return The total session count across the cluster.
+ * @return The total session count across the cluster.
*/
int getActiveSessionsFull();
/**
* Returns the list of all sessions IDS (primary, backup and proxy).
*
- * @return The complete set of sessions IDs across the cluster.
+ * @return The complete set of sessions IDs across the cluster.
*/
Set<String> getSessionIdsFull();
}
diff --git a/java/org/apache/catalina/Engine.java b/java/org/apache/catalina/Engine.java
index 201e93ccff..61da35f55d 100644
--- a/java/org/apache/catalina/Engine.java
+++ b/java/org/apache/catalina/Engine.java
@@ -17,26 +17,21 @@
package org.apache.catalina;
/**
- * An <b>Engine</b> is a Container that represents the entire Catalina servlet
- * engine. It is useful in the following types of scenarios:
+ * An <b>Engine</b> is a Container that represents the entire Catalina servlet engine. It is useful in the following
+ * types of scenarios:
* <ul>
- * <li>You wish to use Interceptors that see every single request processed
- * by the entire engine.
- * <li>You wish to run Catalina in with a standalone HTTP connector, but still
- * want support for multiple virtual hosts.
+ * <li>You wish to use Interceptors that see every single request processed by the entire engine.
+ * <li>You wish to run Catalina in with a standalone HTTP connector, but still want support for multiple virtual hosts.
* </ul>
- * In general, you would not use an Engine when deploying Catalina connected
- * to a web server (such as Apache), because the Connector will have
- * utilized the web server's facilities to determine which Context (or
- * perhaps even which Wrapper) should be utilized to process this request.
+ * In general, you would not use an Engine when deploying Catalina connected to a web server (such as Apache), because
+ * the Connector will have utilized the web server's facilities to determine which Context (or perhaps even which
+ * Wrapper) should be utilized to process this request.
* <p>
- * The child containers attached to an Engine are generally implementations
- * of Host (representing a virtual host) or Context (representing individual
- * an individual servlet context), depending upon the Engine implementation.
+ * The child containers attached to an Engine are generally implementations of Host (representing a virtual host) or
+ * Context (representing individual an individual servlet context), depending upon the Engine implementation.
* <p>
- * If used, an Engine is always the top level Container in a Catalina
- * hierarchy. Therefore, the implementation's <code>setParent()</code> method
- * should throw <code>IllegalArgumentException</code>.
+ * If used, an Engine is always the top level Container in a Catalina hierarchy. Therefore, the implementation's
+ * <code>setParent()</code> method should throw <code>IllegalArgumentException</code>.
*
* @author Craig R. McClanahan
*/
@@ -65,8 +60,7 @@ public interface Engine extends Container {
/**
* Set the JvmRouteId for this engine.
*
- * @param jvmRouteId the (new) JVM Route ID. Each Engine within a cluster
- * must have a unique JVM Route ID.
+ * @param jvmRouteId the (new) JVM Route ID. Each Engine within a cluster must have a unique JVM Route ID.
*/
void setJvmRoute(String jvmRouteId);
diff --git a/java/org/apache/catalina/Globals.java b/java/org/apache/catalina/Globals.java
index ba1c4b5977..b748fa2fc9 100644
--- a/java/org/apache/catalina/Globals.java
+++ b/java/org/apache/catalina/Globals.java
@@ -44,18 +44,15 @@ public final class Globals {
/**
- * The request attribute under which we store the servlet name on a
- * named dispatcher request.
+ * The request attribute under which we store the servlet name on a named dispatcher request.
*/
public static final String NAMED_DISPATCHER_ATTR = "org.apache.catalina.NAMED";
/**
- * The request attribute that is set to {@code Boolean.TRUE} if some request
- * parameters have been ignored during request parameters parsing. It can
- * happen, for example, if there is a limit on the total count of parseable
- * parameters, or if parameter cannot be decoded, or any other error
- * happened during parameter parsing.
+ * The request attribute that is set to {@code Boolean.TRUE} if some request parameters have been ignored during
+ * request parameters parsing. It can happen, for example, if there is a limit on the total count of parseable
+ * parameters, or if parameter cannot be decoded, or any other error happened during parameter parsing.
*/
public static final String PARAMETER_PARSE_FAILED_ATTR = "org.apache.catalina.parameter_parse_failed";
@@ -67,108 +64,90 @@ public final class Globals {
/**
- * The request attribute set by the RemoteIpFilter, RemoteIpValve (and may
- * be set by other similar components) that identifies for the connector the
- * remote IP address claimed to be associated with this request when a
- * request is received via one or more proxies. It is typically provided via
- * the X-Forwarded-For HTTP header.
- *
- * Duplicated here for neater code in the catalina packages.
+ * The request attribute set by the RemoteIpFilter, RemoteIpValve (and may be set by other similar components) that
+ * identifies for the connector the remote IP address claimed to be associated with this request when a request is
+ * received via one or more proxies. It is typically provided via the X-Forwarded-For HTTP header. Duplicated here
+ * for neater code in the catalina packages.
*/
public static final String REMOTE_ADDR_ATTRIBUTE = org.apache.coyote.Constants.REMOTE_ADDR_ATTRIBUTE;
/**
- * The request attribute that is set to the value of {@code Boolean.TRUE}
- * by the RemoteIpFilter, RemoteIpValve (and other similar components) that identifies
- * a request which been forwarded via one or more proxies.
+ * The request attribute that is set to the value of {@code Boolean.TRUE} by the RemoteIpFilter, RemoteIpValve (and
+ * other similar components) that identifies a request which been forwarded via one or more proxies.
*/
public static final String REQUEST_FORWARDED_ATTRIBUTE = "org.apache.tomcat.request.forwarded";
/**
- * The request attribute that is set to the value of {@code Boolean.TRUE}
- * if connector processing this request supports use of sendfile.
- *
- * Duplicated here for neater code in the catalina packages.
+ * The request attribute that is set to the value of {@code Boolean.TRUE} if connector processing this request
+ * supports use of sendfile. Duplicated here for neater code in the catalina packages.
*/
public static final String SENDFILE_SUPPORTED_ATTR = org.apache.coyote.Constants.SENDFILE_SUPPORTED_ATTR;
/**
- * The request attribute that is set to the value of {@code Boolean.TRUE}
- * if {@link org.apache.catalina.filters.RemoteIpFilter} determines
- * that this request was submitted via a secure channel.
+ * The request attribute that is set to the value of {@code Boolean.TRUE} if
+ * {@link org.apache.catalina.filters.RemoteIpFilter} determines that this request was submitted via a secure
+ * channel.
*/
public static final String REMOTE_IP_FILTER_SECURE = "org.apache.catalina.filters.RemoteIpFilter.secure";
/**
- * The request attribute that can be used by a servlet to pass
- * to the connector the name of the file that is to be served
- * by sendfile. The value should be {@code String}
- * that is {@code File.getCanonicalPath()} of the file to be served.
- *
- * Duplicated here for neater code in the catalina packages.
+ * The request attribute that can be used by a servlet to pass to the connector the name of the file that is to be
+ * served by sendfile. The value should be {@code String} that is {@code File.getCanonicalPath()} of the file to be
+ * served. Duplicated here for neater code in the catalina packages.
*/
public static final String SENDFILE_FILENAME_ATTR = org.apache.coyote.Constants.SENDFILE_FILENAME_ATTR;
/**
- * The request attribute that can be used by a servlet to pass
- * to the connector the start offset of the part of a file
- * that is to be served by sendfile. The value should be
- * {@code Long}. To serve complete file
- * the value should be {@code Long.valueOf(0)}.
- *
- * Duplicated here for neater code in the catalina packages.
+ * The request attribute that can be used by a servlet to pass to the connector the start offset of the part of a
+ * file that is to be served by sendfile. The value should be {@code Long}. To serve complete file the value should
+ * be {@code Long.valueOf(0)}. Duplicated here for neater code in the catalina packages.
*/
public static final String SENDFILE_FILE_START_ATTR = org.apache.coyote.Constants.SENDFILE_FILE_START_ATTR;
/**
- * The request attribute that can be used by a servlet to pass
- * to the connector the end offset (not including) of the part
- * of a file that is to be served by sendfile. The value should be
- * {@code java.lang.Long}. To serve complete file
- * the value should be equal to the length of the file.
- *
- * Duplicated here for neater code in the catalina packages.
+ * The request attribute that can be used by a servlet to pass to the connector the end offset (not including) of
+ * the part of a file that is to be served by sendfile. The value should be {@code java.lang.Long}. To serve
+ * complete file the value should be equal to the length of the file. Duplicated here for neater code in the
+ * catalina packages.
*/
public static final String SENDFILE_FILE_END_ATTR = org.apache.coyote.Constants.SENDFILE_FILE_END_ATTR;
/**
- * The request attribute under which we store the array of X509Certificate
- * objects representing the certificate chain presented by our client,
- * if any.
+ * The request attribute under which we store the array of X509Certificate objects representing the certificate
+ * chain presented by our client, if any.
*/
public static final String CERTIFICATES_ATTR = "jakarta.servlet.request.X509Certificate";
/**
- * The request attribute under which we store the name of the cipher suite
- * being used on an SSL connection (as an object of type {@link String}).
+ * The request attribute under which we store the name of the cipher suite being used on an SSL connection (as an
+ * object of type {@link String}).
*/
public static final String CIPHER_SUITE_ATTR = "jakarta.servlet.request.cipher_suite";
/**
- * The request attribute under which we store the key size being used for
- * this SSL connection (as an object of type {@link Integer}).
+ * The request attribute under which we store the key size being used for this SSL connection (as an object of type
+ * {@link Integer}).
*/
public static final String KEY_SIZE_ATTR = "jakarta.servlet.request.key_size";
/**
- * The request attribute under which we store the session id being used
- * for this SSL connection (as an object of type {@link String}).
+ * The request attribute under which we store the session id being used for this SSL connection (as an object of
+ * type {@link String}).
*/
public static final String SSL_SESSION_ID_ATTR = "jakarta.servlet.request.ssl_session_id";
/**
- * The request attribute key for the session manager.
- * This one is a Tomcat extension to the Servlet spec.
+ * The request attribute key for the session manager. This one is a Tomcat extension to the Servlet spec.
*/
public static final String SSL_SESSION_MGR_ATTR = "jakarta.servlet.request.ssl_session_mgr";
@@ -184,39 +163,34 @@ public final class Globals {
// ------------------------------------------ ServletContext attribute names
/**
- * The servlet context attribute under which we store the alternate
- * deployment descriptor for this web application
+ * The servlet context attribute under which we store the alternate deployment descriptor for this web application
*/
public static final String ALT_DD_ATTR = "org.apache.catalina.deploy.alt_dd";
/**
- * The servlet context attribute under which we store the class path
- * for our application class loader (as an object of type String),
- * delimited with the appropriate path delimiter for this platform.
+ * The servlet context attribute under which we store the class path for our application class loader (as an object
+ * of type String), delimited with the appropriate path delimiter for this platform.
*/
- public static final String CLASS_PATH_ATTR = "org.apache.catalina.jsp_classpath";
+ public static final String CLASS_PATH_ATTR = "org.apache.catalina.jsp_classpath";
/**
- * Name of the ServletContext attribute under which we store the context
- * Realm's CredentialHandler (if both the Realm and the CredentialHandler
- * exist).
+ * Name of the ServletContext attribute under which we store the context Realm's CredentialHandler (if both the
+ * Realm and the CredentialHandler exist).
*/
public static final String CREDENTIAL_HANDLER = "org.apache.catalina.CredentialHandler";
/**
- * The WebResourceRoot which is associated with the context. This can be
- * used to manipulate static files.
+ * The WebResourceRoot which is associated with the context. This can be used to manipulate static files.
*/
public static final String RESOURCES_ATTR = "org.apache.catalina.resources";
/**
- * Name of the ServletContext attribute under which we store the web
- * application version string (the text that appears after ## when parallel
- * deployment is used).
+ * Name of the ServletContext attribute under which we store the web application version string (the text that
+ * appears after ## when parallel deployment is used).
*/
public static final String WEBAPP_VERSION = "org.apache.catalina.webappVersion";
@@ -224,8 +198,8 @@ public final class Globals {
// --------------------------- ServletContext initialisation parameter names
/**
- * Name of the ServletContext init-param that determines if the JSP engine
- * should validate *.tld files when parsing them.
+ * Name of the ServletContext init-param that determines if the JSP engine should validate *.tld files when parsing
+ * them.
* <p>
* This must be kept in sync with org.apache.jasper.Constants
*/
@@ -233,9 +207,8 @@ public final class Globals {
/**
- * Name of the ServletContext init-param that determines if the JSP engine
- * will block external entities from being used in *.tld, *.jspx, *.tagx and
- * tagplugin.xml files.
+ * Name of the ServletContext init-param that determines if the JSP engine will block external entities from being
+ * used in *.tld, *.jspx, *.tagx and tagplugin.xml files.
* <p>
* This must be kept in sync with org.apache.jasper.Constants
*/
@@ -245,15 +218,13 @@ public final class Globals {
// --------------------------------------------------- System property names
/**
- * Name of the system property containing
- * the tomcat product installation path
+ * Name of the system property containing the tomcat product installation path
*/
public static final String CATALINA_HOME_PROP = org.apache.catalina.startup.Constants.CATALINA_HOME_PROP;
/**
- * Name of the system property containing
- * the tomcat instance installation path
+ * Name of the system property containing the tomcat instance installation path
*/
public static final String CATALINA_BASE_PROP = org.apache.catalina.startup.Constants.CATALINA_BASE_PROP;
@@ -261,8 +232,8 @@ public final class Globals {
// -------------------------------------------------------- Global constants
/**
- * The flag which controls strict servlet specification compliance. Setting
- * this flag to {@code true} will change the defaults for other settings.
+ * The flag which controls strict servlet specification compliance. Setting this flag to {@code true} will change
+ * the defaults for other settings.
*/
public static final boolean STRICT_SERVLET_COMPLIANCE =
Boolean.getBoolean("org.apache.catalina.STRICT_SERVLET_COMPLIANCE");
diff --git a/java/org/apache/catalina/Group.java b/java/org/apache/catalina/Group.java
index 9cf329e58e..18a28399df 100644
--- a/java/org/apache/catalina/Group.java
+++ b/java/org/apache/catalina/Group.java
@@ -20,11 +20,13 @@ import java.security.Principal;
import java.util.Iterator;
/**
- * <p>Abstract representation of a group of {@link User}s in a
- * {@link UserDatabase}. Each user that is a member of this group
- * inherits the {@link Role}s assigned to the group.</p>
+ * <p>
+ * Abstract representation of a group of {@link User}s in a {@link UserDatabase}. Each user that is a member of this
+ * group inherits the {@link Role}s assigned to the group.
+ * </p>
*
* @author Craig R. McClanahan
+ *
* @since 4.1
*/
public interface Group extends Principal {
@@ -46,15 +48,13 @@ public interface Group extends Principal {
/**
- * @return the group name of this group, which must be unique
- * within the scope of a {@link UserDatabase}.
+ * @return the group name of this group, which must be unique within the scope of a {@link UserDatabase}.
*/
String getGroupname();
/**
- * Set the group name of this group, which must be unique
- * within the scope of a {@link UserDatabase}.
+ * Set the group name of this group, which must be unique within the scope of a {@link UserDatabase}.
*
* @param groupname The new group name
*/
@@ -94,8 +94,7 @@ public interface Group extends Principal {
*
* @param role The role to check
*
- * @return <code>true</code> if the group is assigned to the specified role
- * otherwise <code>false</code>
+ * @return <code>true</code> if the group is assigned to the specified role otherwise <code>false</code>
*/
boolean isInRole(Role role);
diff --git a/java/org/apache/catalina/Host.java b/java/org/apache/catalina/Host.java
index f9af68e9ae..d8ed79369e 100644
--- a/java/org/apache/catalina/Host.java
+++ b/java/org/apache/catalina/Host.java
@@ -22,24 +22,21 @@ import java.util.regex.Pattern;
/**
- * A <b>Host</b> is a Container that represents a virtual host in the
- * Catalina servlet engine. It is useful in the following types of scenarios:
+ * A <b>Host</b> is a Container that represents a virtual host in the Catalina servlet engine. It is useful in the
+ * following types of scenarios:
* <ul>
- * <li>You wish to use Interceptors that see every single request processed
- * by this particular virtual host.
- * <li>You wish to run Catalina in with a standalone HTTP connector, but still
- * want support for multiple virtual hosts.
+ * <li>You wish to use Interceptors that see every single request processed by this particular virtual host.
+ * <li>You wish to run Catalina in with a standalone HTTP connector, but still want support for multiple virtual hosts.
* </ul>
- * In general, you would not use a Host when deploying Catalina connected
- * to a web server (such as Apache), because the Connector will have
- * utilized the web server's facilities to determine which Context (or
- * perhaps even which Wrapper) should be utilized to process this request.
+ * In general, you would not use a Host when deploying Catalina connected to a web server (such as Apache), because the
+ * Connector will have utilized the web server's facilities to determine which Context (or perhaps even which Wrapper)
+ * should be utilized to process this request.
* <p>
- * The parent Container attached to a Host is generally an Engine, but may
- * be some other implementation, or may be omitted if it is not necessary.
+ * The parent Container attached to a Host is generally an Engine, but may be some other implementation, or may be
+ * omitted if it is not necessary.
* <p>
- * The child containers attached to a Host are generally implementations
- * of Context (representing an individual servlet context).
+ * The child containers attached to a Host are generally implementations of Context (representing an individual servlet
+ * context).
*
* @author Craig R. McClanahan
*/
@@ -50,15 +47,13 @@ public interface Host extends Container {
/**
- * The ContainerEvent event type sent when a new alias is added
- * by <code>addAlias()</code>.
+ * The ContainerEvent event type sent when a new alias is added by <code>addAlias()</code>.
*/
String ADD_ALIAS_EVENT = "addAlias";
/**
- * The ContainerEvent event type sent when an old alias is removed
- * by <code>removeAlias()</code>.
+ * The ContainerEvent event type sent when an old alias is removed by <code>removeAlias()</code>.
*/
String REMOVE_ALIAS_EVENT = "removeAlias";
@@ -67,46 +62,39 @@ public interface Host extends Container {
/**
- * @return the XML root for this Host. This can be an absolute
- * pathname or a relative pathname.
- * If null, the base path defaults to
- * ${catalina.base}/conf/<engine name>/<host name> directory
+ * @return the XML root for this Host. This can be an absolute pathname or a relative pathname. If null, the base
+ * path defaults to ${catalina.base}/conf/<engine name>/<host name> directory
*/
String getXmlBase();
/**
- * Set the Xml root for this Host. This can be an absolute
- * pathname or a relative pathname.
- * If null, the base path defaults to
- * ${catalina.base}/conf/<engine name>/<host name> directory
+ * Set the Xml root for this Host. This can be an absolute pathname or a relative pathname. If null, the base path
+ * defaults to ${catalina.base}/conf/<engine name>/<host name> directory
+ *
* @param xmlBase The new XML root
*/
void setXmlBase(String xmlBase);
/**
- * @return a default configuration path of this Host. The file will be
- * canonical if possible.
+ * @return a default configuration path of this Host. The file will be canonical if possible.
*/
File getConfigBaseFile();
/**
- * @return the application root for this Host. This can be an absolute
- * pathname, a relative pathname, or a URL.
+ * @return the application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.
*/
String getAppBase();
/**
- * @return an absolute {@link File} for the appBase of this Host. The file
- * will be canonical if possible. There is no guarantee that that the
- * appBase exists.
+ * @return an absolute {@link File} for the appBase of this Host. The file will be canonical if possible. There is
+ * no guarantee that that the appBase exists.
*/
File getAppBaseFile();
/**
- * Set the application root for this Host. This can be an absolute
- * pathname, a relative pathname, or a URL.
+ * Set the application root for this Host. This can be an absolute pathname, a relative pathname, or a URL.
*
* @param appBase The new application root
*/
@@ -114,23 +102,22 @@ public interface Host extends Container {
/**
- * @return the legacy (Java EE) application root for this Host. This can be
- * an absolute pathname, a relative pathname, or a URL.
+ * @return the legacy (Java EE) application root for this Host. This can be an absolute pathname, a relative
+ * pathname, or a URL.
*/
String getLegacyAppBase();
/**
- * @return an absolute {@link File} for the legacy (Java EE) appBase of this
- * Host. The file will be canonical if possible. There is no guarantee that
- * that the appBase exists.
+ * @return an absolute {@link File} for the legacy (Java EE) appBase of this Host. The file will be canonical if
+ * possible. There is no guarantee that that the appBase exists.
*/
File getLegacyAppBaseFile();
/**
- * Set the legacy (Java EE) application root for this Host. This can be an
- * absolute pathname, a relative pathname, or a URL.
+ * Set the legacy (Java EE) application root for this Host. This can be an absolute pathname, a relative pathname,
+ * or a URL.
*
* @param legacyAppBase The new legacy application root
*/
@@ -138,9 +125,8 @@ public interface Host extends Container {
/**
- * @return the value of the auto deploy flag. If true, it indicates that
- * this host's child webapps should be discovered and automatically
- * deployed dynamically.
+ * @return the value of the auto deploy flag. If true, it indicates that this host's child webapps should be
+ * discovered and automatically deployed dynamically.
*/
boolean getAutoDeploy();
@@ -154,15 +140,13 @@ public interface Host extends Container {
/**
- * @return the Java class name of the context configuration class
- * for new web applications.
+ * @return the Java class name of the context configuration class for new web applications.
*/
String getConfigClass();
/**
- * Set the Java class name of the context configuration class
- * for new web applications.
+ * Set the Java class name of the context configuration class for new web applications.
*
* @param configClass The new context configuration class
*/
@@ -170,9 +154,8 @@ public interface Host extends Container {
/**
- * @return the value of the deploy on startup flag. If true, it indicates
- * that this host's child webapps should be discovered and automatically
- * deployed.
+ * @return the value of the deploy on startup flag. If true, it indicates that this host's child webapps should be
+ * discovered and automatically deployed.
*/
boolean getDeployOnStartup();
@@ -186,25 +169,22 @@ public interface Host extends Container {
/**
- * @return the regular expression that defines the files and directories in
- * the host's appBase that will be ignored by the automatic deployment
- * process.
+ * @return the regular expression that defines the files and directories in the host's appBase that will be ignored
+ * by the automatic deployment process.
*/
String getDeployIgnore();
/**
- * @return the compiled regular expression that defines the files and
- * directories in the host's appBase that will be ignored by the automatic
- * deployment process.
+ * @return the compiled regular expression that defines the files and directories in the host's appBase that will be
+ * ignored by the automatic deployment process.
*/
Pattern getDeployIgnorePattern();
/**
- * Set the regular expression that defines the files and directories in
- * the host's appBase that will be ignored by the automatic deployment
- * process.
+ * Set the regular expression that defines the files and directories in the host's appBase that will be ignored by
+ * the automatic deployment process.
*
* @param deployIgnore A regular expression matching file names
*/
@@ -212,24 +192,23 @@ public interface Host extends Container {
/**
- * @return the executor that is used for starting and stopping contexts. This
- * is primarily for use by components deploying contexts that want to do
- * this in a multi-threaded manner.
+ * @return the executor that is used for starting and stopping contexts. This is primarily for use by components
+ * deploying contexts that want to do this in a multi-threaded manner.
*/
ExecutorService getStartStopExecutor();
/**
- * Returns <code>true</code> if the Host will attempt to create directories for appBase and xmlBase
- * unless they already exist.
+ * Returns <code>true</code> if the Host will attempt to create directories for appBase and xmlBase unless they
+ * already exist.
+ *
* @return true if the Host will attempt to create directories
*/
boolean getCreateDirs();
/**
- * Should the Host attempt to create directories for xmlBase and appBase
- * upon startup.
+ * Should the Host attempt to create directories for xmlBase and appBase upon startup.
*
* @param createDirs The new value for this flag
*/
@@ -237,17 +216,16 @@ public interface Host extends Container {
/**
- * @return <code>true</code> of the Host is configured to automatically undeploy old
- * versions of applications deployed using parallel deployment. This only
- * takes effect is {@link #getAutoDeploy()} also returns <code>true</code>.
+ * @return <code>true</code> of the Host is configured to automatically undeploy old versions of applications
+ * deployed using parallel deployment. This only takes effect is {@link #getAutoDeploy()} also returns
+ * <code>true</code>.
*/
boolean getUndeployOldVersions();
/**
- * Set to <code>true</code> if the Host should automatically undeploy old versions of
- * applications deployed using parallel deployment. This only takes effect
- * if {@link #getAutoDeploy()} returns <code>true</code>.
+ * Set to <code>true</code> if the Host should automatically undeploy old versions of applications deployed using
+ * parallel deployment. This only takes effect if {@link #getAutoDeploy()} returns <code>true</code>.
*
* @param undeployOldVersions The new value for this flag
*/
@@ -265,8 +243,7 @@ public interface Host extends Container {
/**
- * @return the set of alias names for this Host. If none are defined,
- * a zero length array is returned.
+ * @return the set of alias names for this Host. If none are defined, a zero length array is returned.
*/
String[] findAliases();
diff --git a/java/org/apache/catalina/JmxEnabled.java b/java/org/apache/catalina/JmxEnabled.java
index 2d514f4149..d79d2b3d4f 100644
--- a/java/org/apache/catalina/JmxEnabled.java
+++ b/java/org/apache/catalina/JmxEnabled.java
@@ -20,27 +20,23 @@ import javax.management.MBeanRegistration;
import javax.management.ObjectName;
/**
- * This interface is implemented by components that will be registered with an
- * MBean server when they are created and unregistered when they are destroyed.
- * It is primarily intended to be implemented by components that implement
+ * This interface is implemented by components that will be registered with an MBean server when they are created and
+ * unregistered when they are destroyed. It is primarily intended to be implemented by components that implement
* {@link Lifecycle} but is not exclusively for them.
*/
public interface JmxEnabled extends MBeanRegistration {
/**
- * @return the domain under which this component will be / has been
- * registered.
+ * @return the domain under which this component will be / has been registered.
*/
String getDomain();
/**
- * Specify the domain under which this component should be registered. Used
- * with components that cannot (easily) navigate the component hierarchy to
- * determine the correct domain to use.
+ * Specify the domain under which this component should be registered. Used with components that cannot (easily)
+ * navigate the component hierarchy to determine the correct domain to use.
*
- * @param domain The name of the domain under which this component should be
- * registered
+ * @param domain The name of the domain under which this component should be registered
*/
void setDomain(String domain);
diff --git a/java/org/apache/catalina/Lifecycle.java b/java/org/apache/catalina/Lifecycle.java
index 5095a596f4..58aa0eb1c0 100644
--- a/java/org/apache/catalina/Lifecycle.java
+++ b/java/org/apache/catalina/Lifecycle.java
@@ -18,13 +18,11 @@ package org.apache.catalina;
/**
- * Common interface for component life cycle methods. Catalina components
- * may implement this interface (as well as the appropriate interface(s) for
- * the functionality they support) in order to provide a consistent mechanism
- * to start and stop the component.
- * <br>
- * The valid state transitions for components that support {@link Lifecycle}
- * are:
+ * Common interface for component life cycle methods. Catalina components may implement this interface (as well as the
+ * appropriate interface(s) for the functionality they support) in order to provide a consistent mechanism to start and
+ * stop the component. <br>
+ * The valid state transitions for components that support {@link Lifecycle} are:
+ *
* <pre>
* start()
* -----------------------------
@@ -74,9 +72,9 @@ package org.apache.catalina;
* Attempting any other transition will throw {@link LifecycleException}.
*
* </pre>
- * The {@link LifecycleEvent}s fired during state changes are defined in the
- * methods that trigger the changed. No {@link LifecycleEvent}s are fired if the
- * attempted transition is not valid.
+ *
+ * The {@link LifecycleEvent}s fired during state changes are defined in the methods that trigger the changed. No
+ * {@link LifecycleEvent}s are fired if the attempted transition is not valid.
*
* @author Craig R. McClanahan
*/
@@ -153,18 +151,16 @@ public interface Lifecycle {
/**
- * The LifecycleEvent type for the "configure_start" event. Used by those
- * components that use a separate component to perform configuration and
- * need to signal when configuration should be performed - usually after
+ * The LifecycleEvent type for the "configure_start" event. Used by those components that use a separate component
+ * to perform configuration and need to signal when configuration should be performed - usually after
* {@link #BEFORE_START_EVENT} and before {@link #START_EVENT}.
*/
String CONFIGURE_START_EVENT = "configure_start";
/**
- * The LifecycleEvent type for the "configure_stop" event. Used by those
- * components that use a separate component to perform configuration and
- * need to signal when de-configuration should be performed - usually after
+ * The LifecycleEvent type for the "configure_stop" event. Used by those components that use a separate component to
+ * perform configuration and need to signal when de-configuration should be performed - usually after
* {@link #STOP_EVENT} and before {@link #AFTER_STOP_EVENT}.
*/
String CONFIGURE_STOP_EVENT = "configure_stop";
@@ -184,9 +180,8 @@ public interface Lifecycle {
/**
* Get the life cycle listeners associated with this life cycle.
*
- * @return An array containing the life cycle listeners associated with this
- * life cycle. If this component has no listeners registered, a
- * zero-length array is returned.
+ * @return An array containing the life cycle listeners associated with this life cycle. If this component has no
+ * listeners registered, a zero-length array is returned.
*/
LifecycleListener[] findLifecycleListeners();
@@ -200,91 +195,68 @@ public interface Lifecycle {
/**
- * Prepare the component for starting. This method should perform any
- * initialization required post object creation. The following
- * {@link LifecycleEvent}s will be fired in the following order:
+ * Prepare the component for starting. This method should perform any initialization required post object creation.
+ * The following {@link LifecycleEvent}s will be fired in the following order:
* <ol>
- * <li>INIT_EVENT: On the successful completion of component
- * initialization.</li>
+ * <li>INIT_EVENT: On the successful completion of component initialization.</li>
* </ol>
*
- * @exception LifecycleException if this component detects a fatal error
- * that prevents this component from being used
+ * @exception LifecycleException if this component detects a fatal error that prevents this component from being
+ * used
*/
void init() throws LifecycleException;
/**
- * Prepare for the beginning of active use of the public methods other than
- * property getters/setters and life cycle methods of this component. This
- * method should be called before any of the public methods other than
- * property getters/setters and life cycle methods of this component are
- * utilized. The following {@link LifecycleEvent}s will be fired in the
- * following order:
+ * Prepare for the beginning of active use of the public methods other than property getters/setters and life cycle
+ * methods of this component. This method should be called before any of the public methods other than property
+ * getters/setters and life cycle methods of this component are utilized. The following {@link LifecycleEvent}s will
+ * be fired in the following order:
* <ol>
- * <li>BEFORE_START_EVENT: At the beginning of the method. It is as this
- * point the state transitions to
- * {@link LifecycleState#STARTING_PREP}.</li>
- * <li>START_EVENT: During the method once it is safe to call start() for
- * any child components. It is at this point that the
- * state transitions to {@link LifecycleState#STARTING}
- * and that the public methods other than property
- * getters/setters and life cycle methods may be
- * used.</li>
- * <li>AFTER_START_EVENT: At the end of the method, immediately before it
- * returns. It is at this point that the state
- * transitions to {@link LifecycleState#STARTED}.
- * </li>
+ * <li>BEFORE_START_EVENT: At the beginning of the method. It is as this point the state transitions to
+ * {@link LifecycleState#STARTING_PREP}.</li>
+ * <li>START_EVENT: During the method once it is safe to call start() for any child components. It is at this point
+ * that the state transitions to {@link LifecycleState#STARTING} and that the public methods other than property
+ * getters/setters and life cycle methods may be used.</li>
+ * <li>AFTER_START_EVENT: At the end of the method, immediately before it returns. It is at this point that the
+ * state transitions to {@link LifecycleState#STARTED}.</li>
* </ol>
*
- * @exception LifecycleException if this component detects a fatal error
- * that prevents this component from being used
+ * @exception LifecycleException if this component detects a fatal error that prevents this component from being
+ * used
*/
void start() throws LifecycleException;
/**
- * Gracefully terminate the active use of the public methods other than
- * property getters/setters and life cycle methods of this component. Once
- * the STOP_EVENT is fired, the public methods other than property
- * getters/setters and life cycle methods should not be used. The following
- * {@link LifecycleEvent}s will be fired in the following order:
+ * Gracefully terminate the active use of the public methods other than property getters/setters and life cycle
+ * methods of this component. Once the STOP_EVENT is fired, the public methods other than property getters/setters
+ * and life cycle methods should not be used. The following {@link LifecycleEvent}s will be fired in the following
+ * order:
* <ol>
- * <li>BEFORE_STOP_EVENT: At the beginning of the method. It is at this
- * point that the state transitions to
- * {@link LifecycleState#STOPPING_PREP}.</li>
- * <li>STOP_EVENT: During the method once it is safe to call stop() for
- * any child components. It is at this point that the
- * state transitions to {@link LifecycleState#STOPPING}
- * and that the public methods other than property
- * getters/setters and life cycle methods may no longer be
- * used.</li>
- * <li>AFTER_STOP_EVENT: At the end of the method, immediately before it
- * returns. It is at this point that the state
- * transitions to {@link LifecycleState#STOPPED}.
- * </li>
+ * <li>BEFORE_STOP_EVENT: At the beginning of the method. It is at this point that the state transitions to
+ * {@link LifecycleState#STOPPING_PREP}.</li>
+ * <li>STOP_EVENT: During the method once it is safe to call stop() for any child components. It is at this point
+ * that the state transitions to {@link LifecycleState#STOPPING} and that the public methods other than property
+ * getters/setters and life cycle methods may no longer be used.</li>
+ * <li>AFTER_STOP_EVENT: At the end of the method, immediately before it returns. It is at this point that the state
+ * transitions to {@link LifecycleState#STOPPED}.</li>
* </ol>
+ * Note that if transitioning from {@link LifecycleState#FAILED} then the three events above will be fired but the
+ * component will transition directly from {@link LifecycleState#FAILED} to {@link LifecycleState#STOPPING},
+ * bypassing {@link LifecycleState#STOPPING_PREP}
*
- * Note that if transitioning from {@link LifecycleState#FAILED} then the
- * three events above will be fired but the component will transition
- * directly from {@link LifecycleState#FAILED} to
- * {@link LifecycleState#STOPPING}, bypassing
- * {@link LifecycleState#STOPPING_PREP}
- *
- * @exception LifecycleException if this component detects a fatal error
- * that needs to be reported
+ * @exception LifecycleException if this component detects a fatal error that needs to be reported
*/
void stop() throws LifecycleException;
/**
- * Prepare to discard the object. The following {@link LifecycleEvent}s will
- * be fired in the following order:
+ * Prepare to discard the object. The following {@link LifecycleEvent}s will be fired in the following order:
* <ol>
- * <li>DESTROY_EVENT: On the successful completion of component
- * destruction.</li>
+ * <li>DESTROY_EVENT: On the successful completion of component destruction.</li>
* </ol>
*
- * @exception LifecycleException if this component detects a fatal error
- * that prevents this component from being used
+ * @exception LifecycleException if this component detects a fatal error that prevents this component from being
+ * used
*/
void destroy() throws LifecycleException;
@@ -298,10 +270,9 @@ public interface Lifecycle {
/**
- * Obtain a textual representation of the current component state. Useful
- * for JMX. The format of this string may vary between point releases and
- * should not be relied upon to determine component state. To determine
- * component state, use {@link #getState()}.
+ * Obtain a textual representation of the current component state. Useful for JMX. The format of this string may
+ * vary between point releases and should not be relied upon to determine component state. To determine component
+ * state, use {@link #getState()}.
*
* @return The name of the current component state.
*/
@@ -309,10 +280,8 @@ public interface Lifecycle {
/**
- * Marker interface used to indicate that the instance should only be used
- * once. Calling {@link #stop()} on an instance that supports this interface
- * will automatically call {@link #destroy()} after {@link #stop()}
- * completes.
+ * Marker interface used to indicate that the instance should only be used once. Calling {@link #stop()} on an
+ * instance that supports this interface will automatically call {@link #destroy()} after {@link #stop()} completes.
*/
interface SingleUse {
}
diff --git a/java/org/apache/catalina/LifecycleEvent.java b/java/org/apache/catalina/LifecycleEvent.java
index c681586114..b914542db0 100644
--- a/java/org/apache/catalina/LifecycleEvent.java
+++ b/java/org/apache/catalina/LifecycleEvent.java
@@ -19,8 +19,7 @@ package org.apache.catalina;
import java.util.EventObject;
/**
- * General event for notifying listeners of significant changes on a component
- * that implements the Lifecycle interface.
+ * General event for notifying listeners of significant changes on a component that implements the Lifecycle interface.
*
* @author Craig R. McClanahan
*/
@@ -33,8 +32,8 @@ public final class LifecycleEvent extends EventObject {
* Construct a new LifecycleEvent with the specified parameters.
*
* @param lifecycle Component on which this event occurred
- * @param type Event type (required)
- * @param data Event data (if any)
+ * @param type Event type (required)
+ * @param data Event data (if any)
*/
public LifecycleEvent(Lifecycle lifecycle, String type, Object data) {
super(lifecycle);
diff --git a/java/org/apache/catalina/LifecycleException.java b/java/org/apache/catalina/LifecycleException.java
index cfd8e49744..5ff67eea8f 100644
--- a/java/org/apache/catalina/LifecycleException.java
+++ b/java/org/apache/catalina/LifecycleException.java
@@ -18,9 +18,8 @@ package org.apache.catalina;
/**
- * General purpose exception that is thrown to indicate a lifecycle related
- * problem. Such exceptions should generally be considered fatal to the
- * operation of the application containing this component.
+ * General purpose exception that is thrown to indicate a lifecycle related problem. Such exceptions should generally be
+ * considered fatal to the operation of the application containing this component.
*
* @author Craig R. McClanahan
*/
@@ -28,7 +27,7 @@ public final class LifecycleException extends Exception {
private static final long serialVersionUID = 1L;
- //------------------------------------------------------------ Constructors
+ // ------------------------------------------------------------ Constructors
/**
@@ -60,10 +59,9 @@ public final class LifecycleException extends Exception {
/**
- * Construct a new LifecycleException for the specified message
- * and throwable.
+ * Construct a new LifecycleException for the specified message and throwable.
*
- * @param message Message describing this exception
+ * @param message Message describing this exception
* @param throwable Throwable that caused this exception
*/
public LifecycleException(String message, Throwable throwable) {
diff --git a/java/org/apache/catalina/LifecycleListener.java b/java/org/apache/catalina/LifecycleListener.java
index 0efe7eae46..50f38b16bc 100644
--- a/java/org/apache/catalina/LifecycleListener.java
+++ b/java/org/apache/catalina/LifecycleListener.java
@@ -18,10 +18,9 @@ package org.apache.catalina;
/**
- * Interface defining a listener for significant events (including "component
- * start" and "component stop" generated by a component that implements the
- * Lifecycle interface. The listener will be fired after the associated state
- * change has taken place.
+ * Interface defining a listener for significant events (including "component start" and "component stop" generated by a
+ * component that implements the Lifecycle interface. The listener will be fired after the associated state change has
+ * taken place.
*
* @author Craig R. McClanahan
*/
diff --git a/java/org/apache/catalina/LifecycleState.java b/java/org/apache/catalina/LifecycleState.java
index 717e58792f..ec0fd2d10e 100644
--- a/java/org/apache/catalina/LifecycleState.java
+++ b/java/org/apache/catalina/LifecycleState.java
@@ -17,8 +17,8 @@
package org.apache.catalina;
/**
- * The list of valid states for components that implement {@link Lifecycle}.
- * See {@link Lifecycle} for the state transition diagram.
+ * The list of valid states for components that implement {@link Lifecycle}. See {@link Lifecycle} for the state
+ * transition diagram.
*/
public enum LifecycleState {
NEW(false, null),
@@ -43,17 +43,15 @@ public enum LifecycleState {
}
/**
- * May the public methods other than property getters/setters and lifecycle
- * methods be called for a component in this state? It returns
- * <code>true</code> for any component in any of the following states:
+ * May the public methods other than property getters/setters and lifecycle methods be called for a component in
+ * this state? It returns <code>true</code> for any component in any of the following states:
* <ul>
* <li>{@link #STARTING}</li>
* <li>{@link #STARTED}</li>
* <li>{@link #STOPPING_PREP}</li>
* </ul>
*
- * @return <code>true</code> if the component is available for use,
- * otherwise <code>false</code>
+ * @return <code>true</code> if the component is available for use, otherwise <code>false</code>
*/
public boolean isAvailable() {
return available;
diff --git a/java/org/apache/catalina/Loader.java b/java/org/apache/catalina/Loader.java
index 6f7552aee6..75b21c476a 100644
--- a/java/org/apache/catalina/Loader.java
+++ b/java/org/apache/catalina/Loader.java
@@ -19,30 +19,21 @@ package org.apache.catalina;
import java.beans.PropertyChangeListener;
/**
- * A <b>Loader</b> represents a Java ClassLoader implementation that can
- * be used by a Container to load class files (within a repository associated
- * with the Loader) that are designed to be reloaded upon request, as well as
- * a mechanism to detect whether changes have occurred in the underlying
- * repository.
+ * A <b>Loader</b> represents a Java ClassLoader implementation that can be used by a Container to load class files
+ * (within a repository associated with the Loader) that are designed to be reloaded upon request, as well as a
+ * mechanism to detect whether changes have occurred in the underlying repository.
* <p>
- * In order for a <code>Loader</code> implementation to successfully operate
- * with a <code>Context</code> implementation that implements reloading, it
- * must obey the following constraints:
+ * In order for a <code>Loader</code> implementation to successfully operate with a <code>Context</code> implementation
+ * that implements reloading, it must obey the following constraints:
* <ul>
- * <li>Must implement <code>Lifecycle</code> so that the Context can indicate
- * that a new class loader is required.
- * <li>The <code>start()</code> method must unconditionally create a new
- * <code>ClassLoader</code> implementation.
- * <li>The <code>stop()</code> method must throw away its reference to the
- * <code>ClassLoader</code> previously utilized, so that the class loader,
- * all classes loaded by it, and all objects of those classes, can be
- * garbage collected.
- * <li>Must allow a call to <code>stop()</code> to be followed by a call to
- * <code>start()</code> on the same <code>Loader</code> instance.
- * <li>Based on a policy chosen by the implementation, must call the
- * <code>Context.reload()</code> method on the owning <code>Context</code>
- * when a change to one or more of the class files loaded by this class
- * loader is detected.
+ * <li>Must implement <code>Lifecycle</code> so that the Context can indicate that a new class loader is required.
+ * <li>The <code>start()</code> method must unconditionally create a new <code>ClassLoader</code> implementation.
+ * <li>The <code>stop()</code> method must throw away its reference to the <code>ClassLoader</code> previously utilized,
+ * so that the class loader, all classes loaded by it, and all objects of those classes, can be garbage collected.
+ * <li>Must allow a call to <code>stop()</code> to be followed by a call to <code>start()</code> on the same
+ * <code>Loader</code> instance.
+ * <li>Based on a policy chosen by the implementation, must call the <code>Context.reload()</code> method on the owning
+ * <code>Context</code> when a change to one or more of the class files loaded by this class loader is detected.
* </ul>
*
* @author Craig R. McClanahan
@@ -51,9 +42,8 @@ public interface Loader {
/**
- * Execute a periodic task, such as reloading, etc. This method will be
- * invoked inside the classloading context of this container. Unexpected
- * throwables will be caught and logged.
+ * Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of
+ * this container. Unexpected throwables will be caught and logged.
*/
void backgroundProcess();
@@ -79,15 +69,13 @@ public interface Loader {
/**
- * @return the "follow standard delegation model" flag used to configure
- * our ClassLoader.
+ * @return the "follow standard delegation model" flag used to configure our ClassLoader.
*/
boolean getDelegate();
/**
- * Set the "follow standard delegation model" flag used to configure
- * our ClassLoader.
+ * Set the "follow standard delegation model" flag used to configure our ClassLoader.
*
* @param delegate The new flag
*/
@@ -103,11 +91,10 @@ public interface Loader {
/**
- * Has the internal repository associated with this Loader been modified,
- * such that the loaded classes should be reloaded?
+ * Has the internal repository associated with this Loader been modified, such that the loaded classes should be
+ * reloaded?
*
- * @return <code>true</code> when the repository has been modified,
- * <code>false</code> otherwise
+ * @return <code>true</code> when the repository has been modified, <code>false</code> otherwise
*/
boolean modified();
diff --git a/java/org/apache/catalina/Manager.java b/java/org/apache/catalina/Manager.java
index b8438b1150..60b260bd33 100644
--- a/java/org/apache/catalina/Manager.java
+++ b/java/org/apache/catalina/Manager.java
@@ -20,19 +20,16 @@ import java.beans.PropertyChangeListener;
import java.io.IOException;
/**
- * A <b>Manager</b> manages the pool of Sessions that are associated with a
- * particular Context. Different Manager implementations may support
- * value-added features such as the persistent storage of session data,
- * as well as migrating sessions for distributable web applications.
+ * A <b>Manager</b> manages the pool of Sessions that are associated with a particular Context. Different Manager
+ * implementations may support value-added features such as the persistent storage of session data, as well as migrating
+ * sessions for distributable web applications.
* <p>
- * In order for a <code>Manager</code> implementation to successfully operate
- * with a <code>Context</code> implementation that implements reloading, it
- * must obey the following constraints:
+ * In order for a <code>Manager</code> implementation to successfully operate with a <code>Context</code> implementation
+ * that implements reloading, it must obey the following constraints:
* <ul>
- * <li>Must implement <code>Lifecycle</code> so that the Context can indicate
- * that a restart is required.
- * <li>Must allow a call to <code>stop()</code> to be followed by a call to
- * <code>start()</code> on the same <code>Manager</code> instance.
+ * <li>Must implement <code>Lifecycle</code> so that the Context can indicate that a restart is required.
+ * <li>Must allow a call to <code>stop()</code> to be followed by a call to <code>start()</code> on the same
+ * <code>Manager</code> instance.
* </ul>
*
* @author Craig R. McClanahan
@@ -50,11 +47,10 @@ public interface Manager {
/**
- * Set the Context with which this Manager is associated. The Context must
- * be set to a non-null value before the Manager is first used. Multiple
- * calls to this method before first use are permitted. Once the Manager has
- * been used, this method may not be used to change the Context (including
- * setting a {@code null} value) that the Manager is associated with.
+ * Set the Context with which this Manager is associated. The Context must be set to a non-null value before the
+ * Manager is first used. Multiple calls to this method before first use are permitted. Once the Manager has been
+ * used, this method may not be used to change the Context (including setting a {@code null} value) that the Manager
+ * is associated with.
*
* @param context The newly associated Context
*/
@@ -76,9 +72,8 @@ public interface Manager {
/**
- * Returns the total number of sessions created by this manager, which is
- * approximated as the number of active sessions plus the number of
- * expired sessions.
+ * Returns the total number of sessions created by this manager, which is approximated as the number of active
+ * sessions plus the number of expired sessions.
*
* @return Total number of sessions created by this manager.
*/
@@ -89,6 +84,7 @@ public interface Manager {
* Sets the total number of sessions created by this manager.
*
* @param sessionCounter Total number of sessions created by this manager.
+ *
* @deprecated This will be removed in Tomcat 11
*/
@Deprecated
@@ -96,21 +92,17 @@ public interface Manager {
/**
- * Gets the maximum number of sessions that have been active at the same
- * time.
+ * Gets the maximum number of sessions that have been active at the same time.
*
- * @return Maximum number of sessions that have been active at the same
- * time
+ * @return Maximum number of sessions that have been active at the same time
*/
int getMaxActive();
/**
- * (Re)sets the maximum number of sessions that have been active at the
- * same time.
+ * (Re)sets the maximum number of sessions that have been active at the same time.
*
- * @param maxActive Maximum number of sessions that have been active at
- * the same time.
+ * @param maxActive Maximum number of sessions that have been active at the same time.
*/
void setMaxActive(int maxActive);
@@ -140,8 +132,7 @@ public interface Manager {
/**
- * Gets the number of sessions that were not created because the maximum
- * number of active sessions was reached.
+ * Gets the number of sessions that were not created because the maximum number of active sessions was reached.
*
* @return Number of rejected sessions
*/
@@ -149,49 +140,41 @@ public interface Manager {
/**
- * Gets the longest time (in seconds) that an expired session had been
- * alive.
+ * Gets the longest time (in seconds) that an expired session had been alive.
*
- * @return Longest time (in seconds) that an expired session had been
- * alive.
+ * @return Longest time (in seconds) that an expired session had been alive.
*/
int getSessionMaxAliveTime();
/**
- * Sets the longest time (in seconds) that an expired session had been
- * alive.
+ * Sets the longest time (in seconds) that an expired session had been alive.
*
- * @param sessionMaxAliveTime Longest time (in seconds) that an expired
- * session had been alive.
+ * @param sessionMaxAliveTime Longest time (in seconds) that an expired session had been alive.
*/
void setSessionMaxAliveTime(int sessionMaxAliveTime);
/**
- * Gets the average time (in seconds) that expired sessions had been
- * alive. This may be based on sample data.
+ * Gets the average time (in seconds) that expired sessions had been alive. This may be based on sample data.
*
- * @return Average time (in seconds) that expired sessions had been
- * alive.
+ * @return Average time (in seconds) that expired sessions had been alive.
*/
int getSessionAverageAliveTime();
/**
- * Gets the current rate of session creation (in session per minute). This
- * may be based on sample data.
+ * Gets the current rate of session creation (in session per minute). This may be based on sample data.
*
- * @return The current rate (in sessions per minute) of session creation
+ * @return The current rate (in sessions per minute) of session creation
*/
int getSessionCreateRate();
/**
- * Gets the current rate of session expiration (in session per minute). This
- * may be based on sample data
+ * Gets the current rate of session expiration (in session per minute). This may be based on sample data
*
- * @return The current rate (in sessions per minute) of session expiration
+ * @return The current rate (in sessions per minute) of session expiration
*/
int getSessionExpireRate();
@@ -215,12 +198,11 @@ public interface Manager {
/**
- * Change the session ID of the current session to a new randomly generated
- * session ID.
+ * Change the session ID of the current session to a new randomly generated session ID.
*
- * @param session The session to change the session ID for
+ * @param session The session to change the session ID for
*
- * @return The new session ID
+ * @return The new session ID
*/
default String rotateSessionId(Session session) {
String newSessionId = null;
@@ -246,16 +228,15 @@ public interface Manager {
/**
* Change the session ID of the current session to a specified session ID.
*
- * @param session The session to change the session ID for
+ * @param session The session to change the session ID for
* @param newId new session ID
*/
void changeSessionId(Session session, String newId);
/**
- * Get a session from the recycled ones or create a new empty one.
- * The PersistentManager manager does not need to create session data
- * because it reads it from the Store.
+ * Get a session from the recycled ones or create a new empty one. The PersistentManager manager does not need to
+ * create session data because it reads it from the Store.
*
* @return An empty Session object
*/
@@ -263,45 +244,38 @@ public interface Manager {
/**
- * Construct and return a new session object, based on the default
- * settings specified by this Manager's properties. The session
- * id specified will be used as the session id.
- * If a new session cannot be created for any reason, return
- * <code>null</code>.
+ * Construct and return a new session object, based on the default settings specified by this Manager's properties.
+ * The session id specified will be used as the session id. If a new session cannot be created for any reason,
+ * return <code>null</code>.
+ *
+ * @param sessionId The session id which should be used to create the new session; if <code>null</code>, the session
+ * id will be assigned by this method, and available via the getId() method of the returned
+ * session.
*
- * @param sessionId The session id which should be used to create the
- * new session; if <code>null</code>, the session
- * id will be assigned by this method, and available via the getId()
- * method of the returned session.
- * @exception IllegalStateException if a new session cannot be
- * instantiated for any reason
+ * @exception IllegalStateException if a new session cannot be instantiated for any reason
*
- * @return An empty Session object with the given ID or a newly created
- * session ID if none was specified
+ * @return An empty Session object with the given ID or a newly created session ID if none was specified
*/
Session createSession(String sessionId);
/**
- * Return the active Session, associated with this Manager, with the
- * specified session id (if any); otherwise return <code>null</code>.
+ * Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return
+ * <code>null</code>.
*
* @param id The session id for the session to be returned
*
- * @exception IllegalStateException if a new session cannot be
- * instantiated for any reason
- * @exception IOException if an input/output error occurs while
- * processing this request
+ * @exception IllegalStateException if a new session cannot be instantiated for any reason
+ * @exception IOException if an input/output error occurs while processing this request
*
- * @return the request session or {@code null} if a session with the
- * requested ID could not be found
+ * @return the request session or {@code null} if a session with the requested ID could not be found
*/
Session findSession(String id) throws IOException;
/**
- * Return the set of active Sessions associated with this Manager.
- * If this Manager has no active Sessions, a zero-length array is returned.
+ * Return the set of active Sessions associated with this Manager. If this Manager has no active Sessions, a
+ * zero-length array is returned.
*
* @return All the currently active sessions managed by this manager
*/
@@ -309,13 +283,11 @@ public interface Manager {
/**
- * Load any currently active sessions that were previously unloaded
- * to the appropriate persistence mechanism, if any. If persistence is not
- * supported, this method returns without doing anything.
+ * Load any currently active sessions that were previously unloaded to the appropriate persistence mechanism, if
+ * any. If persistence is not supported, this method returns without doing anything.
*
- * @exception ClassNotFoundException if a serialized class cannot be
- * found during the reload
- * @exception IOException if an input/output error occurs
+ * @exception ClassNotFoundException if a serialized class cannot be found during the reload
+ * @exception IOException if an input/output error occurs
*/
void load() throws ClassNotFoundException, IOException;
@@ -331,8 +303,8 @@ public interface Manager {
/**
* Remove this Session from the active Sessions for this Manager.
*
- * @param session Session to be removed
- * @param update Should the expiration statistics be updated
+ * @param session Session to be removed
+ * @param update Should the expiration statistics be updated
*/
void remove(Session session, boolean update);
@@ -346,9 +318,8 @@ public interface Manager {
/**
- * Save any currently active sessions in the appropriate persistence
- * mechanism, if any. If persistence is not supported, this method
- * returns without doing anything.
+ * Save any currently active sessions in the appropriate persistence mechanism, if any. If persistence is not
+ * supported, this method returns without doing anything.
*
* @exception IOException if an input/output error occurs
*/
@@ -356,39 +327,34 @@ public interface Manager {
/**
- * This method will be invoked by the context/container on a periodic
- * basis and allows the manager to implement
- * a method that executes periodic tasks, such as expiring sessions etc.
+ * This method will be invoked by the context/container on a periodic basis and allows the manager to implement a
+ * method that executes periodic tasks, such as expiring sessions etc.
*/
void backgroundProcess();
/**
- * Would the Manager distribute the given session attribute? Manager
- * implementations may provide additional configuration options to control
- * which attributes are distributable.
+ * Would the Manager distribute the given session attribute? Manager implementations may provide additional
+ * configuration options to control which attributes are distributable.
*
* @param name The attribute name
* @param value The attribute value
*
- * @return {@code true} if the Manager would distribute the given attribute
- * otherwise {@code false}
+ * @return {@code true} if the Manager would distribute the given attribute otherwise {@code false}
*/
boolean willAttributeDistribute(String name, Object value);
/**
- * When an attribute that is already present in the session is added again
- * under the same name and the attribute implements {@link
- * jakarta.servlet.http.HttpSessionBindingListener}, should
+ * When an attribute that is already present in the session is added again under the same name and the attribute
+ * implements {@link jakarta.servlet.http.HttpSessionBindingListener}, should
* {@link jakarta.servlet.http.HttpSessionBindingListener#valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent)}
* be called followed by
* {@link jakarta.servlet.http.HttpSessionBindingListener#valueBound(jakarta.servlet.http.HttpSessionBindingEvent)}?
* <p>
* The default value is {@code false}.
*
- * @return {@code true} if the listener will be notified, {@code false} if
- * it will not
+ * @return {@code true} if the listener will be notified, {@code false} if it will not
*/
default boolean getNotifyBindingListenerOnUnchangedValue() {
return false;
@@ -400,30 +366,24 @@ public interface Manager {
* {@link jakarta.servlet.http.HttpSessionBindingListener#valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent)}
* be called followed by
* {@link jakarta.servlet.http.HttpSessionBindingListener#valueBound(jakarta.servlet.http.HttpSessionBindingEvent)}
- * when an attribute that is already present in the session is added again
- * under the same name and the attribute implements {@link
- * jakarta.servlet.http.HttpSessionBindingListener}.
+ * when an attribute that is already present in the session is added again under the same name and the attribute
+ * implements {@link jakarta.servlet.http.HttpSessionBindingListener}.
*
- * @param notifyBindingListenerOnUnchangedValue {@code true} the listener
- * will be called, {@code
+ * @param notifyBindingListenerOnUnchangedValue {@code true} the listener will be called, {@code
* false} it will not
*/
- void setNotifyBindingListenerOnUnchangedValue(
- boolean notifyBindingListenerOnUnchangedValue);
+ void setNotifyBindingListenerOnUnchangedValue(boolean notifyBindingListenerOnUnchangedValue);
/**
- * When an attribute that is already present in the session is added again
- * under the same name and a {@link
- * jakarta.servlet.http.HttpSessionAttributeListener} is configured for the
- * session should
+ * When an attribute that is already present in the session is added again under the same name and a
+ * {@link jakarta.servlet.http.HttpSessionAttributeListener} is configured for the session should
* {@link jakarta.servlet.http.HttpSessionAttributeListener#attributeReplaced(jakarta.servlet.http.HttpSessionBindingEvent)}
* be called?
* <p>
* The default value is {@code true}.
*
- * @return {@code true} if the listener will be notified, {@code false} if
- * it will not
+ * @return {@code true} if the listener will be notified, {@code false} if it will not
*/
default boolean getNotifyAttributeListenerOnUnchangedValue() {
return true;
@@ -433,26 +393,21 @@ public interface Manager {
/**
* Configure if
* {@link jakarta.servlet.http.HttpSessionAttributeListener#attributeReplaced(jakarta.servlet.http.HttpSessionBindingEvent)}
- * when an attribute that is already present in the session is added again
- * under the same name and a {@link
- * jakarta.servlet.http.HttpSessionAttributeListener} is configured for the
- * session.
+ * when an attribute that is already present in the session is added again under the same name and a
+ * {@link jakarta.servlet.http.HttpSessionAttributeListener} is configured for the session.
*
- * @param notifyAttributeListenerOnUnchangedValue {@code true} the listener
- * will be called, {@code
+ * @param notifyAttributeListenerOnUnchangedValue {@code true} the listener will be called, {@code
* false} it will not
*/
- void setNotifyAttributeListenerOnUnchangedValue(
- boolean notifyAttributeListenerOnUnchangedValue);
+ void setNotifyAttributeListenerOnUnchangedValue(boolean notifyAttributeListenerOnUnchangedValue);
/**
- * If this is <code>true</code>, Tomcat will track the number of active
- * requests for each session. When determining if a session is valid, any
- * session with at least one active request will always be considered valid.
- * If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
- * <code>true</code>, the default of this setting will be <code>true</code>,
- * else the default value will be <code>false</code>.
+ * If this is <code>true</code>, Tomcat will track the number of active requests for each session. When determining
+ * if a session is valid, any session with at least one active request will always be considered valid. If
+ * <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to <code>true</code>, the default of this
+ * setting will be <code>true</code>, else the default value will be <code>false</code>.
+ *
* @return the flag value
*/
default boolean getSessionActivityCheck() {
@@ -461,23 +416,21 @@ public interface Manager {
/**
- * Configure if Tomcat will track the number of active requests for each
- * session. When determining if a session is valid, any session with at
- * least one active request will always be considered valid.
+ * Configure if Tomcat will track the number of active requests for each session. When determining if a session is
+ * valid, any session with at least one active request will always be considered valid.
+ *
* @param sessionActivityCheck the new flag value
*/
void setSessionActivityCheck(boolean sessionActivityCheck);
/**
- * If this is <code>true</code>, the last accessed time for sessions will
- * be calculated from the beginning of the previous request. If
- * <code>false</code>, the last accessed time for sessions will be calculated
- * from the end of the previous request. This also affects how the idle time
- * is calculated.
- * If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
- * <code>true</code>, the default of this setting will be <code>true</code>,
- * else the default value will be <code>false</code>.
+ * If this is <code>true</code>, the last accessed time for sessions will be calculated from the beginning of the
+ * previous request. If <code>false</code>, the last accessed time for sessions will be calculated from the end of
+ * the previous request. This also affects how the idle time is calculated. If
+ * <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to <code>true</code>, the default of this
+ * setting will be <code>true</code>, else the default value will be <code>false</code>.
+ *
* @return the flag value
*/
default boolean getSessionLastAccessAtStart() {
@@ -486,11 +439,10 @@ public interface Manager {
/**
- * Configure if the last accessed time for sessions will
- * be calculated from the beginning of the previous request. If
- * <code>false</code>, the last accessed time for sessions will be calculated
- * from the end of the previous request. This also affects how the idle time
- * is calculated.
+ * Configure if the last accessed time for sessions will be calculated from the beginning of the previous request.
+ * If <code>false</code>, the last accessed time for sessions will be calculated from the end of the previous
+ * request. This also affects how the idle time is calculated.
+ *
* @param sessionLastAccessAtStart the new flag value
*/
void setSessionLastAccessAtStart(boolean sessionLastAccessAtStart);
diff --git a/java/org/apache/catalina/Pipeline.java b/java/org/apache/catalina/Pipeline.java
index 67ce9540cc..57afd26ac8 100644
--- a/java/org/apache/catalina/Pipeline.java
+++ b/java/org/apache/catalina/Pipeline.java
@@ -19,19 +19,18 @@ package org.apache.catalina;
import java.util.Set;
/**
- * <p>Interface describing a collection of Valves that should be executed
- * in sequence when the <code>invoke()</code> method is invoked. It is
- * required that a Valve somewhere in the pipeline (usually the last one)
- * must process the request and create the corresponding response, rather
- * than trying to pass the request on.</p>
- *
- * <p>There is generally a single Pipeline instance associated with each
- * Container. The container's normal request processing functionality is
- * generally encapsulated in a container-specific Valve, which should always
- * be executed at the end of a pipeline. To facilitate this, the
- * <code>setBasic()</code> method is provided to set the Valve instance that
- * will always be executed last. Other Valves will be executed in the order
- * that they were added, before the basic Valve is executed.</p>
+ * <p>
+ * Interface describing a collection of Valves that should be executed in sequence when the <code>invoke()</code> method
+ * is invoked. It is required that a Valve somewhere in the pipeline (usually the last one) must process the request and
+ * create the corresponding response, rather than trying to pass the request on.
+ * </p>
+ * <p>
+ * There is generally a single Pipeline instance associated with each Container. The container's normal request
+ * processing functionality is generally encapsulated in a container-specific Valve, which should always be executed at
+ * the end of a pipeline. To facilitate this, the <code>setBasic()</code> method is provided to set the Valve instance
+ * that will always be executed last. Other Valves will be executed in the order that they were added, before the basic
+ * Valve is executed.
+ * </p>
*
* @author Craig R. McClanahan
* @author Peter Donald
@@ -39,21 +38,19 @@ import java.util.Set;
public interface Pipeline extends Contained {
/**
- * @return the Valve instance that has been distinguished as the basic
- * Valve for this Pipeline (if any).
+ * @return the Valve instance that has been distinguished as the basic Valve for this Pipeline (if any).
*/
Valve getBasic();
/**
- * <p>Set the Valve instance that has been distinguished as the basic
- * Valve for this Pipeline (if any). Prior to setting the basic Valve,
- * the Valve's <code>setContainer()</code> will be called, if it
- * implements <code>Contained</code>, with the owning Container as an
- * argument. The method may throw an <code>IllegalArgumentException</code>
- * if this Valve chooses not to be associated with this Container, or
- * <code>IllegalStateException</code> if it is already associated with
- * a different Container.</p>
+ * <p>
+ * Set the Valve instance that has been distinguished as the basic Valve for this Pipeline (if any). Prior to
+ * setting the basic Valve, the Valve's <code>setContainer()</code> will be called, if it implements
+ * <code>Contained</code>, with the owning Container as an argument. The method may throw an
+ * <code>IllegalArgumentException</code> if this Valve chooses not to be associated with this Container, or
+ * <code>IllegalStateException</code> if it is already associated with a different Container.
+ * </p>
*
* @param valve Valve to be distinguished as the basic Valve
*/
@@ -61,48 +58,42 @@ public interface Pipeline extends Contained {
/**
- * <p>Add a new Valve to the end of the pipeline associated with this
- * Container. Prior to adding the Valve, the Valve's
- * <code>setContainer()</code> method will be called, if it implements
- * <code>Contained</code>, with the owning Container as an argument.
- * The method may throw an
- * <code>IllegalArgumentException</code> if this Valve chooses not to
- * be associated with this Container, or <code>IllegalStateException</code>
- * if it is already associated with a different Container.</p>
- *
- * <p>Implementation note: Implementations are expected to trigger the
- * {@link Container#ADD_VALVE_EVENT} for the associated container if this
- * call is successful.</p>
+ * <p>
+ * Add a new Valve to the end of the pipeline associated with this Container. Prior to adding the Valve, the Valve's
+ * <code>setContainer()</code> method will be called, if it implements <code>Contained</code>, with the owning
+ * Container as an argument. The method may throw an <code>IllegalArgumentException</code> if this Valve chooses not
+ * to be associated with this Container, or <code>IllegalStateException</code> if it is already associated with a
+ * different Container.
+ * </p>
+ * <p>
+ * Implementation note: Implementations are expected to trigger the {@link Container#ADD_VALVE_EVENT} for the
+ * associated container if this call is successful.
+ * </p>
*
* @param valve Valve to be added
*
- * @exception IllegalArgumentException if this Container refused to
- * accept the specified Valve
- * @exception IllegalArgumentException if the specified Valve refuses to be
- * associated with this Container
- * @exception IllegalStateException if the specified Valve is already
- * associated with a different Container
+ * @exception IllegalArgumentException if this Container refused to accept the specified Valve
+ * @exception IllegalArgumentException if the specified Valve refuses to be associated with this Container
+ * @exception IllegalStateException if the specified Valve is already associated with a different Container
*/
void addValve(Valve valve);
/**
- * @return the set of Valves in the pipeline associated with this
- * Container, including the basic Valve (if any). If there are no
- * such Valves, a zero-length array is returned.
+ * @return the set of Valves in the pipeline associated with this Container, including the basic Valve (if any). If
+ * there are no such Valves, a zero-length array is returned.
*/
Valve[] getValves();
/**
- * Remove the specified Valve from the pipeline associated with this
- * Container, if it is found; otherwise, do nothing. If the Valve is
- * found and removed, the Valve's <code>setContainer(null)</code> method
- * will be called if it implements <code>Contained</code>.
- *
- * <p>Implementation note: Implementations are expected to trigger the
- * {@link Container#REMOVE_VALVE_EVENT} for the associated container if this
- * call is successful.</p>
+ * Remove the specified Valve from the pipeline associated with this Container, if it is found; otherwise, do
+ * nothing. If the Valve is found and removed, the Valve's <code>setContainer(null)</code> method will be called if
+ * it implements <code>Contained</code>.
+ * <p>
+ * Implementation note: Implementations are expected to trigger the {@link Container#REMOVE_VALVE_EVENT} for the
+ * associated container if this call is successful.
+ * </p>
*
* @param valve Valve to be removed
*/
@@ -110,26 +101,24 @@ public interface Pipeline extends Contained {
/**
- * @return the Valve instance that has been distinguished as the basic
- * Valve for this Pipeline (if any).
+ * @return the Valve instance that has been distinguished as the basic Valve for this Pipeline (if any).
*/
Valve getFirst();
/**
* Returns true if all the valves in this pipeline support async, false otherwise
+ *
* @return true if all the valves in this pipeline support async, false otherwise
*/
boolean isAsyncSupported();
/**
- * Identifies the Valves, if any, in this Pipeline that do not support
- * async.
+ * Identifies the Valves, if any, in this Pipeline that do not support async.
*
- * @param result The Set to which the fully qualified class names of each
- * Valve in this Pipeline that does not support async will be
- * added
+ * @param result The Set to which the fully qualified class names of each Valve in this Pipeline that does not
+ * support async will be added
*/
void findNonAsyncValves(Set<String> result);
}
diff --git a/java/org/apache/catalina/Realm.java b/java/org/apache/catalina/Realm.java
index e81802965e..87893a0259 100644
--- a/java/org/apache/catalina/Realm.java
+++ b/java/org/apache/catalina/Realm.java
@@ -29,11 +29,9 @@ import org.ietf.jgss.GSSCredential;
import org.ietf.jgss.GSSName;
/**
- * A <b>Realm</b> is a read-only facade for an underlying security realm
- * used to authenticate individual users, and identify the security roles
- * associated with those users. Realms can be attached at any Container
- * level, but will typically only be attached to a Context, or higher level,
- * Container.
+ * A <b>Realm</b> is a read-only facade for an underlying security realm used to authenticate individual users, and
+ * identify the security roles associated with those users. Realms can be attached at any Container level, but will
+ * typically only be attached to a Context, or higher level, Container.
*
* @author Craig R. McClanahan
*/
@@ -72,12 +70,10 @@ public interface Realm extends Contained {
/**
- * Try to authenticate using the specified username and
- * credentials.
+ * Try to authenticate using the specified username and credentials.
*
- * @param username Username of the Principal to look up
- * @param credentials Password or other credentials to use in
- * authenticating this username
+ * @param username Username of the Principal to look up
+ * @param credentials Password or other credentials to use in authenticating this username
*
* @return the associated principal, or {@code null} if there is none
*/
@@ -85,65 +81,55 @@ public interface Realm extends Contained {
/**
- * Try to authenticate with the specified username, which
- * matches the digest calculated using the given parameters using the
- * method described in RFC 2617 (which is a superset of RFC 2069).
+ * Try to authenticate with the specified username, which matches the digest calculated using the given parameters
+ * using the method described in RFC 2617 (which is a superset of RFC 2069).
*
* @param username Username of the Principal to look up
- * @param digest Digest which has been submitted by the client
- * @param nonce Unique (or supposedly unique) token which has been used
- * for this request
- * @param nc the nonce counter
- * @param cnonce the client chosen nonce
- * @param qop the "quality of protection" ({@code nc} and {@code cnonce}
- * will only be used, if {@code qop} is not {@code null}).
- * @param realm Realm name
+ * @param digest Digest which has been submitted by the client
+ * @param nonce Unique (or supposedly unique) token which has been used for this request
+ * @param nc the nonce counter
+ * @param cnonce the client chosen nonce
+ * @param qop the "quality of protection" ({@code nc} and {@code cnonce} will only be used, if {@code qop} is
+ * not {@code null}).
+ * @param realm Realm name
* @param digestA2 Second digest calculated as digest(Method + ":" + uri)
*
* @return the associated principal, or {@code null} if there is none.
*
- * @deprecated Unused. Use {@link #authenticate(String, String, String,
- * String, String, String, String, String, String)}. Will be removed in
- * Tomcat 11.
+ * @deprecated Unused. Use
+ * {@link #authenticate(String, String, String, String, String, String, String, String, String)}.
+ * Will be removed in Tomcat 11.
*/
@Deprecated
- Principal authenticate(String username, String digest,
- String nonce, String nc, String cnonce,
- String qop, String realm,
- String digestA2);
+ Principal authenticate(String username, String digest, String nonce, String nc, String cnonce, String qop,
+ String realm, String digestA2);
/**
- * Try to authenticate with the specified username, which
- * matches the digest calculated using the given parameters using the
- * method described in RFC 7616.
+ * Try to authenticate with the specified username, which matches the digest calculated using the given parameters
+ * using the method described in RFC 7616.
* <p>
- * The default implementation calls {@link #authenticate(String, String,
- * String, String, String, String, String, String)} for backwards
- * compatibility which effectively forces the use of MD5 regardless of the
- * algorithm specified in the call to this method.
+ * The default implementation calls
+ * {@link #authenticate(String, String, String, String, String, String, String, String)} for backwards compatibility
+ * which effectively forces the use of MD5 regardless of the algorithm specified in the call to this method.
* <p>
- * Implementations are expected to override the default implementation and
- * take account of the algorithm parameter.
- *
- * @param username Username of the Principal to look up
- * @param digest Digest which has been submitted by the client
- * @param nonce Unique (or supposedly unique) token which has been used
- * for this request
- * @param nc the nonce counter
- * @param cnonce the client chosen nonce
- * @param qop the "quality of protection" ({@code nc} and {@code cnonce}
- * will only be used, if {@code qop} is not {@code null}).
- * @param realm Realm name
- * @param digestA2 Second digest calculated as digest(Method + ":" + uri)
+ * Implementations are expected to override the default implementation and take account of the algorithm parameter.
+ *
+ * @param username Username of the Principal to look up
+ * @param digest Digest which has been submitted by the client
+ * @param nonce Unique (or supposedly unique) token which has been used for this request
+ * @param nc the nonce counter
+ * @param cnonce the client chosen nonce
+ * @param qop the "quality of protection" ({@code nc} and {@code cnonce} will only be used, if {@code qop} is
+ * not {@code null}).
+ * @param realm Realm name
+ * @param digestA2 Second digest calculated as digest(Method + ":" + uri)
* @param algorithm The message digest algorithm to use
*
* @return the associated principal, or {@code null} if there is none.
*/
- default Principal authenticate(String username, String digest,
- String nonce, String nc, String cnonce,
- String qop, String realm,
- String digestA2, String algorithm) {
+ default Principal authenticate(String username, String digest, String nonce, String nc, String cnonce, String qop,
+ String realm, String digestA2, String algorithm) {
return authenticate(username, digest, nonce, nc, cnonce, qop, realm, digestA2);
}
@@ -152,8 +138,8 @@ public interface Realm extends Contained {
* Try to authenticate using a {@link GSSContext}.
*
* @param gssContext The gssContext processed by the {@link Authenticator}.
- * @param storeCreds Should the realm attempt to store the delegated
- * credentials in the returned Principal?
+ * @param storeCreds Should the realm attempt to store the delegated credentials in the returned Principal?
+ *
* @return the associated principal, or {@code null} if there is none
*/
Principal authenticate(GSSContext gssContext, boolean storeCreds);
@@ -162,9 +148,9 @@ public interface Realm extends Contained {
/**
* Try to authenticate using a {@link GSSName}.
*
- * @param gssName The {@link GSSName} of the principal to look up
- * @param gssCredential The {@link GSSCredential} of the principal, may be
- * {@code null}
+ * @param gssName The {@link GSSName} of the principal to look up
+ * @param gssCredential The {@link GSSCredential} of the principal, may be {@code null}
+ *
* @return the associated principal, or {@code null} if there is none
*/
Principal authenticate(GSSName gssName, GSSCredential gssCredential);
@@ -173,8 +159,8 @@ public interface Realm extends Contained {
/**
* Try to authenticate using a chain of {@link X509Certificate}s.
*
- * @param certs Array of client certificates, with the first one in
- * the array being the certificate of the client itself.
+ * @param certs Array of client certificates, with the first one in the array being the certificate of the client
+ * itself.
*
* @return the associated principal, or {@code null} if there is none
*/
@@ -182,80 +168,66 @@ public interface Realm extends Contained {
/**
- * Execute a periodic task, such as reloading, etc. This method will be
- * invoked inside the classloading context of this container. Unexpected
- * throwables will be caught and logged.
+ * Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of
+ * this container. Unexpected throwables will be caught and logged.
*/
void backgroundProcess();
/**
- * Find the SecurityConstraints configured to guard the request URI for
- * this request.
+ * Find the SecurityConstraints configured to guard the request URI for this request.
*
* @param request Request we are processing
* @param context Context the Request is mapped to
*
- * @return the configured {@link SecurityConstraint}, or {@code null} if
- * there is none
+ * @return the configured {@link SecurityConstraint}, or {@code null} if there is none
*/
- SecurityConstraint [] findSecurityConstraints(Request request,
- Context context);
+ SecurityConstraint[] findSecurityConstraints(Request request, Context context);
/**
* Perform access control based on the specified authorization constraint.
*
- * @param request Request we are processing
- * @param response Response we are creating
+ * @param request Request we are processing
+ * @param response Response we are creating
* @param constraint Security constraint we are enforcing
- * @param context The Context to which client of this class is attached.
+ * @param context The Context to which client of this class is attached.
*
- * @return {@code true} if this constraint is satisfied and processing
- * should continue, or {@code false} otherwise
+ * @return {@code true} if this constraint is satisfied and processing should continue, or {@code false} otherwise
*
* @exception IOException if an input/output error occurs
*/
- boolean hasResourcePermission(Request request,
- Response response,
- SecurityConstraint [] constraint,
- Context context)
- throws IOException;
+ boolean hasResourcePermission(Request request, Response response, SecurityConstraint[] constraint, Context context)
+ throws IOException;
/**
- * Check if the specified Principal has the specified
- * security role, within the context of this Realm.
+ * Check if the specified Principal has the specified security role, within the context of this Realm.
*
- * @param wrapper wrapper context for evaluating role
+ * @param wrapper wrapper context for evaluating role
* @param principal Principal for whom the role is to be checked
- * @param role Security role to be checked
+ * @param role Security role to be checked
*
- * @return {@code true} if the specified Principal has the specified
- * security role, within the context of this Realm; otherwise return
- * {@code false}.
+ * @return {@code true} if the specified Principal has the specified security role, within the context of this
+ * Realm; otherwise return {@code false}.
*/
boolean hasRole(Wrapper wrapper, Principal principal, String role);
/**
- * Enforce any user data constraint required by the security constraint
- * guarding this request URI.
+ * Enforce any user data constraint required by the security constraint guarding this request URI.
*
- * @param request Request we are processing
- * @param response Response we are creating
+ * @param request Request we are processing
+ * @param response Response we are creating
* @param constraint Security constraint being checked
*
- * @return {@code true} if this constraint
- * was not violated and processing should continue, or {@code false}
- * if we have created a response already.
+ * @return {@code true} if this constraint was not violated and processing should continue, or {@code false} if we
+ * have created a response already.
*
* @exception IOException if an input/output error occurs
*/
- boolean hasUserDataPermission(Request request,
- Response response,
- SecurityConstraint []constraint)
- throws IOException;
+ boolean hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraint)
+ throws IOException;
/**
@@ -268,6 +240,7 @@ public interface Realm extends Contained {
/**
* Return the availability of the realm for authentication.
+ *
* @return {@code true} if the realm is able to perform authentication
*/
default boolean isAvailable() {
diff --git a/java/org/apache/catalina/Role.java b/java/org/apache/catalina/Role.java
index 18fea5e3e3..9c18711db3 100644
--- a/java/org/apache/catalina/Role.java
+++ b/java/org/apache/catalina/Role.java
@@ -21,10 +21,13 @@ import java.security.Principal;
/**
- * <p>Abstract representation of a security role, suitable for use in
- * environments like JAAS that want to deal with <code>Principals</code>.</p>
+ * <p>
+ * Abstract representation of a security role, suitable for use in environments like JAAS that want to deal with
+ * <code>Principals</code>.
+ * </p>
*
* @author Craig R. McClanahan
+ *
* @since 4.1
*/
public interface Role extends Principal {
@@ -48,15 +51,13 @@ public interface Role extends Principal {
/**
- * @return the role name of this role, which must be unique
- * within the scope of a {@link UserDatabase}.
+ * @return the role name of this role, which must be unique within the scope of a {@link UserDatabase}.
*/
String getRolename();
/**
- * Set the role name of this role, which must be unique
- * within the scope of a {@link UserDatabase}.
+ * Set the role name of this role, which must be unique within the scope of a {@link UserDatabase}.
*
* @param rolename The new role name
*/
diff --git a/java/org/apache/catalina/Server.java b/java/org/apache/catalina/Server.java
index eff7279523..3c3a248ec6 100644
--- a/java/org/apache/catalina/Server.java
+++ b/java/org/apache/catalina/Server.java
@@ -23,21 +23,17 @@ import org.apache.catalina.deploy.NamingResourcesImpl;
import org.apache.catalina.startup.Catalina;
/**
- * A <code>Server</code> element represents the entire Catalina
- * servlet container. Its attributes represent the characteristics of
- * the servlet container as a whole. A <code>Server</code> may contain
- * one or more <code>Services</code>, and the top level set of naming
- * resources.
+ * A <code>Server</code> element represents the entire Catalina servlet container. Its attributes represent the
+ * characteristics of the servlet container as a whole. A <code>Server</code> may contain one or more
+ * <code>Services</code>, and the top level set of naming resources.
* <p>
- * Normally, an implementation of this interface will also implement
- * <code>Lifecycle</code>, such that when the <code>start()</code> and
- * <code>stop()</code> methods are called, all of the defined
- * <code>Services</code> are also started or stopped.
+ * Normally, an implementation of this interface will also implement <code>Lifecycle</code>, such that when the
+ * <code>start()</code> and <code>stop()</code> methods are called, all of the defined <code>Services</code> are also
+ * started or stopped.
* <p>
- * In between, the implementation must open a server socket on the port number
- * specified by the <code>port</code> property. When a connection is accepted,
- * the first line is read and compared with the specified shutdown command.
- * If the command matches, shutdown of the server is initiated.
+ * In between, the implementation must open a server socket on the port number specified by the <code>port</code>
+ * property. When a connection is accepted, the first line is read and compared with the specified shutdown command. If
+ * the command matches, shutdown of the server is initiated.
*
* @author Craig R. McClanahan
*/
@@ -56,8 +52,7 @@ public interface Server extends Lifecycle {
*
* @param globalNamingResources The new global naming resources
*/
- void setGlobalNamingResources
- (NamingResourcesImpl globalNamingResources);
+ void setGlobalNamingResources(NamingResourcesImpl globalNamingResources);
/**
@@ -85,27 +80,24 @@ public interface Server extends Lifecycle {
void setPort(int port);
/**
- * Get the number that offsets the port used for shutdown commands.
- * For example, if port is 8005, and portOffset is 1000,
- * the server listens at 9005.
+ * Get the number that offsets the port used for shutdown commands. For example, if port is 8005, and portOffset is
+ * 1000, the server listens at 9005.
*
* @return the port offset
*/
int getPortOffset();
/**
- * Set the number that offsets the server port used for shutdown commands.
- * For example, if port is 8005, and you set portOffset to 1000,
- * connector listens at 9005.
+ * Set the number that offsets the server port used for shutdown commands. For example, if port is 8005, and you set
+ * portOffset to 1000, connector listens at 9005.
*
* @param portOffset sets the port offset
*/
void setPortOffset(int portOffset);
/**
- * Get the actual port on which server is listening for the shutdown commands.
- * If you do not set port offset, port is returned. If you set
- * port offset, port offset + port is returned.
+ * Get the actual port on which server is listening for the shutdown commands. If you do not set port offset, port
+ * is returned. If you set port offset, port offset + port is returned.
*
* @return the port with offset
*/
@@ -140,9 +132,9 @@ public interface Server extends Lifecycle {
/**
- * @return the parent class loader for this component. If not set, return
- * {@link #getCatalina()} {@link Catalina#getParentClassLoader()}. If
- * catalina has not been set, return the system class loader.
+ * @return the parent class loader for this component. If not set, return {@link #getCatalina()}
+ * {@link Catalina#getParentClassLoader()}. If catalina has not been set, return the system class
+ * loader.
*/
ClassLoader getParentClassLoader();
@@ -169,15 +161,13 @@ public interface Server extends Lifecycle {
/**
- * @return the configured base (instance) directory. Note that home and base
- * may be the same (and are by default). If this is not set the value
- * returned by {@link #getCatalinaHome()} will be used.
+ * @return the configured base (instance) directory. Note that home and base may be the same (and are by default).
+ * If this is not set the value returned by {@link #getCatalinaHome()} will be used.
*/
File getCatalinaBase();
/**
- * Set the configured base (instance) directory. Note that home and base
- * may be the same (and are by default).
+ * Set the configured base (instance) directory. Note that home and base may be the same (and are by default).
*
* @param catalinaBase the configured base directory
*/
@@ -185,14 +175,12 @@ public interface Server extends Lifecycle {
/**
- * @return the configured home (binary) directory. Note that home and base
- * may be the same (and are by default).
+ * @return the configured home (binary) directory. Note that home and base may be the same (and are by default).
*/
File getCatalinaHome();
/**
- * Set the configured home (binary) directory. Note that home and base
- * may be the same (and are by default).
+ * Set the configured home (binary) directory. Note that home and base may be the same (and are by default).
*
* @param catalinaHome the configured home directory
*/
@@ -201,6 +189,7 @@ public interface Server extends Lifecycle {
/**
* Get the utility thread count.
+ *
* @return the thread count
*/
int getUtilityThreads();
@@ -208,6 +197,7 @@ public interface Server extends Lifecycle {
/**
* Set the utility thread count.
+ *
* @param utilityThreads the new thread count
*/
void setUtilityThreads(int utilityThreads);
@@ -234,6 +224,7 @@ public interface Server extends Lifecycle {
* Find the specified Service
*
* @param name Name of the Service to be returned
+ *
* @return the specified Service, or <code>null</code> if none exists.
*/
Service findService(String name);
@@ -246,8 +237,7 @@ public interface Server extends Lifecycle {
/**
- * Remove the specified Service from the set associated from this
- * Server.
+ * Remove the specified Service from the set associated from this Server.
*
* @param service The Service to be removed
*/
@@ -255,8 +245,7 @@ public interface Server extends Lifecycle {
/**
- * @return the token necessary for operations on the associated JNDI naming
- * context.
+ * @return the token necessary for operations on the associated JNDI naming context.
*/
Object getNamingToken();
diff --git a/java/org/apache/catalina/Service.java b/java/org/apache/catalina/Service.java
index 0d7b37a6a3..04a2e594fa 100644
--- a/java/org/apache/catalina/Service.java
+++ b/java/org/apache/catalina/Service.java
@@ -20,14 +20,12 @@ import org.apache.catalina.connector.Connector;
import org.apache.catalina.mapper.Mapper;
/**
- * A <strong>Service</strong> is a group of one or more
- * <strong>Connectors</strong> that share a single <strong>Container</strong>
- * to process their incoming requests. This arrangement allows, for example,
- * a non-SSL and SSL connector to share the same population of web apps.
+ * A <strong>Service</strong> is a group of one or more <strong>Connectors</strong> that share a single
+ * <strong>Container</strong> to process their incoming requests. This arrangement allows, for example, a non-SSL and
+ * SSL connector to share the same population of web apps.
* <p>
- * A given JVM can contain any number of Service instances; however, they are
- * completely independent of each other and share only the basic JVM facilities
- * and classes on the system class path.
+ * A given JVM can contain any number of Service instances; however, they are completely independent of each other and
+ * share only the basic JVM facilities and classes on the system class path.
*
* @author Craig R. McClanahan
*/
@@ -36,14 +34,13 @@ public interface Service extends Lifecycle {
// ------------------------------------------------------------- Properties
/**
- * @return the <code>Engine</code> that handles requests for all
- * <code>Connectors</code> associated with this Service.
+ * @return the <code>Engine</code> that handles requests for all <code>Connectors</code> associated with this
+ * Service.
*/
Engine getContainer();
/**
- * Set the <code>Engine</code> that handles requests for all
- * <code>Connectors</code> associated with this Service.
+ * Set the <code>Engine</code> that handles requests for all <code>Connectors</code> associated with this Service.
*
* @param engine The new Engine
*/
@@ -74,9 +71,8 @@ public interface Service extends Lifecycle {
void setServer(Server server);
/**
- * @return the parent class loader for this component. If not set, return
- * {@link #getServer()} {@link Server#getParentClassLoader()}. If no server
- * has been set, return the system class loader.
+ * @return the parent class loader for this component. If not set, return {@link #getServer()}
+ * {@link Server#getParentClassLoader()}. If no server has been set, return the system class loader.
*/
ClassLoader getParentClassLoader();
@@ -88,8 +84,7 @@ public interface Service extends Lifecycle {
void setParentClassLoader(ClassLoader parent);
/**
- * @return the domain under which this container will be / has been
- * registered.
+ * @return the domain under which this container will be / has been registered.
*/
String getDomain();
@@ -97,8 +92,7 @@ public interface Service extends Lifecycle {
// --------------------------------------------------------- Public Methods
/**
- * Add a new Connector to the set of defined Connectors, and associate it
- * with this Service's Container.
+ * Add a new Connector to the set of defined Connectors, and associate it with this Service's Container.
*
* @param connector The Connector to be added
*/
@@ -112,9 +106,8 @@ public interface Service extends Lifecycle {
Connector[] findConnectors();
/**
- * Remove the specified Connector from the set associated from this
- * Service. The removed Connector will also be disassociated from our
- * Container.
+ * Remove the specified Connector from the set associated from this Service. The removed Connector will also be
+ * disassociated from our Container.
*
* @param connector The Connector to be removed
*/
@@ -122,25 +115,30 @@ public interface Service extends Lifecycle {
/**
* Adds a named executor to the service
+ *
* @param ex Executor
*/
void addExecutor(Executor ex);
/**
* Retrieves all executors
+ *
* @return Executor[]
*/
Executor[] findExecutors();
/**
* Retrieves executor by name, null if not found
+ *
* @param name String
+ *
* @return Executor
*/
Executor getExecutor(String name);
/**
* Removes an executor from the service
+ *
* @param ex Executor
*/
void removeExecutor(Executor ex);
diff --git a/java/org/apache/catalina/Session.java b/java/org/apache/catalina/Session.java
index 4ec7aca0ed..45e1fa8276 100644
--- a/java/org/apache/catalina/Session.java
+++ b/java/org/apache/catalina/Session.java
@@ -24,9 +24,8 @@ import jakarta.servlet.http.HttpSession;
/**
- * A <b>Session</b> is the Catalina-internal facade for an
- * <code>HttpSession</code> that is used to maintain state information
- * between requests for a particular user of a web application.
+ * A <b>Session</b> is the Catalina-internal facade for an <code>HttpSession</code> that is used to maintain state
+ * information between requests for a particular user of a web application.
*
* @author Craig R. McClanahan
*/
@@ -64,15 +63,13 @@ public interface Session {
/**
- * @return the authentication type used to authenticate our cached
- * Principal, if any.
+ * @return the authentication type used to authenticate our cached Principal, if any.
*/
String getAuthType();
/**
- * Set the authentication type used to authenticate our cached
- * Principal, if any.
+ * Set the authentication type used to authenticate our cached Principal, if any.
*
* @param authType The new cached authentication type
*/
@@ -86,15 +83,14 @@ public interface Session {
/**
- * @return the creation time for this session, bypassing the session validity
- * checks.
+ * @return the creation time for this session, bypassing the session validity checks.
*/
long getCreationTimeInternal();
/**
- * Set the creation time for this session. This method is called by the
- * Manager when an existing Session instance is reused.
+ * Set the creation time for this session. This method is called by the Manager when an existing Session instance is
+ * reused.
*
* @param time The new creation time
*/
@@ -114,8 +110,8 @@ public interface Session {
/**
- * Set the session identifier for this session and notifies any associated
- * listeners that a new session has been created.
+ * Set the session identifier for this session and notifies any associated listeners that a new session has been
+ * created.
*
* @param id The new session identifier
*/
@@ -123,42 +119,41 @@ public interface Session {
/**
- * Set the session identifier for this session and optionally notifies any
- * associated listeners that a new session has been created.
+ * Set the session identifier for this session and optionally notifies any associated listeners that a new session
+ * has been created.
*
- * @param id The new session identifier
- * @param notify Should any associated listeners be notified that a new
- * session has been created?
+ * @param id The new session identifier
+ * @param notify Should any associated listeners be notified that a new session has been created?
*/
void setId(String id, boolean notify);
/**
- * @return the last time the client sent a request associated with this
- * session, as the number of milliseconds since midnight, January 1, 1970
- * GMT. Actions that your application takes, such as getting or setting
- * a value associated with the session, do not affect the access time.
- * This one gets updated whenever a request starts.
+ * @return the last time the client sent a request associated with this session, as the number of milliseconds since
+ * midnight, January 1, 1970 GMT. Actions that your application takes, such as getting or setting a
+ * value associated with the session, do not affect the access time. This one gets updated whenever a
+ * request starts.
*/
long getThisAccessedTime();
/**
* @return the last client access time without invalidation check
+ *
* @see #getThisAccessedTime()
*/
long getThisAccessedTimeInternal();
/**
- * @return the last time the client sent a request associated with this
- * session, as the number of milliseconds since midnight, January 1, 1970
- * GMT. Actions that your application takes, such as getting or setting
- * a value associated with the session, do not affect the access time.
- * This one gets updated whenever a request finishes.
+ * @return the last time the client sent a request associated with this session, as the number of milliseconds since
+ * midnight, January 1, 1970 GMT. Actions that your application takes, such as getting or setting a
+ * value associated with the session, do not affect the access time. This one gets updated whenever a
+ * request finishes.
*/
long getLastAccessedTime();
/**
* @return the last client access time without invalidation check
+ *
* @see #getLastAccessedTime()
*/
long getLastAccessedTimeInternal();
@@ -170,6 +165,7 @@ public interface Session {
/**
* @return the idle time from last client access time without invalidation check
+ *
* @see #getIdleTime()
*/
long getIdleTimeInternal();
@@ -189,17 +185,15 @@ public interface Session {
/**
- * @return the maximum time interval, in seconds, between client requests
- * before the servlet container will invalidate the session. A negative
- * time indicates that the session should never time out.
+ * @return the maximum time interval, in seconds, between client requests before the servlet container will
+ * invalidate the session. A negative time indicates that the session should never time out.
*/
int getMaxInactiveInterval();
/**
- * Set the maximum time interval, in seconds, between client requests
- * before the servlet container will invalidate the session. A negative
- * time indicates that the session should never time out.
+ * Set the maximum time interval, in seconds, between client requests before the servlet container will invalidate
+ * the session. A negative time indicates that the session should never time out.
*
* @param interval The new maximum interval
*/
@@ -215,19 +209,17 @@ public interface Session {
/**
- * @return the authenticated Principal that is associated with this Session.
- * This provides an <code>Authenticator</code> with a means to cache a
- * previously authenticated Principal, and avoid potentially expensive
- * <code>Realm.authenticate()</code> calls on every request. If there
- * is no current associated Principal, return <code>null</code>.
+ * @return the authenticated Principal that is associated with this Session. This provides an
+ * <code>Authenticator</code> with a means to cache a previously authenticated Principal, and avoid
+ * potentially expensive <code>Realm.authenticate()</code> calls on every request. If there is no
+ * current associated Principal, return <code>null</code>.
*/
Principal getPrincipal();
/**
- * Set the authenticated Principal that is associated with this Session.
- * This provides an <code>Authenticator</code> with a means to cache a
- * previously authenticated Principal, and avoid potentially expensive
+ * Set the authenticated Principal that is associated with this Session. This provides an <code>Authenticator</code>
+ * with a means to cache a previously authenticated Principal, and avoid potentially expensive
* <code>Realm.authenticate()</code> calls on every request.
*
* @param principal The new Principal, or <code>null</code> if none
@@ -236,8 +228,7 @@ public interface Session {
/**
- * @return the <code>HttpSession</code> for which this object
- * is the facade.
+ * @return the <code>HttpSession</code> for which this object is the facade.
*/
HttpSession getSession();
@@ -260,9 +251,8 @@ public interface Session {
/**
- * Update the accessed time information for this session. This method
- * should be called by the context when a request comes in for a particular
- * session, even if the application does not reference it.
+ * Update the accessed time information for this session. This method should be called by the context when a request
+ * comes in for a particular session, even if the application does not reference it.
*/
void access();
@@ -270,8 +260,7 @@ public interface Session {
/**
* Add a session event listener to this component.
*
- * @param listener the SessionListener instance that should be notified
- * for session events
+ * @param listener the SessionListener instance that should be notified for session events
*/
void addSessionListener(SessionListener listener);
@@ -283,15 +272,15 @@ public interface Session {
/**
- * Perform the internal processing required to invalidate this session,
- * without triggering an exception if the session has already expired.
+ * Perform the internal processing required to invalidate this session, without triggering an exception if the
+ * session has already expired.
*/
void expire();
/**
- * @return the object bound with the specified name to the internal notes
- * for this session, or <code>null</code> if no such binding exists.
+ * @return the object bound with the specified name to the internal notes for this session, or <code>null</code> if
+ * no such binding exists.
*
* @param name Name of the note to be returned
*/
@@ -299,22 +288,19 @@ public interface Session {
/**
- * @return an Iterator containing the String names of all notes bindings
- * that exist for this session.
+ * @return an Iterator containing the String names of all notes bindings that exist for this session.
*/
Iterator<String> getNoteNames();
/**
- * Release all object references, and initialize instance variables, in
- * preparation for reuse of this object.
+ * Release all object references, and initialize instance variables, in preparation for reuse of this object.
*/
void recycle();
/**
- * Remove any object bound to the specified name in the internal notes
- * for this session.
+ * Remove any object bound to the specified name in the internal notes for this session.
*
* @param name Name of the note to be removed
*/
@@ -324,17 +310,16 @@ public interface Session {
/**
* Remove a session event listener from this component.
*
- * @param listener remove the session listener, which will no longer be
- * notified
+ * @param listener remove the session listener, which will no longer be notified
*/
void removeSessionListener(SessionListener listener);
/**
- * Bind an object to a specified name in the internal notes associated
- * with this session, replacing any existing binding for this name.
+ * Bind an object to a specified name in the internal notes associated with this session, replacing any existing
+ * binding for this name.
*
- * @param name Name to which the object should be bound
+ * @param name Name to which the object should be bound
* @param value Object to be bound to the specified name
*/
void setNote(String name, Object value);
@@ -343,27 +328,24 @@ public interface Session {
/**
* Inform the listeners about the change session ID.
*
- * @param newId new session ID
- * @param oldId old session ID
- * @param notifySessionListeners Should any associated sessionListeners be
- * notified that session ID has been changed?
- * @param notifyContainerListeners Should any associated ContainerListeners
- * be notified that session ID has been changed?
+ * @param newId new session ID
+ * @param oldId old session ID
+ * @param notifySessionListeners Should any associated sessionListeners be notified that session ID has been
+ * changed?
+ * @param notifyContainerListeners Should any associated ContainerListeners be notified that session ID has been
+ * changed?
*/
- void tellChangedSessionId(String newId, String oldId,
- boolean notifySessionListeners, boolean notifyContainerListeners);
+ void tellChangedSessionId(String newId, String oldId, boolean notifySessionListeners,
+ boolean notifyContainerListeners);
/**
- * Does the session implementation support the distributing of the given
- * attribute? If the Manager is marked as distributable, then this method
- * must be used to check attributes before adding them to a session and
- * an {@link IllegalArgumentException} thrown if the proposed attribute is
- * not distributable.
+ * Does the session implementation support the distributing of the given attribute? If the Manager is marked as
+ * distributable, then this method must be used to check attributes before adding them to a session and an
+ * {@link IllegalArgumentException} thrown if the proposed attribute is not distributable.
* <p>
- * Note that the {@link Manager} implementation may further restrict which
- * attributes are distributed but a {@link Manager} level restriction should
- * not trigger an {@link IllegalArgumentException} in
+ * Note that the {@link Manager} implementation may further restrict which attributes are distributed but a
+ * {@link Manager} level restriction should not trigger an {@link IllegalArgumentException} in
* {@link HttpSession#setAttribute(String, Object)}
*
* @param name The attribute name
diff --git a/java/org/apache/catalina/SessionEvent.java b/java/org/apache/catalina/SessionEvent.java
index e92ff38b47..fb40837f36 100644
--- a/java/org/apache/catalina/SessionEvent.java
+++ b/java/org/apache/catalina/SessionEvent.java
@@ -52,8 +52,8 @@ public final class SessionEvent extends EventObject {
* Construct a new SessionEvent with the specified parameters.
*
* @param session Session on which this event occurred
- * @param type Event type
- * @param data Event data
+ * @param type Event type
+ * @param data Event data
*/
public SessionEvent(Session session, String type, Object data) {
diff --git a/java/org/apache/catalina/SessionIdGenerator.java b/java/org/apache/catalina/SessionIdGenerator.java
index 09a08dfb19..f9b318201b 100644
--- a/java/org/apache/catalina/SessionIdGenerator.java
+++ b/java/org/apache/catalina/SessionIdGenerator.java
@@ -19,16 +19,14 @@ package org.apache.catalina;
public interface SessionIdGenerator {
/**
- * @return the node identifier associated with this node which will be
- * included in the generated session ID.
+ * @return the node identifier associated with this node which will be included in the generated session ID.
*/
String getJvmRoute();
/**
- * Specify the node identifier associated with this node which will be
- * included in the generated session ID.
+ * Specify the node identifier associated with this node which will be included in the generated session ID.
*
- * @param jvmRoute The node identifier
+ * @param jvmRoute The node identifier
*/
void setJvmRoute(String jvmRoute);
@@ -40,7 +38,7 @@ public interface SessionIdGenerator {
/**
* Specify the number of bytes for a session ID
*
- * @param sessionIdLength Number of bytes
+ * @param sessionIdLength Number of bytes
*/
void setSessionIdLength(int sessionIdLength);
@@ -54,7 +52,8 @@ public interface SessionIdGenerator {
/**
* Generate and return a new session identifier.
*
- * @param route node identifier to include in generated id
+ * @param route node identifier to include in generated id
+ *
* @return the newly generated session id
*/
String generateSessionId(String route);
diff --git a/java/org/apache/catalina/Store.java b/java/org/apache/catalina/Store.java
index 9512121526..89b3e01218 100644
--- a/java/org/apache/catalina/Store.java
+++ b/java/org/apache/catalina/Store.java
@@ -22,11 +22,9 @@ import java.io.IOException;
/**
- * A <b>Store</b> is the abstraction of a Catalina component that provides
- * persistent storage and loading of Sessions and their associated user data.
- * Implementations are free to save and load the Sessions to any media they
- * wish, but it is assumed that saved Sessions are persistent across
- * server or context restarts.
+ * A <b>Store</b> is the abstraction of a Catalina component that provides persistent storage and loading of Sessions
+ * and their associated user data. Implementations are free to save and load the Sessions to any media they wish, but it
+ * is assumed that saved Sessions are persistent across server or context restarts.
*
* @author Craig R. McClanahan
*/
@@ -68,9 +66,8 @@ public interface Store {
/**
- * @return an array containing the session identifiers of all Sessions
- * currently saved in this Store. If there are no such Sessions, a
- * zero-length array is returned.
+ * @return an array containing the session identifiers of all Sessions currently saved in this Store. If there are
+ * no such Sessions, a zero-length array is returned.
*
* @exception IOException if an input/output error occurred
*/
@@ -78,24 +75,22 @@ public interface Store {
/**
- * Load and return the Session associated with the specified session
- * identifier from this Store, without removing it. If there is no
- * such stored Session, return <code>null</code>.
+ * Load and return the Session associated with the specified session identifier from this Store, without removing
+ * it. If there is no such stored Session, return <code>null</code>.
*
* @param id Session identifier of the session to load
*
* @exception ClassNotFoundException if a deserialization error occurs
- * @exception IOException if an input/output error occurs
+ * @exception IOException if an input/output error occurs
+ *
* @return the loaded Session instance
*/
- Session load(String id)
- throws ClassNotFoundException, IOException;
+ Session load(String id) throws ClassNotFoundException, IOException;
/**
- * Remove the Session with the specified session identifier from
- * this Store, if present. If no such Session is present, this method
- * takes no action.
+ * Remove the Session with the specified session identifier from this Store, if present. If no such Session is
+ * present, this method takes no action.
*
* @param id Session identifier of the Session to be removed
*
@@ -121,8 +116,8 @@ public interface Store {
/**
- * Save the specified Session into this Store. Any previously saved
- * information for the associated session identifier is replaced.
+ * Save the specified Session into this Store. Any previously saved information for the associated session
+ * identifier is replaced.
*
* @param session Session to be saved
*
diff --git a/java/org/apache/catalina/StoreManager.java b/java/org/apache/catalina/StoreManager.java
index fbc05b85ba..fe23014c6b 100644
--- a/java/org/apache/catalina/StoreManager.java
+++ b/java/org/apache/catalina/StoreManager.java
@@ -17,20 +17,18 @@
package org.apache.catalina;
/**
- * PersistentManager would have been a better name but that would have clashed
- * with the implementation name.
+ * PersistentManager would have been a better name but that would have clashed with the implementation name.
*/
public interface StoreManager extends DistributedManager {
/**
- * @return the Store object which manages persistent Session
- * storage for this Manager.
+ * @return the Store object which manages persistent Session storage for this Manager.
*/
Store getStore();
/**
- * Remove this Session from the active Sessions for this Manager,
- * but not from the Store. (Used by the PersistentValve)
+ * Remove this Session from the active Sessions for this Manager, but not from the Store. (Used by the
+ * PersistentValve)
*
* @param session Session to be removed
*/
diff --git a/java/org/apache/catalina/ThreadBindingListener.java b/java/org/apache/catalina/ThreadBindingListener.java
index f901e534ad..68da5684b8 100644
--- a/java/org/apache/catalina/ThreadBindingListener.java
+++ b/java/org/apache/catalina/ThreadBindingListener.java
@@ -18,12 +18,13 @@ package org.apache.catalina;
/**
- * Callback for establishing naming association when entering the application
- * scope. This corresponds to setting the context classloader.
+ * Callback for establishing naming association when entering the application scope. This corresponds to setting the
+ * context classloader.
*/
public interface ThreadBindingListener {
void bind();
+
void unbind();
}
diff --git a/java/org/apache/catalina/TomcatPrincipal.java b/java/org/apache/catalina/TomcatPrincipal.java
index 3d69f0b053..582a6b5de6 100644
--- a/java/org/apache/catalina/TomcatPrincipal.java
+++ b/java/org/apache/catalina/TomcatPrincipal.java
@@ -22,8 +22,8 @@ import java.util.Enumeration;
import org.ietf.jgss.GSSCredential;
/**
- * Defines additional methods implemented by {@link Principal}s created by
- * Tomcat's standard {@link Realm} implementations.
+ * Defines additional methods implemented by {@link Principal}s created by Tomcat's standard {@link Realm}
+ * implementations.
*/
public interface TomcatPrincipal extends Principal {
@@ -38,61 +38,49 @@ public interface TomcatPrincipal extends Principal {
GSSCredential getGssCredential();
/**
- * Calls logout, if necessary, on any associated JAASLoginContext and/or
- * GSSContext. May in the future be extended to cover other logout
- * requirements.
+ * Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext. May in the future be extended
+ * to cover other logout requirements.
*
- * @throws Exception If something goes wrong with the logout. Uses Exception
- * to allow for future expansion of this method to cover
- * other logout mechanisms that might throw a different
- * exception to LoginContext
+ * @throws Exception If something goes wrong with the logout. Uses Exception to allow for future expansion of this
+ * method to cover other logout mechanisms that might throw a different exception to
+ * LoginContext
*/
void logout() throws Exception;
/**
- * Returns the value of the named attribute as an <code>Object</code>, or
- * <code>null</code> if no attribute of the given name exists, or if
- * <code>null</code> has been specified as the attribute's name.
+ * Returns the value of the named attribute as an <code>Object</code>, or <code>null</code> if no attribute of the
+ * given name exists, or if <code>null</code> has been specified as the attribute's name.
* <p>
- * Only the servlet container may set attributes to make available custom
- * information about a Principal or the user it represents.
+ * Only the servlet container may set attributes to make available custom information about a Principal or the user
+ * it represents.
* <p>
- * The purpose of the method is to implement read only access to attributes
- * which may be stored in the <code>Realm</code> implementation's backend
- * due to its inherent design.
+ * The purpose of the method is to implement read only access to attributes which may be stored in the
+ * <code>Realm</code> implementation's backend due to its inherent design.
* <p>
- * As using this method from application code will make it non portable to
- * other EE compliant containers, it is advised this should never be used
- * as an object storage facility tied to the <code>Principal</code>, but
- * rather as simple extra additional metadata. It is recommended that a
- * container level object is used to further process the attributes that
- * may be associated with the <code>Principal</code>.
+ * As using this method from application code will make it non portable to other EE compliant containers, it is
+ * advised this should never be used as an object storage facility tied to the <code>Principal</code>, but rather as
+ * simple extra additional metadata. It is recommended that a container level object is used to further process the
+ * attributes that may be associated with the <code>Principal</code>.
* <p>
- * <code>Realm</code> implementations that are provided by Tomcat will
- * not provide complex type mapping, but will in most cases always
- * return a result as a <code>String</code> object which may need custom
- * decoding.
+ * <code>Realm</code> implementations that are provided by Tomcat will not provide complex type mapping, but will in
+ * most cases always return a result as a <code>String</code> object which may need custom decoding.
* <p>
- * <code>Realm</code> implementations that are provided by Tomcat will
- * not provide an implementation for this facility unless it is inherent
- * to the storage backend of the <code>Realm</code> itself and metadata
- * is available without additional user intervention or configuration.
+ * <code>Realm</code> implementations that are provided by Tomcat will not provide an implementation for this
+ * facility unless it is inherent to the storage backend of the <code>Realm</code> itself and metadata is available
+ * without additional user intervention or configuration.
*
* @param name a <code>String</code> specifying the name of the attribute
- * @return an <code>Object</code> containing the value of the attribute, or
- * <code>null</code> if the attribute does not exist, or if
- * <code>null</code> has been specified as the attribute's name
+ *
+ * @return an <code>Object</code> containing the value of the attribute, or <code>null</code> if the attribute does
+ * not exist, or if <code>null</code> has been specified as the attribute's name
*/
Object getAttribute(String name);
/**
- * Returns an <code>Enumeration</code> containing the names of the
- * attributes available to this Principal. This method returns an empty
- * <code>Enumeration</code> if the Principal has no attributes available to
- * it.
+ * Returns an <code>Enumeration</code> containing the names of the attributes available to this Principal. This
+ * method returns an empty <code>Enumeration</code> if the Principal has no attributes available to it.
*
- * @return an <code>Enumeration</code> of strings containing the names of
- * the Principal's attributes
+ * @return an <code>Enumeration</code> of strings containing the names of the Principal's attributes
*/
Enumeration<String> getAttributeNames();
}
diff --git a/java/org/apache/catalina/TrackedWebResource.java b/java/org/apache/catalina/TrackedWebResource.java
index b6576e403d..1548e8c9c1 100644
--- a/java/org/apache/catalina/TrackedWebResource.java
+++ b/java/org/apache/catalina/TrackedWebResource.java
@@ -20,5 +20,6 @@ import java.io.Closeable;
public interface TrackedWebResource extends Closeable {
Exception getCreatedBy();
+
String getName();
}
diff --git a/java/org/apache/catalina/User.java b/java/org/apache/catalina/User.java
index eb51a1b807..4c1235bb1a 100644
--- a/java/org/apache/catalina/User.java
+++ b/java/org/apache/catalina/User.java
@@ -22,12 +22,12 @@ import java.util.Iterator;
/**
- * Abstract representation of a user in a {@link UserDatabase}. Each user is
- * optionally associated with a set of {@link Group}s through which they inherit
- * additional security roles, and is optionally assigned a set of specific
+ * Abstract representation of a user in a {@link UserDatabase}. Each user is optionally associated with a set of
+ * {@link Group}s through which they inherit additional security roles, and is optionally assigned a set of specific
* {@link Role}s.
*
* @author Craig R. McClanahan
+ *
* @since 4.1
*/
public interface User extends Principal {
@@ -57,17 +57,15 @@ public interface User extends Principal {
/**
- * @return the logon password of this user, optionally prefixed with the
- * identifier of an encoding scheme surrounded by curly braces, such as
- * <code>{md5}xxxxx</code>.
+ * @return the logon password of this user, optionally prefixed with the identifier of an encoding scheme surrounded
+ * by curly braces, such as <code>{md5}xxxxx</code>.
*/
String getPassword();
/**
- * Set the logon password of this user, optionally prefixed with the
- * identifier of an encoding scheme surrounded by curly braces, such as
- * <code>{md5}xxxxx</code>.
+ * Set the logon password of this user, optionally prefixed with the identifier of an encoding scheme surrounded by
+ * curly braces, such as <code>{md5}xxxxx</code>.
*
* @param password The new logon password
*/
@@ -87,15 +85,13 @@ public interface User extends Principal {
/**
- * @return the logon username of this user, which must be unique
- * within the scope of a {@link UserDatabase}.
+ * @return the logon username of this user, which must be unique within the scope of a {@link UserDatabase}.
*/
String getUsername();
/**
- * Set the logon username of this user, which must be unique within
- * the scope of a {@link UserDatabase}.
+ * Set the logon username of this user, which must be unique within the scope of a {@link UserDatabase}.
*
* @param username The new logon username
*/
@@ -125,17 +121,18 @@ public interface User extends Principal {
* Is this user in the specified {@link Group}?
*
* @param group The group to check
+ *
* @return <code>true</code> if the user is in the specified group
*/
boolean isInGroup(Group group);
/**
- * Is this user specifically assigned the specified {@link Role}? This
- * method does <strong>NOT</strong> check for roles inherited based on
- * {@link Group} membership.
+ * Is this user specifically assigned the specified {@link Role}? This method does <strong>NOT</strong> check for
+ * roles inherited based on {@link Group} membership.
*
* @param role The role to check
+ *
* @return <code>true</code> if the user has the specified role
*/
boolean isInRole(Role role);
diff --git a/java/org/apache/catalina/UserDatabase.java b/java/org/apache/catalina/UserDatabase.java
index e07b90b812..00e67318b9 100644
--- a/java/org/apache/catalina/UserDatabase.java
+++ b/java/org/apache/catalina/UserDatabase.java
@@ -19,12 +19,12 @@ package org.apache.catalina;
import java.util.Iterator;
/**
- * Abstract representation of a database of {@link User}s and {@link Group}s
- * that can be maintained by an application, along with definitions of
- * corresponding {@link Role}s, and referenced by a {@link Realm} for
- * authentication and access control.
+ * Abstract representation of a database of {@link User}s and {@link Group}s that can be maintained by an application,
+ * along with definitions of corresponding {@link Role}s, and referenced by a {@link Realm} for authentication and
+ * access control.
*
* @author Craig R. McClanahan
+ *
* @since 4.1
*/
public interface UserDatabase {
@@ -68,8 +68,9 @@ public interface UserDatabase {
/**
* Create and return a new {@link Group} defined in this user database.
*
- * @param groupname The group name of the new group (must be unique)
+ * @param groupname The group name of the new group (must be unique)
* @param description The description of this group
+ *
* @return The new group
*/
Group createGroup(String groupname, String description);
@@ -78,8 +79,9 @@ public interface UserDatabase {
/**
* Create and return a new {@link Role} defined in this user database.
*
- * @param rolename The role name of the new role (must be unique)
+ * @param rolename The role name of the new role (must be unique)
* @param description The description of this role
+ *
* @return The new role
*/
Role createRole(String rolename, String description);
@@ -91,14 +93,14 @@ public interface UserDatabase {
* @param username The logon username of the new user (must be unique)
* @param password The logon password of the new user
* @param fullName The full name of the new user
+ *
* @return The new user
*/
User createUser(String username, String password, String fullName);
/**
- * @return the {@link Group} with the specified group name, if any;
- * otherwise return <code>null</code>.
+ * @return the {@link Group} with the specified group name, if any; otherwise return <code>null</code>.
*
* @param groupname Name of the group to return
*/
@@ -106,8 +108,7 @@ public interface UserDatabase {
/**
- * @return the {@link Role} with the specified role name, if any; otherwise
- * return <code>null</code>.
+ * @return the {@link Role} with the specified role name, if any; otherwise return <code>null</code>.
*
* @param rolename Name of the role to return
*/
@@ -115,8 +116,7 @@ public interface UserDatabase {
/**
- * @return the {@link User} with the specified user name, if any; otherwise
- * return <code>null</code>.
+ * @return the {@link User} with the specified user name, if any; otherwise return <code>null</code>.
*
* @param username Name of the user to return
*/
@@ -156,35 +156,34 @@ public interface UserDatabase {
/**
- * Signal the specified {@link Group} from this user database has been
- * modified.
+ * Signal the specified {@link Group} from this user database has been modified.
*
* @param group The group that has been modified
*/
- default void modifiedGroup(Group group) {}
+ default void modifiedGroup(Group group) {
+ }
/**
- * Signal the specified {@link Role} from this user database has been
- * modified.
+ * Signal the specified {@link Role} from this user database has been modified.
*
* @param role The role that has been modified
*/
- default void modifiedRole(Role role) {}
+ default void modifiedRole(Role role) {
+ }
/**
- * Signal the specified {@link User} from this user database has been
- * modified.
+ * Signal the specified {@link User} from this user database has been modified.
*
* @param user The user that has been modified
*/
- default void modifiedUser(User user) {}
+ default void modifiedUser(User user) {
+ }
/**
- * Save any updated information to the persistent storage location for this
- * user database.
+ * Save any updated information to the persistent storage location for this user database.
*
* @exception Exception if any exception is thrown during saving
*/
@@ -192,8 +191,8 @@ public interface UserDatabase {
/**
- * Perform any background processing (e.g. checking for changes in persisted
- * storage) required for the user database.
+ * Perform any background processing (e.g. checking for changes in persisted storage) required for the user
+ * database.
*/
default void backgroundProcess() {
// NO-OP by default
@@ -211,9 +210,8 @@ public interface UserDatabase {
/**
- * Is the database data loaded on demand. This is used to avoid eager
- * loading of the full database data, for example for JMX registration of
- * all objects.
+ * Is the database data loaded on demand. This is used to avoid eager loading of the full database data, for example
+ * for JMX registration of all objects.
*
* @return false
*/
diff --git a/java/org/apache/catalina/Valve.java b/java/org/apache/catalina/Valve.java
index a3704fc03b..47c1f4c85b 100644
--- a/java/org/apache/catalina/Valve.java
+++ b/java/org/apache/catalina/Valve.java
@@ -24,14 +24,13 @@ import org.apache.catalina.connector.Request;
import org.apache.catalina.connector.Response;
/**
- * <p>A <b>Valve</b> is a request processing component associated with a
- * particular Container. A series of Valves are generally associated with
- * each other into a Pipeline. The detailed contract for a Valve is included
- * in the description of the <code>invoke()</code> method below.</p>
- *
- * <b>HISTORICAL NOTE</b>: The "Valve" name was assigned to this concept
- * because a valve is what you use in a real world pipeline to control and/or
- * modify flows through it.
+ * <p>
+ * A <b>Valve</b> is a request processing component associated with a particular Container. A series of Valves are
+ * generally associated with each other into a Pipeline. The detailed contract for a Valve is included in the
+ * description of the <code>invoke()</code> method below.
+ * </p>
+ * <b>HISTORICAL NOTE</b>: The "Valve" name was assigned to this concept because a valve is what you use in a real world
+ * pipeline to control and/or modify flows through it.
*
* @author Craig R. McClanahan
* @author Gunnar Rjnning
@@ -40,14 +39,13 @@ import org.apache.catalina.connector.Response;
public interface Valve {
- //-------------------------------------------------------------- Properties
+ // -------------------------------------------------------------- Properties
/**
- * Returns the next Valve in this pipeline, or <code>null</code> if this is
- * the last Valve in the pipeline.
+ * Returns the next Valve in this pipeline, or <code>null</code> if this is the last Valve in the pipeline.
*
- * @return the next Valve in the pipeline containing this Valve, or
- * <code>null</code> if this is the last Valve in the pipeline.
+ * @return the next Valve in the pipeline containing this Valve, or <code>null</code> if this is the last Valve in
+ * the pipeline.
*/
Valve getNext();
@@ -60,66 +58,60 @@ public interface Valve {
void setNext(Valve valve);
- //---------------------------------------------------------- Public Methods
+ // ---------------------------------------------------------- Public Methods
/**
- * Execute a periodic task, such as reloading, etc. This method will be
- * invoked inside the classloading context of this container. Unexpected
- * throwables will be caught and logged.
+ * Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of
+ * this container. Unexpected throwables will be caught and logged.
*/
void backgroundProcess();
/**
- * <p>Perform request processing as required by this Valve.</p>
- *
- * <p>An individual Valve <b>MAY</b> perform the following actions, in
- * the specified order:</p>
+ * <p>
+ * Perform request processing as required by this Valve.
+ * </p>
+ * <p>
+ * An individual Valve <b>MAY</b> perform the following actions, in the specified order:
+ * </p>
* <ul>
- * <li>Examine and/or modify the properties of the specified Request and
- * Response.
- * <li>Examine the properties of the specified Request, completely generate
- * the corresponding Response, and return control to the caller.
- * <li>Examine the properties of the specified Request and Response, wrap
- * either or both of these objects to supplement their functionality,
- * and pass them on.
- * <li>If the corresponding Response was not generated (and control was not
- * returned, call the next Valve in the pipeline (if there is one) by
- * executing <code>getNext().invoke()</code>.
- * <li>Examine, but not modify, the properties of the resulting Response
- * (which was created by a subsequently invoked Valve or Container).
+ * <li>Examine and/or modify the properties of the specified Request and Response.
+ * <li>Examine the properties of the specified Request, completely generate the corresponding Response, and return
+ * control to the caller.
+ * <li>Examine the properties of the specified Request and Response, wrap either or both of these objects to
+ * supplement their functionality, and pass them on.
+ * <li>If the corresponding Response was not generated (and control was not returned, call the next Valve in the
+ * pipeline (if there is one) by executing <code>getNext().invoke()</code>.
+ * <li>Examine, but not modify, the properties of the resulting Response (which was created by a subsequently
+ * invoked Valve or Container).
* </ul>
- *
- * <p>A Valve <b>MUST NOT</b> do any of the following things:</p>
+ * <p>
+ * A Valve <b>MUST NOT</b> do any of the following things:
+ * </p>
* <ul>
- * <li>Change request properties that have already been used to direct
- * the flow of processing control for this request (for instance,
- * trying to change the virtual host to which a Request should be
- * sent from a pipeline attached to a Host or Context in the
- * standard implementation).
- * <li>Create a completed Response <strong>AND</strong> pass this
- * Request and Response on to the next Valve in the pipeline.
- * <li>Consume bytes from the input stream associated with the Request,
- * unless it is completely generating the response, or wrapping the
- * request before passing it on.
- * <li>Modify the HTTP headers included with the Response after the
- * <code>getNext().invoke()</code> method has returned.
- * <li>Perform any actions on the output stream associated with the
- * specified Response after the <code>getNext().invoke()</code> method has
- * returned.
+ * <li>Change request properties that have already been used to direct the flow of processing control for this
+ * request (for instance, trying to change the virtual host to which a Request should be sent from a pipeline
+ * attached to a Host or Context in the standard implementation).
+ * <li>Create a completed Response <strong>AND</strong> pass this Request and Response on to the next Valve in the
+ * pipeline.
+ * <li>Consume bytes from the input stream associated with the Request, unless it is completely generating the
+ * response, or wrapping the request before passing it on.
+ * <li>Modify the HTTP headers included with the Response after the <code>getNext().invoke()</code> method has
+ * returned.
+ * <li>Perform any actions on the output stream associated with the specified Response after the
+ * <code>getNext().invoke()</code> method has returned.
* </ul>
*
- * @param request The servlet request to be processed
+ * @param request The servlet request to be processed
* @param response The servlet response to be created
*
- * @exception IOException if an input/output error occurs, or is thrown
- * by a subsequently invoked Valve, Filter, or Servlet
- * @exception ServletException if a servlet error occurs, or is thrown
- * by a subsequently invoked Valve, Filter, or Servlet
+ * @exception IOException if an input/output error occurs, or is thrown by a subsequently invoked Valve,
+ * Filter, or Servlet
+ * @exception ServletException if a servlet error occurs, or is thrown by a subsequently invoked Valve, Filter, or
+ * Servlet
*/
- void invoke(Request request, Response response)
- throws IOException, ServletException;
+ void invoke(Request request, Response response) throws IOException, ServletException;
boolean isAsyncSupported();
diff --git a/java/org/apache/catalina/WebResource.java b/java/org/apache/catalina/WebResource.java
index 2c8b05da51..8c50577f6b 100644
--- a/java/org/apache/catalina/WebResource.java
+++ b/java/org/apache/catalina/WebResource.java
@@ -22,8 +22,7 @@ import java.security.cert.Certificate;
import java.util.jar.Manifest;
/**
- * Represents a file or directory within a web application. It borrows heavily
- * from {@link java.io.File}.
+ * Represents a file or directory within a web application. It borrows heavily from {@link java.io.File}.
*/
public interface WebResource {
/**
@@ -32,8 +31,8 @@ public interface WebResource {
long getLastModified();
/**
- * @return the last modified time of this resource in the correct format for
- * the HTTP Last-Modified header as specified by RFC 2616.
+ * @return the last modified time of this resource in the correct format for the HTTP Last-Modified header as
+ * specified by RFC 2616.
*/
String getLastModifiedHttp();
@@ -43,11 +42,9 @@ public interface WebResource {
boolean exists();
/**
- * Indicates if this resource is required for applications to correctly scan
- * the file structure but that does not exist in either the main or any
- * additional {@link WebResourceSet}. For example, if an external
- * directory is mapped to /WEB-INF/lib in an otherwise empty web
- * application, /WEB-INF will be represented as a virtual resource.
+ * Indicates if this resource is required for applications to correctly scan the file structure but that does not
+ * exist in either the main or any additional {@link WebResourceSet}. For example, if an external directory is
+ * mapped to /WEB-INF/lib in an otherwise empty web application, /WEB-INF will be represented as a virtual resource.
*
* @return <code>true</code> for a virtual resource
*/
@@ -89,16 +86,16 @@ public interface WebResource {
boolean canRead();
/**
- * @return The path of this resource relative to the web application root. If the
- * resource is a directory, the return value will end in '/'.
+ * @return The path of this resource relative to the web application root. If the resource is a directory, the
+ * return value will end in '/'.
*/
String getWebappPath();
/**
- * Return the strong ETag if available (currently not supported) else return
- * the weak ETag calculated from the content length and last modified.
+ * Return the strong ETag if available (currently not supported) else return the weak ETag calculated from the
+ * content length and last modified.
*
- * @return The ETag for this resource
+ * @return The ETag for this resource
*/
String getETag();
@@ -117,46 +114,42 @@ public interface WebResource {
/**
* Obtain an InputStream based on the contents of this resource.
*
- * @return An InputStream based on the contents of this resource or
- * <code>null</code> if the resource does not exist or does not
- * represent a file
+ * @return An InputStream based on the contents of this resource or <code>null</code> if the resource does not exist
+ * or does not represent a file
*/
InputStream getInputStream();
/**
- * @return the binary content of this resource or {@code null} if it is not
- * available in a byte[] because, for example, it is too big.
+ * @return the binary content of this resource or {@code null} if it is not available in a byte[] because, for
+ * example, it is too big.
*/
byte[] getContent();
/**
- * @return The time the file was created. If not available, the result of
- * {@link #getLastModified()} will be returned.
+ * @return The time the file was created. If not available, the result of {@link #getLastModified()} will be
+ * returned.
*/
long getCreation();
/**
- * @return a URL to access the resource or <code>null</code> if no such URL
- * is available or if the resource does not exist.
+ * @return a URL to access the resource or <code>null</code> if no such URL is available or if the resource does not
+ * exist.
*/
URL getURL();
/**
- * @return the code base for this resource that will be used when looking up the
- * assigned permissions for the code base in the security policy file when
- * running under a security manager.
+ * @return the code base for this resource that will be used when looking up the assigned permissions for the code
+ * base in the security policy file when running under a security manager.
*/
URL getCodeBase();
/**
- * @return a reference to the WebResourceRoot of which this WebResource is a
- * part.
+ * @return a reference to the WebResourceRoot of which this WebResource is a part.
*/
WebResourceRoot getWebResourceRoot();
/**
- * @return the certificates that were used to sign this resource to verify
- * it or @null if none.
+ * @return the certificates that were used to sign this resource to verify it or @null if none.
*
* @see java.util.jar.JarEntry#getCertificates()
*/
diff --git a/java/org/apache/catalina/WebResourceRoot.java b/java/org/apache/catalina/WebResourceRoot.java
index 36bad52945..fb6b43c002 100644
--- a/java/org/apache/catalina/WebResourceRoot.java
+++ b/java/org/apache/catalina/WebResourceRoot.java
@@ -22,268 +22,214 @@ import java.util.List;
import java.util.Set;
/**
- * Represents the complete set of resources for a web application. The resources
- * for a web application comprise of multiple ResourceSets and when looking for
- * a Resource, the ResourceSets are processed in the following order:
+ * Represents the complete set of resources for a web application. The resources for a web application comprise of
+ * multiple ResourceSets and when looking for a Resource, the ResourceSets are processed in the following order:
* <ol>
- * <li>Pre - Resources defined by the <PreResource> element in the web
- * application's context.xml. Resources will be searched in the order
- * they were specified.</li>
- * <li>Main - The main resources for the web application - i.e. the WAR or the
- * directory containing the expanded WAR</li>
- * <li>JARs - Resource JARs as defined by the Servlet specification. JARs will
- * be searched in the order they were added to the ResourceRoot.</li>
- * <li>Post - Resources defined by the <PostResource> element in the web
- * application's context.xml. Resources will be searched in the order
- * they were specified.</li>
+ * <li>Pre - Resources defined by the <PreResource> element in the web application's context.xml. Resources will
+ * be searched in the order they were specified.</li>
+ * <li>Main - The main resources for the web application - i.e. the WAR or the directory containing the expanded
+ * WAR</li>
+ * <li>JARs - Resource JARs as defined by the Servlet specification. JARs will be searched in the order they were added
+ * to the ResourceRoot.</li>
+ * <li>Post - Resources defined by the <PostResource> element in the web application's context.xml. Resources will
+ * be searched in the order they were specified.</li>
* </ol>
* The following conventions should be noted:
* <ul>
- * <li>Write operations (including delete) will only be applied to the main
- * ResourceSet. The write operation will fail if the presence of a Resource
- * in one of the other ResourceSets effectively makes the operation on the
- * main ResourceSet a NO-OP.</li>
- * <li>A file in a ResourceSet will hide a directory of the same name (and all
- * the contents of that directory) in a ResourceSet that is later in the
- * search order.</li>
- * <li>Only the main ResourceSet may define a META-INF/context.xml since that
- * file defines the Pre- and Post-Resources.</li>
- * <li>As per the Servlet specification, any META-INF or WEB-INF directories in
- * a resource JAR will be ignored.</li>
- * <li>Pre- and Post-Resources may define WEB-INF/lib and WEB-INF/classes in
- * order to make additional libraries and/or classes available to the web
- * application.
+ * <li>Write operations (including delete) will only be applied to the main ResourceSet. The write operation will fail
+ * if the presence of a Resource in one of the other ResourceSets effectively makes the operation on the main
+ * ResourceSet a NO-OP.</li>
+ * <li>A file in a ResourceSet will hide a directory of the same name (and all the contents of that directory) in a
+ * ResourceSet that is later in the search order.</li>
+ * <li>Only the main ResourceSet may define a META-INF/context.xml since that file defines the Pre- and
+ * Post-Resources.</li>
+ * <li>As per the Servlet specification, any META-INF or WEB-INF directories in a resource JAR will be ignored.</li>
+ * <li>Pre- and Post-Resources may define WEB-INF/lib and WEB-INF/classes in order to make additional libraries and/or
+ * classes available to the web application.
* </ul>
- * This mechanism replaces and extends the following features that were present
- * in earlier versions:
+ * This mechanism replaces and extends the following features that were present in earlier versions:
* <ul>
- * <li>Aliases - Replaced by Post-Resources with the addition of
- * support for single files as well as directories
- * and JARs.</li>
- * <li>VirtualWebappLoader - Replaced by Pre- and Post-Resources mapped to
- * WEB-INF/lib and WEB-INF/classes</li>
- * <li>VirtualDirContext - Replaced by Pre- and Post-Resources</li>
- * <li>External repositories - Replaced by Pre- and Post-Resources mapped to
- * WEB-INF/lib and WEB-INF/classes</li>
- * <li>Resource JARs - Same feature but implemented using the same
- * mechanism as all the other additional
- * resources.</li>
+ * <li>Aliases - Replaced by Post-Resources with the addition of support for single files as well as directories and
+ * JARs.</li>
+ * <li>VirtualWebappLoader - Replaced by Pre- and Post-Resources mapped to WEB-INF/lib and WEB-INF/classes</li>
+ * <li>VirtualDirContext - Replaced by Pre- and Post-Resources</li>
+ * <li>External repositories - Replaced by Pre- and Post-Resources mapped to WEB-INF/lib and WEB-INF/classes</li>
+ * <li>Resource JARs - Same feature but implemented using the same mechanism as all the other additional resources.</li>
* </ul>
*/
/*
- * A potential future enhancement is to allow writing to any ResourceSet,
- * not just the main ResourceSet although that adds all sorts complications
- * including:
- * - which ResourceSet to write to
- * - unexpected behaviour when deleting a resource from one ResourceSet since
- * that may unmask a resource in a lower priority ResourceSet so what was a
- * delete looks like a replace with the user having no idea where the 'new'
- * resource came from
- * - how to handle PUT when the target is read-only but it could be written to
- * a higher priority ResourceSet that is read-write
+ * A potential future enhancement is to allow writing to any ResourceSet, not just the main ResourceSet although that
+ * adds all sorts complications including: - which ResourceSet to write to - unexpected behaviour when deleting a
+ * resource from one ResourceSet since that may unmask a resource in a lower priority ResourceSet so what was a delete
+ * looks like a replace with the user having no idea where the 'new' resource came from - how to handle PUT when the
+ * target is read-only but it could be written to a higher priority ResourceSet that is read-write
*/
public interface WebResourceRoot extends Lifecycle {
/**
- * Obtain the object that represents the resource at the given path. Note
- * that the resource at that path may not exist. If the resource does not
- * exist, the WebResource returned will be associated with the main
- * WebResourceSet.
+ * Obtain the object that represents the resource at the given path. Note that the resource at that path may not
+ * exist. If the resource does not exist, the WebResource returned will be associated with the main WebResourceSet.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The object that represents the resource at the given path
+ * @return The object that represents the resource at the given path
*/
WebResource getResource(String path);
/**
- * Obtain the objects that represent the resource at the given path. Note
- * that the resource at that path may not exist. If the resource does not
- * exist, the WebResource returned will be associated with the main
- * WebResourceSet. This will include all matches even if the resource would
- * not normally be accessible (e.g. because it was overridden by another
- * resource)
+ * Obtain the objects that represent the resource at the given path. Note that the resource at that path may not
+ * exist. If the resource does not exist, the WebResource returned will be associated with the main WebResourceSet.
+ * This will include all matches even if the resource would not normally be accessible (e.g. because it was
+ * overridden by another resource)
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The objects that represents the resource at the given path
+ * @return The objects that represents the resource at the given path
*/
WebResource[] getResources(String path);
/**
- * Obtain the object that represents the class loader resource at the given
- * path. WEB-INF/classes is always searched prior to searching JAR files in
- * WEB-INF/lib. The search order for JAR files will be consistent across
- * subsequent calls to this method until the web application is reloaded. No
- * guarantee is made as to what the search order for JAR files may be.
+ * Obtain the object that represents the class loader resource at the given path. WEB-INF/classes is always searched
+ * prior to searching JAR files in WEB-INF/lib. The search order for JAR files will be consistent across subsequent
+ * calls to this method until the web application is reloaded. No guarantee is made as to what the search order for
+ * JAR files may be.
*
- * @param path The path of the class loader resource of interest relative
- * to the the root of class loader resources for this web
- * application.
+ * @param path The path of the class loader resource of interest relative to the the root of class loader resources
+ * for this web application.
*
- * @return The object that represents the class loader resource at the
- * given path
+ * @return The object that represents the class loader resource at the given path
*/
WebResource getClassLoaderResource(String path);
/**
- * Obtain the objects that represent the class loader resource at the given
- * path. Note that the resource at that path may not exist. If the path does
- * not exist, the WebResource returned will be associated with the main
- * WebResourceSet. This will include all matches even if the resource would
- * not normally be accessible (e.g. because it was overridden by another
- * resource)
+ * Obtain the objects that represent the class loader resource at the given path. Note that the resource at that
+ * path may not exist. If the path does not exist, the WebResource returned will be associated with the main
+ * WebResourceSet. This will include all matches even if the resource would not normally be accessible (e.g. because
+ * it was overridden by another resource)
*
- * @param path The path for the class loader resource of interest relative
- * to the root of the class loader resources for the web
- * application. It must start with '/'.
+ * @param path The path for the class loader resource of interest relative to the root of the class loader resources
+ * for the web application. It must start with '/'.
*
- * @return The objects that represents the class loader resources at the
- * given path. There will always be at least one element although
- * that element may represent a resource that is not present.
+ * @return The objects that represents the class loader resources at the given path. There will always be at least
+ * one element although that element may represent a resource that is not present.
*/
WebResource[] getClassLoaderResources(String path);
/**
- * Obtain the list of the names of all of the files and directories located
- * in the specified directory.
+ * Obtain the list of the names of all of the files and directories located in the specified directory.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The list of resources. If path does not refer to a directory
- * then a zero length array will be returned.
+ * @return The list of resources. If path does not refer to a directory then a zero length array will be returned.
*/
String[] list(String path);
/**
- * Obtain the Set of the web applications pathnames of all of the files and
- * directories located in the specified directory. Paths representing
- * directories will end with a '/' character.
+ * Obtain the Set of the web applications pathnames of all of the files and directories located in the specified
+ * directory. Paths representing directories will end with a '/' character.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The Set of resources. If path does not refer to a directory
- * then null will be returned.
+ * @return The Set of resources. If path does not refer to a directory then null will be returned.
*/
Set<String> listWebAppPaths(String path);
/**
* Obtain the list of all of the WebResources in the specified directory.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The list of resources. If path does not refer to a directory
- * then a zero length array will be returned.
+ * @return The list of resources. If path does not refer to a directory then a zero length array will be returned.
*/
WebResource[] listResources(String path);
/**
* Create a new directory at the given path.
*
- * @param path The path for the new resource to create relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the new resource to create relative to the root of the web application. It must start
+ * with '/'.
*
- * @return <code>true</code> if the directory was created, otherwise
- * <code>false</code>
+ * @return <code>true</code> if the directory was created, otherwise <code>false</code>
*/
boolean mkdir(String path);
/**
- * Create a new resource at the requested path using the provided
- * InputStream.
+ * Create a new resource at the requested path using the provided InputStream.
*
- * @param path The path to be used for the new Resource. It is relative
- * to the root of the web application and must start with
- * '/'.
- * @param is The InputStream that will provide the content for the
- * new Resource.
- * @param overwrite If <code>true</code> and the resource already exists it
- * will be overwritten. If <code>false</code> and the
- * resource already exists the write will fail.
+ * @param path The path to be used for the new Resource. It is relative to the root of the web application and
+ * must start with '/'.
+ * @param is The InputStream that will provide the content for the new Resource.
+ * @param overwrite If <code>true</code> and the resource already exists it will be overwritten. If
+ * <code>false</code> and the resource already exists the write will fail.
*
- * @return <code>true</code> if and only if the new Resource is written
+ * @return <code>true</code> if and only if the new Resource is written
*/
boolean write(String path, InputStream is, boolean overwrite);
/**
- * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot}
- * based on the provided parameters.
+ * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot} based on the provided parameters.
*
- * @param type The type of {@link WebResourceSet} to create
- * @param webAppMount The path within the web application that the
- * resources should be published at. It must start
- * with '/'.
- * @param url The URL of the resource (must locate a JAR, file or
- * directory)
- * @param internalPath The path within the resource where the content is to
- * be found. It must start with '/'.
+ * @param type The type of {@link WebResourceSet} to create
+ * @param webAppMount The path within the web application that the resources should be published at. It must start
+ * with '/'.
+ * @param url The URL of the resource (must locate a JAR, file or directory)
+ * @param internalPath The path within the resource where the content is to be found. It must start with '/'.
*/
- void createWebResourceSet(ResourceSetType type, String webAppMount, URL url,
- String internalPath);
+ void createWebResourceSet(ResourceSetType type, String webAppMount, URL url, String internalPath);
/**
- * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot}
- * based on the provided parameters.
+ * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot} based on the provided parameters.
*
- * @param type The type of {@link WebResourceSet} to create
- * @param webAppMount The path within the web application that the
- * resources should be published at. It must start
- * with '/'.
- * @param base The location of the resources
- * @param archivePath The path within the resource to the archive where
- * the content is to be found. If there is no
- * archive then this should be <code>null</code>.
- * @param internalPath The path within the archive (or the resource if the
- * archivePath is <code>null</code> where the
- * content is to be found. It must start with '/'.
+ * @param type The type of {@link WebResourceSet} to create
+ * @param webAppMount The path within the web application that the resources should be published at. It must start
+ * with '/'.
+ * @param base The location of the resources
+ * @param archivePath The path within the resource to the archive where the content is to be found. If there is no
+ * archive then this should be <code>null</code>.
+ * @param internalPath The path within the archive (or the resource if the archivePath is <code>null</code> where
+ * the content is to be found. It must start with '/'.
*/
- void createWebResourceSet(ResourceSetType type, String webAppMount,
- String base, String archivePath, String internalPath);
+ void createWebResourceSet(ResourceSetType type, String webAppMount, String base, String archivePath,
+ String internalPath);
/**
- * Adds the provided WebResourceSet to this web application as a 'Pre'
- * resource.
+ * Adds the provided WebResourceSet to this web application as a 'Pre' resource.
*
* @param webResourceSet the resource set to use
*/
void addPreResources(WebResourceSet webResourceSet);
/**
- * @return the list of WebResourceSet configured to this web application
- * as a 'Pre' resource.
+ * @return the list of WebResourceSet configured to this web application as a 'Pre' resource.
*/
WebResourceSet[] getPreResources();
/**
- * Adds the provided WebResourceSet to this web application as a 'Jar'
- * resource.
+ * Adds the provided WebResourceSet to this web application as a 'Jar' resource.
*
* @param webResourceSet the resource set to use
*/
void addJarResources(WebResourceSet webResourceSet);
/**
- * @return the list of WebResourceSet configured to this web application
- * as a 'Jar' resource.
+ * @return the list of WebResourceSet configured to this web application as a 'Jar' resource.
*/
WebResourceSet[] getJarResources();
/**
- * Adds the provided WebResourceSet to this web application as a 'Post'
- * resource.
+ * Adds the provided WebResourceSet to this web application as a 'Post' resource.
*
* @param webResourceSet the resource set to use
*/
void addPostResources(WebResourceSet webResourceSet);
/**
- * @return the list of WebResourceSet configured to this web application
- * as a 'Post' resource.
+ * @return the list of WebResourceSet configured to this web application as a 'Post' resource.
*/
WebResourceSet[] getPostResources();
@@ -302,22 +248,21 @@ public interface WebResourceRoot extends Lifecycle {
/**
* Configure if this resources allow the use of symbolic links.
*
- * @param allowLinking <code>true</code> if symbolic links are allowed.
+ * @param allowLinking <code>true</code> if symbolic links are allowed.
*/
void setAllowLinking(boolean allowLinking);
/**
* Determine if this resources allow the use of symbolic links.
*
- * @return <code>true</code> if symbolic links are allowed
+ * @return <code>true</code> if symbolic links are allowed
*/
boolean getAllowLinking();
/**
* Set whether or not caching is permitted for this web application.
*
- * @param cachingAllowed <code>true</code> to enable caching, else
- * <code>false</code>
+ * @param cachingAllowed <code>true</code> to enable caching, else <code>false</code>
*/
void setCachingAllowed(boolean cachingAllowed);
@@ -329,66 +274,60 @@ public interface WebResourceRoot extends Lifecycle {
/**
* Set the Time-To-Live (TTL) for cache entries.
*
- * @param ttl TTL in milliseconds
+ * @param ttl TTL in milliseconds
*/
void setCacheTtl(long ttl);
/**
* Get the Time-To-Live (TTL) for cache entries.
*
- * @return TTL in milliseconds
+ * @return TTL in milliseconds
*/
long getCacheTtl();
/**
* Set the maximum permitted size for the cache.
*
- * @param cacheMaxSize Maximum cache size in kilobytes
+ * @param cacheMaxSize Maximum cache size in kilobytes
*/
void setCacheMaxSize(long cacheMaxSize);
/**
* Get the maximum permitted size for the cache.
*
- * @return Maximum cache size in kilobytes
+ * @return Maximum cache size in kilobytes
*/
long getCacheMaxSize();
/**
- * Set the maximum permitted size for a single object in the cache. Note
- * that the maximum size in bytes may not exceed {@link Integer#MAX_VALUE}.
+ * Set the maximum permitted size for a single object in the cache. Note that the maximum size in bytes may not
+ * exceed {@link Integer#MAX_VALUE}.
*
- * @param cacheObjectMaxSize Maximum size for a single cached object in
- * kilobytes
+ * @param cacheObjectMaxSize Maximum size for a single cached object in kilobytes
*/
void setCacheObjectMaxSize(int cacheObjectMaxSize);
/**
- * Get the maximum permitted size for a single object in the cache. Note
- * that the maximum size in bytes may not exceed {@link Integer#MAX_VALUE}.
+ * Get the maximum permitted size for a single object in the cache. Note that the maximum size in bytes may not
+ * exceed {@link Integer#MAX_VALUE}.
*
- * @return Maximum size for a single cached object in kilobytes
+ * @return Maximum size for a single cached object in kilobytes
*/
int getCacheObjectMaxSize();
/**
- * Controls whether the track locked files feature is enabled. If enabled,
- * all calls to methods that return objects that lock a file and need to be
- * closed to release that lock (e.g. {@link WebResource#getInputStream()}
- * will perform a number of additional tasks.
+ * Controls whether the track locked files feature is enabled. If enabled, all calls to methods that return objects
+ * that lock a file and need to be closed to release that lock (e.g. {@link WebResource#getInputStream()} will
+ * perform a number of additional tasks.
* <ul>
- * <li>The stack trace at the point where the method was called will be
- * recorded and associated with the returned object.</li>
- * <li>The returned object will be wrapped so that the point where close()
- * (or equivalent) is called to release the resources can be detected.
- * Tracking of the object will cease once the resources have been
- * released.</li>
- * <li>All remaining locked resources on web application shutdown will be
- * logged and then closed.</li>
+ * <li>The stack trace at the point where the method was called will be recorded and associated with the returned
+ * object.</li>
+ * <li>The returned object will be wrapped so that the point where close() (or equivalent) is called to release the
+ * resources can be detected. Tracking of the object will cease once the resources have been released.</li>
+ * <li>All remaining locked resources on web application shutdown will be logged and then closed.</li>
* </ul>
*
- * @param trackLockedFiles {@code true} to enable it, {@code false} to
- * disable it
+ * @param trackLockedFiles {@code true} to enable it, {@code false} to disable it
*/
void setTrackLockedFiles(boolean trackLockedFiles);
@@ -421,46 +360,43 @@ public interface WebResourceRoot extends Lifecycle {
ArchiveIndexStrategy getArchiveIndexStrategyEnum();
/**
- * This method will be invoked by the context on a periodic basis and allows
- * the implementation a method that executes periodic tasks, such as purging
- * expired cache entries.
+ * This method will be invoked by the context on a periodic basis and allows the implementation a method that
+ * executes periodic tasks, such as purging expired cache entries.
*/
void backgroundProcess();
/**
- * Add a specified resource to track to be able to later release
- * resources on stop.
+ * Add a specified resource to track to be able to later release resources on stop.
+ *
* @param trackedResource the resource that will be tracked
*/
void registerTrackedResource(TrackedWebResource trackedResource);
/**
* Stop tracking specified resource, once it no longer needs to free resources.
+ *
* @param trackedResource the resource that was tracked
*/
void deregisterTrackedResource(TrackedWebResource trackedResource);
/**
- * @return the set of {@link WebResourceSet#getBaseUrl()} for all
- * {@link WebResourceSet}s used by this root.
+ * @return the set of {@link WebResourceSet#getBaseUrl()} for all {@link WebResourceSet}s used by this root.
*/
List<URL> getBaseUrls();
/**
- * Implementations may cache some information to improve performance. This
- * method triggers the clean-up of those resources.
+ * Implementations may cache some information to improve performance. This method triggers the clean-up of those
+ * resources.
*/
void gc();
/**
* Obtain the current caching strategy.
* <p>
- * The default implementation returns {@code null}. Sub-classes wishing to
- * utilise a {@link CacheStrategy} should provide an appropriate
- * implementation.
+ * The default implementation returns {@code null}. Sub-classes wishing to utilise a {@link CacheStrategy} should
+ * provide an appropriate implementation.
*
- * @return the current caching strategy or {@code null} if no strategy has
- * been configured
+ * @return the current caching strategy or {@code null} if no strategy has been configured
*/
default CacheStrategy getCacheStrategy() {
return null;
@@ -469,8 +405,8 @@ public interface WebResourceRoot extends Lifecycle {
/**
* Set the current caching strategy.
* <p>
- * The default implementation is a NO-OP. Sub-classes wishing to utilise a
- * {@link CacheStrategy} should provide an appropriate implementation.
+ * The default implementation is a NO-OP. Sub-classes wishing to utilise a {@link CacheStrategy} should provide an
+ * appropriate implementation.
*
* @param strategy The new strategy to use or {@code null} for no strategy
*/
@@ -513,14 +449,11 @@ public interface WebResourceRoot extends Lifecycle {
interface CacheStrategy {
/**
- * Should the result of looking up the resource at the given path be
- * excluded from caching?
+ * Should the result of looking up the resource at the given path be excluded from caching?
*
- * @param path The path to check against the strategy to see if the
- * result should be cached
+ * @param path The path to check against the strategy to see if the result should be cached
*
- * @return {@code true} if the result should not be cached, otherwise
- * {@code false}
+ * @return {@code true} if the result should not be cached, otherwise {@code false}
*/
boolean noCache(String path);
}
diff --git a/java/org/apache/catalina/WebResourceSet.java b/java/org/apache/catalina/WebResourceSet.java
index 9d71cd0719..1d2729cfea 100644
--- a/java/org/apache/catalina/WebResourceSet.java
+++ b/java/org/apache/catalina/WebResourceSet.java
@@ -21,107 +21,93 @@ import java.net.URL;
import java.util.Set;
/**
- * Represents a set of resources that are part of a web application. Examples
- * include a directory structure, a resources JAR and a WAR file.
+ * Represents a set of resources that are part of a web application. Examples include a directory structure, a resources
+ * JAR and a WAR file.
*/
public interface WebResourceSet extends Lifecycle {
/**
- * Obtain the object that represents the resource at the given path. Note
- * the resource at that path may not exist.
+ * Obtain the object that represents the resource at the given path. Note the resource at that path may not exist.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The object that represents the resource at the given path
+ * @return The object that represents the resource at the given path
*/
WebResource getResource(String path);
/**
- * Obtain the list of the names of all of the files and directories located
- * in the specified directory.
+ * Obtain the list of the names of all of the files and directories located in the specified directory.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The list of resources. If path does not refer to a directory
- * then a zero length array will be returned.
+ * @return The list of resources. If path does not refer to a directory then a zero length array will be returned.
*/
String[] list(String path);
/**
- * Obtain the Set of the web applications pathnames of all of the files and
- * directories located in the specified directory. Paths representing
- * directories will end with a "/" character.
+ * Obtain the Set of the web applications pathnames of all of the files and directories located in the specified
+ * directory. Paths representing directories will end with a "/" character.
*
- * @param path The path for the resource of interest relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the resource of interest relative to the root of the web application. It must start with
+ * '/'.
*
- * @return The Set of resources. If path does not refer to a directory
- * then an empty set will be returned.
+ * @return The Set of resources. If path does not refer to a directory then an empty set will be returned.
*/
Set<String> listWebAppPaths(String path);
/**
* Create a new directory at the given path.
*
- * @param path The path for the new resource to create relative to the root
- * of the web application. It must start with '/'.
+ * @param path The path for the new resource to create relative to the root of the web application. It must start
+ * with '/'.
*
- * @return <code>true</code> if the directory was created, otherwise
- * <code>false</code>
+ * @return <code>true</code> if the directory was created, otherwise <code>false</code>
*/
boolean mkdir(String path);
/**
- * Create a new resource at the requested path using the provided
- * InputStream.
- *
- * @param path The path to be used for the new Resource. It is relative
- * to the root of the web application and must start with
- * '/'.
- * @param is The InputStream that will provide the content for the
- * new Resource.
- * @param overwrite If <code>true</code> and the resource already exists it
- * will be overwritten. If <code>false</code> and the
- * resource already exists the write will fail.
- *
- * @return <code>true</code> if and only if the new Resource is written
+ * Create a new resource at the requested path using the provided InputStream.
+ *
+ * @param path The path to be used for the new Resource. It is relative to the root of the web application and
+ * must start with '/'.
+ * @param is The InputStream that will provide the content for the new Resource.
+ * @param overwrite If <code>true</code> and the resource already exists it will be overwritten. If
+ * <code>false</code> and the resource already exists the write will fail.
+ *
+ * @return <code>true</code> if and only if the new Resource is written
*/
boolean write(String path, InputStream is, boolean overwrite);
void setRoot(WebResourceRoot root);
/**
- * Should resources returned by this resource set only be included in any
- * results when the lookup is explicitly looking for class loader resources.
- * i.e. should these resources be excluded from look ups that are explicitly
+ * Should resources returned by this resource set only be included in any results when the lookup is explicitly
+ * looking for class loader resources. i.e. should these resources be excluded from look ups that are explicitly
* looking for static (non-class loader) resources.
*
- * @return <code>true</code> if these resources should only be used for
- * class loader resource lookups, otherwise <code>false</code>
+ * @return <code>true</code> if these resources should only be used for class loader resource lookups, otherwise
+ * <code>false</code>
*/
boolean getClassLoaderOnly();
void setClassLoaderOnly(boolean classLoaderOnly);
/**
- * Should resources returned by this resource set only be included in any
- * results when the lookup is explicitly looking for static (non-class
- * loader) resources. i.e. should these resources be excluded from look ups
- * that are explicitly looking for class loader resources.
- *
- * @return <code>true</code> if these resources should only be used for
- * static (non-class loader) resource lookups, otherwise
- * <code>false</code>
+ * Should resources returned by this resource set only be included in any results when the lookup is explicitly
+ * looking for static (non-class loader) resources. i.e. should these resources be excluded from look ups that are
+ * explicitly looking for class loader resources.
+ *
+ * @return <code>true</code> if these resources should only be used for static (non-class loader) resource lookups,
+ * otherwise <code>false</code>
*/
boolean getStaticOnly();
void setStaticOnly(boolean staticOnly);
/**
- * Obtain the base URL for this set of resources. One of the uses of this is
- * to grant read permissions to the resources when running under a security
- * manager.
+ * Obtain the base URL for this set of resources. One of the uses of this is to grant read permissions to the
+ * resources when running under a security manager.
*
* @return The base URL for this set of resources
*/
@@ -130,27 +116,23 @@ public interface WebResourceSet extends Lifecycle {
/**
* Configures whether or not this set of resources is read-only.
*
- * @param readOnly <code>true</code> if this set of resources should be
- * configured to be read-only
+ * @param readOnly <code>true</code> if this set of resources should be configured to be read-only
*
- * @throws IllegalArgumentException if an attempt is made to configure a
- * {@link WebResourceSet} that is hard-coded to be read-only as
- * writable
+ * @throws IllegalArgumentException if an attempt is made to configure a {@link WebResourceSet} that is hard-coded
+ * to be read-only as writable
*/
void setReadOnly(boolean readOnly);
/**
- * Obtains the current value of the read-only setting for this set of
- * resources.
+ * Obtains the current value of the read-only setting for this set of resources.
*
- * @return <code>true</code> if this set of resources is configured to be
- * read-only, otherwise <code>false</code>
+ * @return <code>true</code> if this set of resources is configured to be read-only, otherwise <code>false</code>
*/
boolean isReadOnly();
/**
- * Implementations may cache some information to improve performance. This
- * method triggers the clean-up of those resources.
+ * Implementations may cache some information to improve performance. This method triggers the clean-up of those
+ * resources.
*/
void gc();
}
diff --git a/java/org/apache/catalina/Wrapper.java b/java/org/apache/catalina/Wrapper.java
index 0803161df9..63e4dcf7a0 100644
--- a/java/org/apache/catalina/Wrapper.java
+++ b/java/org/apache/catalina/Wrapper.java
@@ -24,21 +24,17 @@ import jakarta.servlet.UnavailableException;
/**
- * A <b>Wrapper</b> is a Container that represents an individual servlet
- * definition from the deployment descriptor of the web application. It
- * provides a convenient mechanism to use Interceptors that see every single
- * request to the servlet represented by this definition.
+ * A <b>Wrapper</b> is a Container that represents an individual servlet definition from the deployment descriptor of
+ * the web application. It provides a convenient mechanism to use Interceptors that see every single request to the
+ * servlet represented by this definition.
* <p>
- * Implementations of Wrapper are responsible for managing the servlet life
- * cycle for their underlying servlet class, including calling init() and
- * destroy() at appropriate times.
+ * Implementations of Wrapper are responsible for managing the servlet life cycle for their underlying servlet class,
+ * including calling init() and destroy() at appropriate times.
* <p>
- * The parent Container attached to a Wrapper will generally be an
- * implementation of Context, representing the servlet context (and
- * therefore the web application) within which this servlet executes.
+ * The parent Container attached to a Wrapper will generally be an implementation of Context, representing the servlet
+ * context (and therefore the web application) within which this servlet executes.
* <p>
- * Child Containers are not allowed on Wrapper implementations, so the
- * <code>addChild()</code> method should throw an
+ * Child Containers are not allowed on Wrapper implementations, so the <code>addChild()</code> method should throw an
* <code>IllegalArgumentException</code>.
*
* @author Craig R. McClanahan
@@ -59,20 +55,18 @@ public interface Wrapper extends Container {
/**
- * @return the available date/time for this servlet, in milliseconds since
- * the epoch. If this date/time is in the future, any request for this
- * servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero,
- * the servlet is currently available. A value equal to Long.MAX_VALUE
- * is considered to mean that unavailability is permanent.
+ * @return the available date/time for this servlet, in milliseconds since the epoch. If this date/time is in the
+ * future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. If it is zero, the
+ * servlet is currently available. A value equal to Long.MAX_VALUE is considered to mean that
+ * unavailability is permanent.
*/
long getAvailable();
/**
- * Set the available date/time for this servlet, in milliseconds since the
- * epoch. If this date/time is in the future, any request for this servlet
- * will return an SC_SERVICE_UNAVAILABLE error. A value equal to
- * Long.MAX_VALUE is considered to mean that unavailability is permanent.
+ * Set the available date/time for this servlet, in milliseconds since the epoch. If this date/time is in the
+ * future, any request for this servlet will return an SC_SERVICE_UNAVAILABLE error. A value equal to Long.MAX_VALUE
+ * is considered to mean that unavailability is permanent.
*
* @param available The new available date/time
*/
@@ -80,15 +74,13 @@ public interface Wrapper extends Container {
/**
- * @return the load-on-startup order value (negative value means
- * load on first call).
+ * @return the load-on-startup order value (negative value means load on first call).
*/
int getLoadOnStartup();
/**
- * Set the load-on-startup order value (negative value means
- * load on first call).
+ * Set the load-on-startup order value (negative value means load on first call).
*
* @param value New load-on-startup value
*/
@@ -124,14 +116,10 @@ public interface Wrapper extends Container {
/**
- * Gets the names of the methods supported by the underlying servlet.
+ * Gets the names of the methods supported by the underlying servlet. This is the same set of methods included in
+ * the Allow response header in response to an OPTIONS request method processed by the underlying servlet.
*
- * This is the same set of methods included in the Allow response header
- * in response to an OPTIONS request method processed by the underlying
- * servlet.
- *
- * @return Array of names of the methods supported by the underlying
- * servlet
+ * @return Array of names of the methods supported by the underlying servlet
*
* @throws ServletException If the target servlet cannot be loaded
*/
@@ -163,7 +151,7 @@ public interface Wrapper extends Container {
/**
* Add a new servlet initialization parameter for this servlet.
*
- * @param name Name of this initialization parameter to add
+ * @param name Name of this initialization parameter to add
* @param value Value of this initialization parameter to add
*/
void addInitParameter(String name, String value);
@@ -178,8 +166,7 @@ public interface Wrapper extends Container {
/**
- * Add a new security role reference record to the set of records for
- * this servlet.
+ * Add a new security role reference record to the set of records for this servlet.
*
* @param name Role name used within this servlet
* @param link Role name used within the web application
@@ -188,13 +175,12 @@ public interface Wrapper extends Container {
/**
- * Allocate an initialized instance of this Servlet that is ready to have
- * its <code>service()</code> method called. The previously initialized
- * instance may be returned immediately.
+ * Allocate an initialized instance of this Servlet that is ready to have its <code>service()</code> method called.
+ * The previously initialized instance may be returned immediately.
*
- * @exception ServletException if the Servlet init() method threw
- * an exception
+ * @exception ServletException if the Servlet init() method threw an exception
* @exception ServletException if a loading error occurs
+ *
* @return a new Servlet instance
*/
Servlet allocate() throws ServletException;
@@ -211,8 +197,7 @@ public interface Wrapper extends Container {
/**
- * @return the value for the specified initialization parameter name,
- * if any; otherwise return <code>null</code>.
+ * @return the value for the specified initialization parameter name, if any; otherwise return <code>null</code>.
*
* @param name Name of the requested initialization parameter
*/
@@ -220,8 +205,7 @@ public interface Wrapper extends Container {
/**
- * @return the names of all defined initialization parameters for this
- * servlet.
+ * @return the names of all defined initialization parameters for this servlet.
*/
String[] findInitParameters();
@@ -233,8 +217,8 @@ public interface Wrapper extends Container {
/**
- * @return the security role link for the specified security role
- * reference name, if any; otherwise return <code>null</code>.
+ * @return the security role link for the specified security role reference name, if any; otherwise return
+ * <code>null</code>.
*
* @param name Security role reference used within this servlet
*/
@@ -242,8 +226,8 @@ public interface Wrapper extends Container {
/**
- * @return the set of security role reference names associated with
- * this servlet, if any; otherwise return a zero-length array.
+ * @return the set of security role reference names associated with this servlet, if any; otherwise return a
+ * zero-length array.
*/
String[] findSecurityReferences();
@@ -255,13 +239,12 @@ public interface Wrapper extends Container {
/**
- * Load and initialize an instance of this Servlet, if there is not already
- * at least one initialized instance. This can be used, for example, to
- * load Servlets that are marked in the deployment descriptor to be loaded
- * at server startup time.
+ * Load and initialize an instance of this Servlet, if there is not already at least one initialized instance. This
+ * can be used, for example, to load Servlets that are marked in the deployment descriptor to be loaded at server
+ * startup time.
*
- * @exception ServletException if the Servlet init() method threw
- * an exception or if some other loading problem occurs
+ * @exception ServletException if the Servlet init() method threw an exception or if some other loading problem
+ * occurs
*/
void load() throws ServletException;
@@ -291,21 +274,18 @@ public interface Wrapper extends Container {
/**
- * Process an UnavailableException, marking this Servlet as unavailable
- * for the specified amount of time.
+ * Process an UnavailableException, marking this Servlet as unavailable for the specified amount of time.
*
- * @param unavailable The exception that occurred, or <code>null</code>
- * to mark this Servlet as permanently unavailable
+ * @param unavailable The exception that occurred, or <code>null</code> to mark this Servlet as permanently
+ * unavailable
*/
void unavailable(UnavailableException unavailable);
/**
- * Unload all initialized instances of this servlet, after calling the
- * <code>destroy()</code> method for each instance. This can be used,
- * for example, prior to shutting down the entire servlet engine, or
- * prior to reloading all of the classes from the Loader associated with
- * our Loader's repository.
+ * Unload all initialized instances of this servlet, after calling the <code>destroy()</code> method for each
+ * instance. This can be used, for example, prior to shutting down the entire servlet engine, or prior to reloading
+ * all of the classes from the Loader associated with our Loader's repository.
*
* @exception ServletException if an unload error occurs
*/
@@ -313,25 +293,22 @@ public interface Wrapper extends Container {
/**
- * @return the multi-part configuration for the associated Servlet. If no
- * multi-part configuration has been defined, then <code>null</code> will be
- * returned.
+ * @return the multi-part configuration for the associated Servlet. If no multi-part configuration has been defined,
+ * then <code>null</code> will be returned.
*/
MultipartConfigElement getMultipartConfigElement();
/**
- * Set the multi-part configuration for the associated Servlet. To clear the
- * multi-part configuration specify <code>null</code> as the new value.
+ * Set the multi-part configuration for the associated Servlet. To clear the multi-part configuration specify
+ * <code>null</code> as the new value.
*
* @param multipartConfig The configuration associated with the Servlet
*/
- void setMultipartConfigElement(
- MultipartConfigElement multipartConfig);
+ void setMultipartConfigElement(MultipartConfigElement multipartConfig);
/**
- * Does the associated Servlet support async processing? Defaults to
- * <code>false</code>.
+ * Does the associated Servlet support async processing? Defaults to <code>false</code>.
*
* @return <code>true</code> if the Servlet supports async
*/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org