init

java/org/apache/catalina/AccessLog.java

@@ -0,0 +1,108 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.catalina;
+
+import org.apache.catalina.connector.Request;
+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.
+ */
+public interface AccessLog {
+
+    /**
+     * Name of request attribute used to override the remote address recorded by
+     * the AccessLog.
+     */
+    public static final String REMOTE_ADDR_ATTRIBUTE =
+            "org.apache.catalina.AccessLog.RemoteAddr";
+
+    /**
+     * Name of request attribute used to override remote host name recorded by
+     * the AccessLog.
+     */
+    public static final String REMOTE_HOST_ATTRIBUTE =
+            "org.apache.catalina.AccessLog.RemoteHost";
+
+    /**
+     * Name of request attribute used to override the protocol recorded by the
+     * AccessLog.
+     */
+    public static final String PROTOCOL_ATTRIBUTE =
+            "org.apache.catalina.AccessLog.Protocol";
+
+    /**
+     * Name of request attribute used to override the server name recorded by
+     * the AccessLog.
+     */
+    public static final String SERVER_NAME_ATTRIBUTE =
+            "org.apache.catalina.AccessLog.ServerName";
+
+    /**
+     * Name of request attribute used to override the server port recorded by
+     * the AccessLog.
+     */
+    public static final String SERVER_PORT_ATTRIBUTE =
+            "org.apache.catalina.AccessLog.ServerPort";
+
+
+    /**
+     * 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
+     *                  milliseconds (use 0 if not known)
+     */
+    public 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:
+     * <ul>
+     * <li>org.apache.catalina.RemoteAddr</li>
+     * <li>org.apache.catalina.RemoteHost</li>
+     * <li>org.apache.catalina.Protocol</li>
+     * <li>org.apache.catalina.ServerName</li>
+     * <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.
+     */
+    public void setRequestAttributesEnabled(boolean requestAttributesEnabled);
+
+    /**
+     * @see #setRequestAttributesEnabled(boolean)
+     * @return <code>true</code> if the attributes will be logged, otherwise
+     *         <code>false</code>
+     */
+    public boolean getRequestAttributesEnabled();
+}

java/org/apache/catalina/AsyncDispatcher.java

@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+import javax.servlet.ServletRequest;
+import javax.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.
+     * @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
+     */
+    public void dispatch(ServletRequest request, ServletResponse response)
+            throws ServletException, IOException;
+}

java/org/apache/catalina/Authenticator.java

@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServletResponse;
+
+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.
+ *
+ * @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.
+     *
+     * @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).
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public boolean authenticate(Request request, HttpServletResponse response)
+            throws IOException;
+
+    public void login(String userName, String password, Request request)
+            throws ServletException;
+
+    public void logout(Request request);
+}

java/org/apache/catalina/Cluster.java

@@ -0,0 +1,104 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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.
+ *
+ * @author Bip Thelin
+ * @author Remy Maucherat
+ */
+public interface Cluster {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * 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
+     */
+    public String getClusterName();
+
+
+    /**
+     * Set the name of the cluster to join, if no cluster with
+     * this name is present create one.
+     *
+     * @param clusterName The clustername to join
+     */
+    public void setClusterName(String clusterName);
+
+    /**
+     * Set the Container associated with our Cluster
+     *
+     * @param container The Container to use
+     */
+    public void setContainer(Container container);
+
+    /**
+     * Get the Container associated with our Cluster
+     *
+     * @return The Container associated with our Cluster
+     */
+    public Container getContainer();
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * 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
+     *
+     * @return The newly created Manager instance
+     */
+    public Manager createManager(String name);
+
+
+    /**
+     * 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
+     */
+    public void registerManager(Manager manager);
+
+    /**
+     * Removes a manager from the cluster
+     * @param manager Manager
+     */
+    public void removeManager(Manager manager);
+
+    // --------------------------------------------------------- Cluster Wide Deployments
+
+
+    /**
+     * 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.
+     */
+    public void backgroundProcess();
+}

java/org/apache/catalina/Contained.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+/**
+ * <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
+ */
+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
+     */
+    Container getContainer();
+
+
+    /**
+     * 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
+     */
+    void setContainer(Container container);
+}

java/org/apache/catalina/Container.java

@@ -0,0 +1,474 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.beans.PropertyChangeListener;
+import java.io.File;
+
+import javax.management.ObjectName;
+
+import org.apache.catalina.connector.Request;
+import org.apache.catalina.connector.Response;
+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.
+ * <p>
+ * 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>Wrapper</b> - Representation of an individual servlet definition
+ *     (which may support multiple servlet instances if the servlet itself
+ *     implements SingleThreadModel).
+ * </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.
+ * <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:
+ * <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.
+ * </ul>
+ *
+ * @author Craig R. McClanahan
+ * @author Remy Maucherat
+ */
+public interface Container extends Lifecycle {
+
+
+    // ----------------------------------------------------- Manifest Constants
+
+
+    /**
+     * The ContainerEvent event type sent when a child container is added
+     * by <code>addChild()</code>.
+     */
+    public static final String ADD_CHILD_EVENT = "addChild";
+
+
+    /**
+     * The ContainerEvent event type sent when a valve is added
+     * by <code>addValve()</code>, if this Container supports pipelines.
+     */
+    public static final String ADD_VALVE_EVENT = "addValve";
+
+
+    /**
+     * The ContainerEvent event type sent when a child container is removed
+     * by <code>removeChild()</code>.
+     */
+    public static final String REMOVE_CHILD_EVENT = "removeChild";
+
+
+    /**
+     * The ContainerEvent event type sent when a valve is removed
+     * by <code>removeValve()</code>, if this Container supports pipelines.
+     */
+    public static final String REMOVE_VALVE_EVENT = "removeValve";
+
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * 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>.
+     */
+    public Log getLogger();
+
+
+    /**
+     * Return the logger name that the container will use.
+     * @return the abbreviated name of this container for logging messages
+     */
+    public String getLogName();
+
+
+    /**
+     * Obtain the JMX name for this container.
+     *
+     * @return the JMX name associated with this container.
+     */
+    public ObjectName getObjectName();
+
+
+    /**
+     * Obtain the JMX domain under which this container will be / has been
+     * registered.
+     *
+     * @return The JMX domain name
+     */
+    public String getDomain();
+
+
+    /**
+     * 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
+     *
+     */
+    public String getMBeanKeyProperties();
+
+
+    /**
+     * Return the Pipeline object that manages the Valves associated with
+     * this Container.
+     *
+     * @return The Pipeline
+     */
+    public Pipeline getPipeline();
+
+
+    /**
+     * 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>.
+     */
+    public Cluster getCluster();
+
+
+    /**
+     * Set the Cluster with which this Container is associated.
+     *
+     * @param cluster the Cluster with which this Container is associated.
+     */
+    public void setCluster(Cluster cluster);
+
+
+    /**
+     * 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.
+     */
+    public int getBackgroundProcessorDelay();
+
+
+    /**
+     * 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
+     */
+    public 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 The human readable name of this container.
+     */
+    public String getName();
+
+
+    /**
+     * 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)
+     */
+    public void setName(String name);
+
+
+    /**
+     * 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>.
+     */
+    public 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.
+     *
+     * @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
+     */
+    public void setParent(Container container);
+
+
+    /**
+     * 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.
+     */
+    public 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.
+     *
+     * @param parent The new parent class loader
+     */
+    public void setParentClassLoader(ClassLoader parent);
+
+
+    /**
+     * 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>.
+     */
+    public Realm getRealm();
+
+
+    /**
+     * Set the Realm with which this Container is associated.
+     *
+     * @param realm The newly associated Realm
+     */
+    public void setRealm(Realm realm);
+
+
+    // --------------------------------------------------------- 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.
+     */
+    public 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
+     *
+     * @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
+     */
+    public void addChild(Container child);
+
+
+    /**
+     * Add a container event listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addContainerListener(ContainerListener listener);
+
+
+    /**
+     * Add a property change listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addPropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * Obtain a child Container by name.
+     *
+     * @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.
+     */
+    public Container findChild(String name);
+
+
+    /**
+     * 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.
+     */
+    public Container[] findChildren();
+
+
+    /**
+     * 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.
+     */
+    public ContainerListener[] findContainerListeners();
+
+
+    /**
+     * Remove an existing child Container from association with this parent
+     * Container.
+     *
+     * @param child Existing child Container to be removed
+     */
+    public void removeChild(Container child);
+
+
+    /**
+     * Remove a container event listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removeContainerListener(ContainerListener listener);
+
+
+    /**
+     * Remove a property change listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removePropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * 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
+     */
+    public void fireContainerEvent(String type, Object data);
+
+
+    /**
+     * 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
+     */
+    public 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.
+     *
+     * @return The AccessLog to use for a request/response destined for this
+     *         container
+     */
+    public 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.
+     *
+     * @return The currently configured number of threads used to start/stop
+     *         children associated with this container
+     */
+    public 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
+     */
+    public void setStartStopThreads(int startStopThreads);
+
+
+    /**
+     * Obtain the location of CATALINA_BASE.
+     *
+     * @return  The location of CATALINA_BASE.
+     */
+    public File getCatalinaBase();
+
+
+    /**
+     * Obtain the location of CATALINA_HOME.
+     *
+     * @return The location of CATALINA_HOME.
+     */
+    public File getCatalinaHome();
+}

java/org/apache/catalina/ContainerEvent.java

@@ -0,0 +1,96 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.util.EventObject;
+
+/**
+ * General event for notifying listeners of significant changes on a Container.
+ *
+ * @author Craig R. McClanahan
+ */
+public final class ContainerEvent extends EventObject {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * The event data associated with this event.
+     */
+    private final Object data;
+
+
+    /**
+     * The event type this instance represents.
+     */
+    private final String type;
+
+
+    /**
+     * Construct a new ContainerEvent with the specified parameters.
+     *
+     * @param container Container on which this event occurred
+     * @param type Event type
+     * @param data Event data
+     */
+    public ContainerEvent(Container container, String type, Object data) {
+        super(container);
+        this.type = type;
+        this.data = data;
+    }
+
+
+    /**
+     * Return the event data of this event.
+     *
+     * @return The data, if any, associated with this event.
+     */
+    public Object getData() {
+        return this.data;
+    }
+
+
+    /**
+     * Return the Container on which this event occurred.
+     *
+     * @return The Container on which this event occurred.
+     */
+    public Container getContainer() {
+        return (Container) getSource();
+    }
+
+
+    /**
+     * 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.
+     */
+    public String getType() {
+        return this.type;
+    }
+
+
+    /**
+     * Return a string representation of this event.
+     */
+    @Override
+    public String toString() {
+        return "ContainerEvent['" + getContainer() + "','" +
+                getType() + "','" + getData() + "']";
+    }
+}

java/org/apache/catalina/ContainerListener.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package 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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface ContainerListener {
+
+
+    /**
+     * Acknowledge the occurrence of the specified event.
+     *
+     * @param event ContainerEvent that has occurred
+     */
+    public void containerEvent(ContainerEvent event);
+
+
+}

java/org/apache/catalina/ContainerServlet.java

@@ -0,0 +1,44 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface ContainerServlet {
+
+    /**
+     * Obtain the Wrapper with which this Servlet is associated.
+     *
+     * @return The Wrapper with which this Servlet is associated.
+     */
+    public Wrapper getWrapper();
+
+
+    /**
+     * Set the Wrapper with which this Servlet is associated.
+     *
+     * @param wrapper The new associated Wrapper
+     */
+    public void setWrapper(Wrapper wrapper);
+}

java/org/apache/catalina/CredentialHandler.java

@@ -0,0 +1,46 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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.
+ */
+public interface CredentialHandler {
+
+    /**
+     * Checks to see if the input credentials match the stored credentials
+     *
+     * @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>
+     */
+    boolean matches(String inputCredentials, String storedCredentials);
+
+    /**
+     * Generates the equivalent stored credentials for the given input
+     * credentials.
+     *
+     * @param inputCredentials  User provided credentials
+     *
+     * @return  The equivalent stored credentials for the given input
+     *          credentials
+     */
+    String mutate(String inputCredentials);
+}

java/org/apache/catalina/DistributedManager.java

@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package 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.
+ * <p>
+ * With the BackupManager, sessions can be primary (master 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).
+ */
+public interface DistributedManager {
+
+    /**
+     * Returns the total session count for primary, backup and proxy.
+     *
+     * @return  The total session count across the cluster.
+     */
+    public int getActiveSessionsFull();
+
+    /**
+     * Returns the list of all sessions IDS (primary, backup and proxy).
+     *
+     * @return  The complete set of sessions IDs across the cluster.
+     */
+    public Set<String> getSessionIdsFull();
+}

java/org/apache/catalina/Engine.java

@@ -0,0 +1,86 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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:
+ * <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.
+ * </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.
+ * <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.
+ * <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>.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Engine extends Container {
+
+    /**
+     * @return the default host name for this Engine.
+     */
+    public String getDefaultHost();
+
+
+    /**
+     * Set the default hostname for this Engine.
+     *
+     * @param defaultHost The new default host
+     */
+    public void setDefaultHost(String defaultHost);
+
+
+    /**
+     * @return the JvmRouteId for this engine.
+     */
+    public String getJvmRoute();
+
+
+    /**
+     * 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.
+     */
+    public void setJvmRoute(String jvmRouteId);
+
+
+    /**
+     * @return the <code>Service</code> with which we are associated (if any).
+     */
+    public Service getService();
+
+
+    /**
+     * Set the <code>Service</code> with which we are associated (if any).
+     *
+     * @param service The service that owns this Engine
+     */
+    public void setService(Service service);
+}

java/org/apache/catalina/Executor.java

@@ -0,0 +1,42 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.util.concurrent.TimeUnit;
+
+public interface Executor extends java.util.concurrent.Executor, Lifecycle {
+
+    public String getName();
+
+    /**
+     * Executes the given command at some time in the future.  The command
+     * may execute in a new thread, in a pooled thread, or in the calling
+     * thread, at the discretion of the <code>Executor</code> implementation.
+     * If no threads are available, it will be added to the work queue.
+     * If the work queue is full, the system will wait for the specified
+     * time until it throws a RejectedExecutionException
+     *
+     * @param command the runnable task
+     * @param timeout the length of time to wait for the task to complete
+     * @param unit    the units in which timeout is expressed
+     *
+     * @throws java.util.concurrent.RejectedExecutionException if this task
+     * cannot be accepted for execution - the queue is full
+     * @throws NullPointerException if command or unit is null
+     */
+    void execute(Runnable command, long timeout, TimeUnit unit);
+}

java/org/apache/catalina/GSSRealm.java

@@ -0,0 +1,45 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.security.Principal;
+
+import org.ietf.jgss.GSSCredential;
+import org.ietf.jgss.GSSName;
+
+/**
+ * A <b>GSSRealm</b> is a specialized realm for GSS-based principals.
+ *
+ * @deprecated This will be removed in Tomcat 9 and integrated into {@link Realm}.
+ */
+@Deprecated
+public interface GSSRealm extends Realm {
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * 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}
+     * @return the associated principal, or {@code null} if there is none
+     */
+    public Principal authenticate(GSSName gssName, GSSCredential gssCredential);
+
+}

java/org/apache/catalina/Globals.java

@@ -0,0 +1,295 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+/**
+ * Global constants that are applicable to multiple packages within Catalina.
+ *
+ * @author Craig R. McClanahan
+ */
+public final class Globals {
+
+    /**
+     * 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 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 =
+        "javax.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
+     * java.lang.String).
+     */
+    public static final String CIPHER_SUITE_ATTR =
+        "javax.servlet.request.cipher_suite";
+
+
+    /**
+     * Request dispatcher state.
+     */
+    public static final String DISPATCHER_TYPE_ATTR =
+        "org.apache.catalina.core.DISPATCHER_TYPE";
+
+
+    /**
+     * Request dispatcher path.
+     */
+    public static final String DISPATCHER_REQUEST_PATH_ATTR =
+        "org.apache.catalina.core.DISPATCHER_REQUEST_PATH";
+
+
+    /**
+     * 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";
+
+
+    /**
+     * 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";
+
+
+    /**
+     * The request attribute under which we store the key size being used for
+     * this SSL connection (as an object of type java.lang.Integer).
+     */
+    public static final String KEY_SIZE_ATTR =
+        "javax.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 java.lang.String).
+     */
+    public static final String SSL_SESSION_ID_ATTR =
+        "javax.servlet.request.ssl_session_id";
+
+
+    /**
+     * 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 =
+        "javax.servlet.request.ssl_session_mgr";
+
+
+    /**
+     * 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 servlet context attribute under which we store a flag used
+     * to mark this request as having been processed by the SSIServlet.
+     * We do this because of the pathInfo mangling happening when using
+     * the CGIServlet in conjunction with the SSI servlet. (value stored
+     * as an object of type String)
+     *
+     * @deprecated Unused. This is no longer used as the CGIO servlet now has
+     *             generic handling for when it is used as an include.
+     *             This will be removed in Tomcat 10
+     */
+    @Deprecated
+    public static final String SSI_FLAG_ATTR = "org.apache.catalina.ssi.SSIServlet";
+
+
+    /**
+     * The subject under which the AccessControlContext is running.
+     */
+    public static final String SUBJECT_ATTR =
+        "javax.security.auth.subject";
+
+
+    public static final String GSS_CREDENTIAL_ATTR =
+        "org.apache.catalina.realm.GSS_CREDENTIAL";
+
+
+    /**
+     * 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 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 java.lang.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 java.lang.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.
+     */
+    public static final String SENDFILE_FILE_END_ATTR =
+            org.apache.coyote.Constants.SENDFILE_FILE_END_ATTR;
+
+
+    /**
+     * 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.
+     */
+    public static final String REQUEST_FORWARDED_ATTRIBUTE =
+        "org.apache.tomcat.request.forwarded";
+
+
+    public static final String ASYNC_SUPPORTED_ATTR =
+        "org.apache.catalina.ASYNC_SUPPORTED";
+
+
+    /**
+     * 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";
+
+
+    /**
+     * The reason that the parameter parsing failed.
+     */
+    public static final String PARAMETER_PARSE_FAILED_REASON_ATTR =
+            "org.apache.catalina.parameter_parse_failed_reason";
+
+
+    /**
+     * The master flag which controls strict servlet specification
+     * compliance.
+     */
+    public static final boolean STRICT_SERVLET_COMPLIANCE =
+        Boolean.parseBoolean(System.getProperty("org.apache.catalina.STRICT_SERVLET_COMPLIANCE", "false"));
+
+
+    /**
+     * Has security been turned on?
+     */
+    public static final boolean IS_SECURITY_ENABLED =
+        (System.getSecurityManager() != null);
+
+
+    /**
+     * Default domain for MBeans if none can be determined
+     */
+    public static final String DEFAULT_MBEAN_DOMAIN = "Catalina";
+
+
+    /**
+     * Name of the system property containing
+     * the tomcat product installation path
+     */
+    public static final String CATALINA_HOME_PROP = "catalina.home";
+
+
+    /**
+     * Name of the system property containing
+     * the tomcat instance installation path
+     */
+    public static final String CATALINA_BASE_PROP = "catalina.base";
+
+
+    /**
+     * 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
+     */
+    public static final String JASPER_XML_VALIDATION_TLD_INIT_PARAM =
+            "org.apache.jasper.XML_VALIDATE_TLD";
+
+
+    /**
+     * 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
+     */
+    public static final String JASPER_XML_BLOCK_EXTERNAL_INIT_PARAM =
+            "org.apache.jasper.XML_BLOCK_EXTERNAL";
+
+    /**
+     * 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";
+}

java/org/apache/catalina/Group.java

@@ -0,0 +1,117 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+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>
+ *
+ * @author Craig R. McClanahan
+ * @since 4.1
+ */
+public interface Group extends Principal {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * @return the description of this group.
+     */
+    public String getDescription();
+
+
+    /**
+     * Set the description of this group.
+     *
+     * @param description The new description
+     */
+    public void setDescription(String description);
+
+
+    /**
+     * @return the group name of this group, which must be unique
+     * within the scope of a {@link UserDatabase}.
+     */
+    public String getGroupname();
+
+
+    /**
+     * Set the group name of this group, which must be unique
+     * within the scope of a {@link UserDatabase}.
+     *
+     * @param groupname The new group name
+     */
+    public void setGroupname(String groupname);
+
+
+    /**
+     * @return the set of {@link Role}s assigned specifically to this group.
+     */
+    public Iterator<Role> getRoles();
+
+
+    /**
+     * @return the {@link UserDatabase} within which this Group is defined.
+     */
+    public UserDatabase getUserDatabase();
+
+
+    /**
+     * @return the set of {@link User}s that are members of this group.
+     */
+    public Iterator<User> getUsers();
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Add a new {@link Role} to those assigned specifically to this group.
+     *
+     * @param role The new role
+     */
+    public void addRole(Role role);
+
+
+    /**
+     * Is this group specifically assigned the specified {@link Role}?
+     *
+     * @param role The role to check
+     *
+     * @return <code>true</code> if the group is assigned to the specified role
+     *         otherwise <code>false</code>
+     */
+    public boolean isInRole(Role role);
+
+
+    /**
+     * Remove a {@link Role} from those assigned to this group.
+     *
+     * @param role The old role
+     */
+    public void removeRole(Role role);
+
+
+    /**
+     * Remove all {@link Role}s from those assigned to this group.
+     */
+    public void removeRoles();
+
+
+}

java/org/apache/catalina/Host.java

@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.File;
+import java.util.concurrent.ExecutorService;
+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:
+ * <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.
+ * </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.
+ * <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.
+ * <p>
+ * The child containers attached to a Host are generally implementations
+ * of Context (representing an individual servlet context).
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Host extends Container {
+
+
+    // ----------------------------------------------------- Manifest Constants
+
+
+    /**
+     * The ContainerEvent event type sent when a new alias is added
+     * by <code>addAlias()</code>.
+     */
+    public static final String ADD_ALIAS_EVENT = "addAlias";
+
+
+    /**
+     * The ContainerEvent event type sent when an old alias is removed
+     * by <code>removeAlias()</code>.
+     */
+    public static final String REMOVE_ALIAS_EVENT = "removeAlias";
+
+
+    // ------------------------------------------------------------- Properties
+
+
+    /**
+     * @return the XML root for this Host.  This can be an absolute
+     * pathname, a relative pathname, or a URL.
+     * If null, the base path defaults to
+     * ${catalina.base}/conf/&lt;engine name&gt;/&lt;host name&gt; directory
+     */
+    public String getXmlBase();
+
+    /**
+     * Set the Xml root for this Host.  This can be an absolute
+     * pathname, a relative pathname, or a URL.
+     * If null, the base path defaults to
+     * ${catalina.base}/conf/&lt;engine name&gt;/&lt;host name&gt; directory
+     * @param xmlBase The new XML root
+     */
+    public void setXmlBase(String xmlBase);
+
+    /**
+     * @return a default configuration path of this Host. The file will be
+     * canonical if possible.
+     */
+    public File getConfigBaseFile();
+
+    /**
+     * @return the application root for this Host.  This can be an absolute
+     * pathname, a relative pathname, or a URL.
+     */
+    public 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.
+     */
+    public File getAppBaseFile();
+
+
+    /**
+     * 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
+     */
+    public void setAppBase(String appBase);
+
+
+    /**
+     * @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.
+     */
+    public boolean getAutoDeploy();
+
+
+    /**
+     * Set the auto deploy flag value for this host.
+     *
+     * @param autoDeploy The new auto deploy flag
+     */
+    public void setAutoDeploy(boolean autoDeploy);
+
+
+    /**
+     * @return the Java class name of the context configuration class
+     * for new web applications.
+     */
+    public String getConfigClass();
+
+
+    /**
+     * Set the Java class name of the context configuration class
+     * for new web applications.
+     *
+     * @param configClass The new context configuration class
+     */
+    public void setConfigClass(String configClass);
+
+
+    /**
+     * @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.
+     */
+    public boolean getDeployOnStartup();
+
+
+    /**
+     * Set the deploy on startup flag value for this host.
+     *
+     * @param deployOnStartup The new deploy on startup flag
+     */
+    public void setDeployOnStartup(boolean deployOnStartup);
+
+
+    /**
+     * @return the regular expression that defines the files and directories in
+     * the host's appBase that will be ignored by the automatic deployment
+     * process.
+     */
+    public 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.
+     */
+    public 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.
+     *
+     * @param deployIgnore A regular expression matching file names
+     */
+    public void setDeployIgnore(String deployIgnore);
+
+
+    /**
+     * @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.
+     */
+    public ExecutorService getStartStopExecutor();
+
+
+    /**
+     * 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
+     */
+    public boolean getCreateDirs();
+
+
+    /**
+     * Should the Host attempt to create directories for xmlBase and appBase
+     * upon startup.
+     *
+     * @param createDirs The new value for this flag
+     */
+    public void setCreateDirs(boolean createDirs);
+
+
+    /**
+     * @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>.
+     */
+    public 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>.
+     *
+     * @param undeployOldVersions The new value for this flag
+     */
+    public void setUndeployOldVersions(boolean undeployOldVersions);
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Add an alias name that should be mapped to this same Host.
+     *
+     * @param alias The alias to be added
+     */
+    public void addAlias(String alias);
+
+
+    /**
+     * @return the set of alias names for this Host.  If none are defined,
+     * a zero length array is returned.
+     */
+    public String[] findAliases();
+
+
+    /**
+     * Remove the specified alias name from the aliases for this Host.
+     *
+     * @param alias Alias name to be removed
+     */
+    public void removeAlias(String alias);
+}

java/org/apache/catalina/JmxEnabled.java

@@ -0,0 +1,52 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+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
+ * {@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.
+     */
+    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.
+     *
+     * @param domain The name of the domain under which this component should be
+     *               registered
+     */
+    void setDomain(String domain);
+
+
+    /**
+     * @return the name under which this component has been registered with JMX.
+     */
+    ObjectName getObjectName();
+}

java/org/apache/catalina/Lifecycle.java

@@ -0,0 +1,319 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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:
+ * <pre>
+ *            start()
+ *  -----------------------------
+ *  |                           |
+ *  | init()                    |
+ * NEW -»-- INITIALIZING        |
+ * | |           |              |     ------------------«-----------------------
+ * | |           |auto          |     |                                        |
+ * | |          \|/    start() \|/   \|/     auto          auto         stop() |
+ * | |      INITIALIZED --»-- STARTING_PREP --»- STARTING --»- STARTED --»---  |
+ * | |         |                                                            |  |
+ * | |destroy()|                                                            |  |
+ * | --»-----«--    ------------------------«--------------------------------  ^
+ * |     |          |                                                          |
+ * |     |         \|/          auto                 auto              start() |
+ * |     |     STOPPING_PREP ----»---- STOPPING ------»----- STOPPED -----»-----
+ * |    \|/                               ^                     |  ^
+ * |     |               stop()           |                     |  |
+ * |     |       --------------------------                     |  |
+ * |     |       |                                              |  |
+ * |     |       |    destroy()                       destroy() |  |
+ * |     |    FAILED ----»------ DESTROYING ---«-----------------  |
+ * |     |                        ^     |                          |
+ * |     |     destroy()          |     |auto                      |
+ * |     --------»-----------------    \|/                         |
+ * |                                 DESTROYED                     |
+ * |                                                               |
+ * |                            stop()                             |
+ * ----»-----------------------------»------------------------------
+ *
+ * Any state can transition to FAILED.
+ *
+ * Calling start() while a component is in states STARTING_PREP, STARTING or
+ * STARTED has no effect.
+ *
+ * Calling start() while a component is in state NEW will cause init() to be
+ * called immediately after the start() method is entered.
+ *
+ * Calling stop() while a component is in states STOPPING_PREP, STOPPING or
+ * STOPPED has no effect.
+ *
+ * Calling stop() while a component is in state NEW transitions the component
+ * to STOPPED. This is typically encountered when a component fails to start and
+ * does not start all its sub-components. When the component is stopped, it will
+ * try to stop all sub-components - even those it didn't start.
+ *
+ * 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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Lifecycle {
+
+
+    // ----------------------------------------------------- Manifest Constants
+
+
+    /**
+     * The LifecycleEvent type for the "component before init" event.
+     */
+    public static final String BEFORE_INIT_EVENT = "before_init";
+
+
+    /**
+     * The LifecycleEvent type for the "component after init" event.
+     */
+    public static final String AFTER_INIT_EVENT = "after_init";
+
+
+    /**
+     * The LifecycleEvent type for the "component start" event.
+     */
+    public static final String START_EVENT = "start";
+
+
+    /**
+     * The LifecycleEvent type for the "component before start" event.
+     */
+    public static final String BEFORE_START_EVENT = "before_start";
+
+
+    /**
+     * The LifecycleEvent type for the "component after start" event.
+     */
+    public static final String AFTER_START_EVENT = "after_start";
+
+
+    /**
+     * The LifecycleEvent type for the "component stop" event.
+     */
+    public static final String STOP_EVENT = "stop";
+
+
+    /**
+     * The LifecycleEvent type for the "component before stop" event.
+     */
+    public static final String BEFORE_STOP_EVENT = "before_stop";
+
+
+    /**
+     * The LifecycleEvent type for the "component after stop" event.
+     */
+    public static final String AFTER_STOP_EVENT = "after_stop";
+
+
+    /**
+     * The LifecycleEvent type for the "component after destroy" event.
+     */
+    public static final String AFTER_DESTROY_EVENT = "after_destroy";
+
+
+    /**
+     * The LifecycleEvent type for the "component before destroy" event.
+     */
+    public static final String BEFORE_DESTROY_EVENT = "before_destroy";
+
+
+    /**
+     * The LifecycleEvent type for the "periodic" event.
+     */
+    public static final String PERIODIC_EVENT = "periodic";
+
+
+    /**
+     * 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}.
+     */
+    public static final 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
+     * {@link #STOP_EVENT} and before {@link #AFTER_STOP_EVENT}.
+     */
+    public static final String CONFIGURE_STOP_EVENT = "configure_stop";
+
+
+    // --------------------------------------------------------- Public Methods
+
+
+    /**
+     * Add a LifecycleEvent listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addLifecycleListener(LifecycleListener listener);
+
+
+    /**
+     * 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.
+     */
+    public LifecycleListener[] findLifecycleListeners();
+
+
+    /**
+     * Remove a LifecycleEvent listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removeLifecycleListener(LifecycleListener listener);
+
+
+    /**
+     * 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>
+     * </ol>
+     *
+     * @exception LifecycleException if this component detects a fatal error
+     *  that prevents this component from being used
+     */
+    public 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:
+     * <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>
+     * </ol>
+     *
+     * @exception LifecycleException if this component detects a fatal error
+     *  that prevents this component from being used
+     */
+    public 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:
+     * <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>
+     * </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}
+     *
+     * @exception LifecycleException if this component detects a fatal error
+     *  that needs to be reported
+     */
+    public void stop() throws LifecycleException;
+
+    /**
+     * 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>
+     * </ol>
+     *
+     * @exception LifecycleException if this component detects a fatal error
+     *  that prevents this component from being used
+     */
+    public void destroy() throws LifecycleException;
+
+
+    /**
+     * Obtain the current state of the source component.
+     *
+     * @return The current state of the source component.
+     */
+    public LifecycleState 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.
+     */
+    public String getStateName();
+
+
+    /**
+     * 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.
+     */
+    public interface SingleUse {
+    }
+}

java/org/apache/catalina/LifecycleEvent.java

@@ -0,0 +1,80 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.util.EventObject;
+
+/**
+ * General event for notifying listeners of significant changes on a component
+ * that implements the Lifecycle interface.
+ *
+ * @author Craig R. McClanahan
+ */
+public final class LifecycleEvent extends EventObject {
+
+    private static final long serialVersionUID = 1L;
+
+
+    /**
+     * 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)
+     */
+    public LifecycleEvent(Lifecycle lifecycle, String type, Object data) {
+        super(lifecycle);
+        this.type = type;
+        this.data = data;
+    }
+
+
+    /**
+     * The event data associated with this event.
+     */
+    private final Object data;
+
+
+    /**
+     * The event type this instance represents.
+     */
+    private final String type;
+
+
+    /**
+     * @return the event data of this event.
+     */
+    public Object getData() {
+        return data;
+    }
+
+
+    /**
+     * @return the Lifecycle on which this event occurred.
+     */
+    public Lifecycle getLifecycle() {
+        return (Lifecycle) getSource();
+    }
+
+
+    /**
+     * @return the event type of this event.
+     */
+    public String getType() {
+        return this.type;
+    }
+}

java/org/apache/catalina/LifecycleException.java

@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package 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.
+ *
+ * @author Craig R. McClanahan
+ */
+public final class LifecycleException extends Exception {
+
+    private static final long serialVersionUID = 1L;
+
+    //------------------------------------------------------------ Constructors
+
+
+    /**
+     * Construct a new LifecycleException with no other information.
+     */
+    public LifecycleException() {
+        super();
+    }
+
+
+    /**
+     * Construct a new LifecycleException for the specified message.
+     *
+     * @param message Message describing this exception
+     */
+    public LifecycleException(String message) {
+        super(message);
+    }
+
+
+    /**
+     * Construct a new LifecycleException for the specified throwable.
+     *
+     * @param throwable Throwable that caused this exception
+     */
+    public LifecycleException(Throwable throwable) {
+        super(throwable);
+    }
+
+
+    /**
+     * Construct a new LifecycleException for the specified message
+     * and throwable.
+     *
+     * @param message Message describing this exception
+     * @param throwable Throwable that caused this exception
+     */
+    public LifecycleException(String message, Throwable throwable) {
+        super(message, throwable);
+    }
+}

java/org/apache/catalina/LifecycleListener.java

@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package 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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface LifecycleListener {
+
+
+    /**
+     * Acknowledge the occurrence of the specified event.
+     *
+     * @param event LifecycleEvent that has occurred
+     */
+    public void lifecycleEvent(LifecycleEvent event);
+
+
+}

java/org/apache/catalina/LifecycleState.java

@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+/**
+ * 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),
+    INITIALIZING(false, Lifecycle.BEFORE_INIT_EVENT),
+    INITIALIZED(false, Lifecycle.AFTER_INIT_EVENT),
+    STARTING_PREP(false, Lifecycle.BEFORE_START_EVENT),
+    STARTING(true, Lifecycle.START_EVENT),
+    STARTED(true, Lifecycle.AFTER_START_EVENT),
+    STOPPING_PREP(true, Lifecycle.BEFORE_STOP_EVENT),
+    STOPPING(false, Lifecycle.STOP_EVENT),
+    STOPPED(false, Lifecycle.AFTER_STOP_EVENT),
+    DESTROYING(false, Lifecycle.BEFORE_DESTROY_EVENT),
+    DESTROYED(false, Lifecycle.AFTER_DESTROY_EVENT),
+    FAILED(false, null);
+
+    private final boolean available;
+    private final String lifecycleEvent;
+
+    private LifecycleState(boolean available, String lifecycleEvent) {
+        this.available = available;
+        this.lifecycleEvent = lifecycleEvent;
+    }
+
+    /**
+     * 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>
+     */
+    public boolean isAvailable() {
+        return available;
+    }
+
+    public String getLifecycleEvent() {
+        return lifecycleEvent;
+    }
+}

java/org/apache/catalina/Loader.java

@@ -0,0 +1,135 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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.
+ * <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:
+ * <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.
+ * </ul>
+ *
+ * @author Craig R. McClanahan
+ */
+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.
+     */
+    public void backgroundProcess();
+
+
+    /**
+     * @return the Java class loader to be used by this Container.
+     */
+    public ClassLoader getClassLoader();
+
+
+    /**
+     * @return the Context with which this Loader has been associated.
+     */
+    public Context getContext();
+
+
+    /**
+     * Set the Context with which this Loader has been associated.
+     *
+     * @param context The associated Context
+     */
+    public void setContext(Context context);
+
+
+    /**
+     * @return the "follow standard delegation model" flag used to configure
+     * our ClassLoader.
+     */
+    public boolean getDelegate();
+
+
+    /**
+     * Set the "follow standard delegation model" flag used to configure
+     * our ClassLoader.
+     *
+     * @param delegate The new flag
+     */
+    public void setDelegate(boolean delegate);
+
+
+    /**
+     * @return the reloadable flag for this Loader.
+     */
+    public boolean getReloadable();
+
+
+    /**
+     * Set the reloadable flag for this Loader.
+     *
+     * @param reloadable The new reloadable flag
+     */
+    public void setReloadable(boolean reloadable);
+
+
+    /**
+     * Add a property change listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addPropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * 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
+     */
+    public boolean modified();
+
+
+    /**
+     * Remove a property change listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removePropertyChangeListener(PropertyChangeListener listener);
+}

java/org/apache/catalina/Manager.java

@@ -0,0 +1,354 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+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.
+ * <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:
+ * <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.
+ * </ul>
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Manager {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * Get the Context with which this Manager is associated.
+     *
+     * @return The associated Context
+     */
+    public Context getContext();
+
+
+    /**
+     * 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
+     */
+    public void setContext(Context context);
+
+
+    /**
+     * @return the session id generator
+     */
+    public SessionIdGenerator getSessionIdGenerator();
+
+
+    /**
+     * Sets the session id generator
+     *
+     * @param sessionIdGenerator The session id generator
+     */
+    public void setSessionIdGenerator(SessionIdGenerator sessionIdGenerator);
+
+
+    /**
+     * Returns the total number of sessions created by this manager.
+     *
+     * @return Total number of sessions created by this manager.
+     */
+    public long getSessionCounter();
+
+
+    /**
+     * Sets the total number of sessions created by this manager.
+     *
+     * @param sessionCounter Total number of sessions created by this manager.
+     */
+    public void setSessionCounter(long sessionCounter);
+
+
+    /**
+     * 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
+     */
+    public int getMaxActive();
+
+
+    /**
+     * (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.
+     */
+    public void setMaxActive(int maxActive);
+
+
+    /**
+     * Gets the number of currently active sessions.
+     *
+     * @return Number of currently active sessions
+     */
+    public int getActiveSessions();
+
+
+    /**
+     * Gets the number of sessions that have expired.
+     *
+     * @return Number of sessions that have expired
+     */
+    public long getExpiredSessions();
+
+
+    /**
+     * Sets the number of sessions that have expired.
+     *
+     * @param expiredSessions Number of sessions that have expired
+     */
+    public void setExpiredSessions(long expiredSessions);
+
+
+    /**
+     * Gets the number of sessions that were not created because the maximum
+     * number of active sessions was reached.
+     *
+     * @return Number of rejected sessions
+     */
+    public int getRejectedSessions();
+
+
+    /**
+     * 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.
+     */
+    public int getSessionMaxAliveTime();
+
+
+    /**
+     * 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.
+     */
+    public void setSessionMaxAliveTime(int sessionMaxAliveTime);
+
+
+    /**
+     * 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.
+     */
+    public int getSessionAverageAliveTime();
+
+
+    /**
+     * 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
+     */
+    public int getSessionCreateRate();
+
+
+    /**
+     * 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
+     */
+    public int getSessionExpireRate();
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Add this Session to the set of active Sessions for this Manager.
+     *
+     * @param session Session to be added
+     */
+    public void add(Session session);
+
+
+    /**
+     * Add a property change listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addPropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * 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
+     */
+    public void changeSessionId(Session session);
+
+
+    /**
+     * Change the session ID of the current session to a specified session ID.
+     *
+     * @param session   The session to change the session ID for
+     * @param newId   new session ID
+     */
+    public 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.
+     *
+     * @return An empty Session object
+     */
+    public Session createEmptySession();
+
+
+    /**
+     * 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.
+     * @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
+     */
+    public Session createSession(String sessionId);
+
+
+    /**
+     * 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
+     *
+     * @return the request session or {@code null} if a session with the
+     *         requested ID could not be found
+     */
+    public 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 All the currently active sessions managed by this manager
+     */
+    public Session[] findSessions();
+
+
+    /**
+     * 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
+     */
+    public void load() throws ClassNotFoundException, IOException;
+
+
+    /**
+     * Remove this Session from the active Sessions for this Manager.
+     *
+     * @param session Session to be removed
+     */
+    public void remove(Session session);
+
+
+    /**
+     * Remove this Session from the active Sessions for this Manager.
+     *
+     * @param session   Session to be removed
+     * @param update    Should the expiration statistics be updated
+     */
+    public void remove(Session session, boolean update);
+
+
+    /**
+     * Remove a property change listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removePropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * 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
+     */
+    public void unload() throws IOException;
+
+
+    /**
+     * 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.
+     */
+    public void backgroundProcess();
+
+
+    /**
+     * 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}
+     */
+    public boolean willAttributeDistribute(String name, Object value);
+}

java/org/apache/catalina/Pipeline.java

@@ -0,0 +1,149 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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>
+ *
+ * @author Craig R. McClanahan
+ * @author Peter Donald
+ */
+public interface Pipeline {
+
+    /**
+     * @return the Valve instance that has been distinguished as the basic
+     * Valve for this Pipeline (if any).
+     */
+    public 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>
+     *
+     * @param valve Valve to be distinguished as the basic Valve
+     */
+    public void setBasic(Valve valve);
+
+
+    /**
+     * <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
+     */
+    public 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.
+     */
+    public 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>
+     *
+     * @param valve Valve to be removed
+     */
+    public void removeValve(Valve valve);
+
+
+    /**
+     * @return the Valve instance that has been distinguished as the basic
+     * Valve for this Pipeline (if any).
+     */
+    public 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
+     */
+    public boolean isAsyncSupported();
+
+
+    /**
+     * @return the Container with which this Pipeline is associated.
+     */
+    public Container getContainer();
+
+
+    /**
+     * Set the Container with which this Pipeline is associated.
+     *
+     * @param container The new associated container
+     */
+    public void setContainer(Container container);
+
+
+    /**
+     * 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
+     */
+    public void findNonAsyncValves(Set<String> result);
+}

java/org/apache/catalina/Realm.java

@@ -0,0 +1,244 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.beans.PropertyChangeListener;
+import java.io.IOException;
+import java.security.Principal;
+import java.security.cert.X509Certificate;
+
+import org.apache.catalina.connector.Request;
+import org.apache.catalina.connector.Response;
+import org.apache.tomcat.util.descriptor.web.SecurityConstraint;
+import org.ietf.jgss.GSSContext;
+
+/**
+ * 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
+ */
+public interface Realm {
+
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * @return the Container with which this Realm has been associated.
+     */
+    public Container getContainer();
+
+
+    /**
+     * Set the Container with which this Realm has been associated.
+     *
+     * @param container The associated Container
+     */
+    public void setContainer(Container container);
+
+
+    /**
+     * @return the CredentialHandler configured for this Realm.
+     */
+    public CredentialHandler getCredentialHandler();
+
+    /**
+     * Set the CredentialHandler to be used by this Realm.
+     *
+     * @param credentialHandler the {@link CredentialHandler} to use
+     */
+    public void setCredentialHandler(CredentialHandler credentialHandler);
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Add a property change listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addPropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * Try to authenticate with the specified username.
+     *
+     * @param username Username of the Principal to look up
+     * @return the associated principal, or <code>null</code> if none is
+     *         associated.
+     */
+    public Principal authenticate(String username);
+
+
+    /**
+     * 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
+     * @return the associated principal, or <code>null</code> if there is none
+     */
+    public Principal authenticate(String username, String credentials);
+
+
+    /**
+     * 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</code> and <code>cnonce</code>
+     *        will only be used, if <code>qop</code> is not <code>null</code>).
+     * @param realm Realm name
+     * @param md5a2 Second MD5 digest used to calculate the digest :
+     * MD5(Method + ":" + uri)
+     * @return the associated principal, or <code>null</code> if there is none.
+     */
+    public Principal authenticate(String username, String digest,
+                                  String nonce, String nc, String cnonce,
+                                  String qop, String realm,
+                                  String md5a2);
+
+
+    /**
+     * 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?
+     * @return the associated principal, or <code>null</code> if there is none
+     */
+    public Principal authenticate(GSSContext gssContext, boolean storeCreds);
+
+
+    /**
+     * Try to authenticate using {@link X509Certificate}s
+     *
+     * @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</code> if there is none
+     */
+    public Principal authenticate(X509Certificate certs[]);
+
+
+    /**
+     * 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.
+     */
+    public void backgroundProcess();
+
+
+    /**
+     * Find the SecurityConstraints configured to guard the request URI for
+     * this request.
+     *
+     * @param request Request we are processing
+     * @param context {@link Context} for this request
+     * @return the configured {@link SecurityConstraint}, of <code>null</code>
+     *         if there is none
+     */
+    public 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 constraint Security constraint we are enforcing
+     * @param context The Context to which client of this class is attached.
+     * @return <code>true</code> if this constraint is satisfied and processing
+     *         should continue, or <code>false</code> otherwise
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public 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.
+     *
+     * @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
+     * @return <code>true</code> if the specified Principal has the specified
+     *         security role, within the context of this Realm; otherwise return
+     *         <code>false</code>.
+     */
+    public boolean hasRole(Wrapper wrapper, Principal principal, String role);
+
+
+    /**
+     * 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 constraint Security constraint being checked
+     * @return <code>true</code> if this constraint
+     *         was not violated and processing should continue, or <code>false</code>
+     *         if we have created a response already.
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public boolean hasUserDataPermission(Request request,
+                                         Response response,
+                                         SecurityConstraint []constraint)
+        throws IOException;
+
+
+    /**
+     * Remove a property change listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removePropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * Return roles associated with given principal
+     * @param principal the {@link Principal} to get the roles for.
+     * @return principal roles
+     * @deprecated This will be removed in Tomcat 10.
+     */
+    @Deprecated
+    public String[] getRoles(Principal principal);
+
+
+    /**
+     * Return the availability of the realm for authentication.
+     * @return <code>true</code> if the realm is able to perform authentication
+     */
+    public boolean isAvailable();
+
+}

java/org/apache/catalina/Role.java

@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+
+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>
+ *
+ * @author Craig R. McClanahan
+ * @since 4.1
+ */
+public interface Role extends Principal {
+
+
+    // ------------------------------------------------------------- Properties
+
+
+    /**
+     * @return the description of this role.
+     */
+    public String getDescription();
+
+
+    /**
+     * Set the description of this role.
+     *
+     * @param description The new description
+     */
+    public void setDescription(String description);
+
+
+    /**
+     * @return the role name of this role, which must be unique
+     * within the scope of a {@link UserDatabase}.
+     */
+    public String getRolename();
+
+
+    /**
+     * Set the role name of this role, which must be unique
+     * within the scope of a {@link UserDatabase}.
+     *
+     * @param rolename The new role name
+     */
+    public void setRolename(String rolename);
+
+
+    /**
+     * @return the {@link UserDatabase} within which this Role is defined.
+     */
+    public UserDatabase getUserDatabase();
+
+
+}

java/org/apache/catalina/Server.java

@@ -0,0 +1,222 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+import java.io.File;
+
+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.
+ * <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.
+ * <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.
+ * <p>
+ * <strong>NOTE</strong> - The concrete implementation of this class should
+ * register the (singleton) instance with the <code>ServerFactory</code>
+ * class in its constructor(s).
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Server extends Lifecycle {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * @return the global naming resources.
+     */
+    public NamingResourcesImpl getGlobalNamingResources();
+
+
+    /**
+     * Set the global naming resources.
+     *
+     * @param globalNamingResources The new global naming resources
+     */
+    public void setGlobalNamingResources
+        (NamingResourcesImpl globalNamingResources);
+
+
+    /**
+     * @return the global naming resources context.
+     */
+    public javax.naming.Context getGlobalNamingContext();
+
+
+    /**
+     * @return the port number we listen to for shutdown commands.
+     */
+    public int getPort();
+
+
+    /**
+     * Set the port number we listen to for shutdown commands.
+     *
+     * @param port The new port number
+     */
+    public void setPort(int port);
+
+
+    /**
+     * @return the address on which we listen to for shutdown commands.
+     */
+    public String getAddress();
+
+
+    /**
+     * Set the address on which we listen to for shutdown commands.
+     *
+     * @param address The new address
+     */
+    public void setAddress(String address);
+
+
+    /**
+     * @return the shutdown command string we are waiting for.
+     */
+    public String getShutdown();
+
+
+    /**
+     * Set the shutdown command we are waiting for.
+     *
+     * @param shutdown The new shutdown command
+     */
+    public void setShutdown(String shutdown);
+
+
+    /**
+     * @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.
+     */
+    public ClassLoader getParentClassLoader();
+
+
+    /**
+     * Set the parent class loader for this server.
+     *
+     * @param parent The new parent class loader
+     */
+    public void setParentClassLoader(ClassLoader parent);
+
+
+    /**
+     * @return the outer Catalina startup/shutdown component if present.
+     */
+    public Catalina getCatalina();
+
+    /**
+     * Set the outer Catalina startup/shutdown component if present.
+     *
+     * @param catalina the outer Catalina component
+     */
+    public void setCatalina(Catalina catalina);
+
+
+    /**
+     * @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.
+     */
+    public File getCatalinaBase();
+
+    /**
+     * 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
+     */
+    public void setCatalinaBase(File catalinaBase);
+
+
+    /**
+     * @return the configured home (binary) directory. Note that home and base
+     * may be the same (and are by default).
+     */
+    public File getCatalinaHome();
+
+    /**
+     * 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
+     */
+    public void setCatalinaHome(File catalinaHome);
+
+
+    // --------------------------------------------------------- Public Methods
+
+
+    /**
+     * Add a new Service to the set of defined Services.
+     *
+     * @param service The Service to be added
+     */
+    public void addService(Service service);
+
+
+    /**
+     * Wait until a proper shutdown command is received, then return.
+     */
+    public void await();
+
+
+    /**
+     * Find the specified Service
+     *
+     * @param name Name of the Service to be returned
+     * @return the specified Service, or <code>null</code> if none exists.
+     */
+    public Service findService(String name);
+
+
+    /**
+     * @return the set of Services defined within this Server.
+     */
+    public Service[] findServices();
+
+
+    /**
+     * Remove the specified Service from the set associated from this
+     * Server.
+     *
+     * @param service The Service to be removed
+     */
+    public void removeService(Service service);
+
+
+    /**
+     * @return the token necessary for operations on the associated JNDI naming
+     * context.
+     */
+    public Object getNamingToken();
+}

java/org/apache/catalina/Service.java

@@ -0,0 +1,152 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+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.
+ * <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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Service extends Lifecycle {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * @return the <code>Engine</code> that handles requests for all
+     * <code>Connectors</code> associated with this Service.
+     */
+    public Engine getContainer();
+
+    /**
+     * Set the <code>Engine</code> that handles requests for all
+     * <code>Connectors</code> associated with this Service.
+     *
+     * @param engine The new Engine
+     */
+    public void setContainer(Engine engine);
+
+    /**
+     * @return the name of this Service.
+     */
+    public String getName();
+
+    /**
+     * Set the name of this Service.
+     *
+     * @param name The new service name
+     */
+    public void setName(String name);
+
+    /**
+     * @return the <code>Server</code> with which we are associated (if any).
+     */
+    public Server getServer();
+
+    /**
+     * Set the <code>Server</code> with which we are associated (if any).
+     *
+     * @param server The server that owns this Service
+     */
+    public 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.
+     */
+    public ClassLoader getParentClassLoader();
+
+    /**
+     * Set the parent class loader for this service.
+     *
+     * @param parent The new parent class loader
+     */
+    public void setParentClassLoader(ClassLoader parent);
+
+    /**
+     * @return the domain under which this container will be / has been
+     * registered.
+     */
+    public String getDomain();
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * 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
+     */
+    public void addConnector(Connector connector);
+
+    /**
+     * Find and return the set of Connectors associated with this Service.
+     *
+     * @return the set of associated Connectors
+     */
+    public Connector[] findConnectors();
+
+    /**
+     * 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
+     */
+    public void removeConnector(Connector connector);
+
+    /**
+     * Adds a named executor to the service
+     * @param ex Executor
+     */
+    public void addExecutor(Executor ex);
+
+    /**
+     * Retrieves all executors
+     * @return Executor[]
+     */
+    public Executor[] findExecutors();
+
+    /**
+     * Retrieves executor by name, null if not found
+     * @param name String
+     * @return Executor
+     */
+    public Executor getExecutor(String name);
+
+    /**
+     * Removes an executor from the service
+     * @param ex Executor
+     */
+    public void removeExecutor(Executor ex);
+
+    /**
+     * @return the mapper associated with this Service.
+     */
+    Mapper getMapper();
+}

java/org/apache/catalina/Session.java

@@ -0,0 +1,378 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+
+import java.security.Principal;
+import java.util.Iterator;
+
+import javax.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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Session {
+
+
+    // ----------------------------------------------------- Manifest Constants
+
+
+    /**
+     * The SessionEvent event type when a session is created.
+     */
+    public static final String SESSION_CREATED_EVENT = "createSession";
+
+
+    /**
+     * The SessionEvent event type when a session is destroyed.
+     */
+    public static final String SESSION_DESTROYED_EVENT = "destroySession";
+
+
+    /**
+     * The SessionEvent event type when a session is activated.
+     */
+    public static final String SESSION_ACTIVATED_EVENT = "activateSession";
+
+
+    /**
+     * The SessionEvent event type when a session is passivated.
+     */
+    public static final String SESSION_PASSIVATED_EVENT = "passivateSession";
+
+
+    // ------------------------------------------------------------- Properties
+
+
+    /**
+     * @return the authentication type used to authenticate our cached
+     * Principal, if any.
+     */
+    public String getAuthType();
+
+
+    /**
+     * Set the authentication type used to authenticate our cached
+     * Principal, if any.
+     *
+     * @param authType The new cached authentication type
+     */
+    public void setAuthType(String authType);
+
+
+    /**
+     * @return the creation time for this session.
+     */
+    public long getCreationTime();
+
+
+    /**
+     * @return the creation time for this session, bypassing the session validity
+     * checks.
+     */
+    public long getCreationTimeInternal();
+
+
+    /**
+     * 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
+     */
+    public void setCreationTime(long time);
+
+
+    /**
+     * @return the session identifier for this session.
+     */
+    public String getId();
+
+
+    /**
+     * @return the session identifier for this session.
+     */
+    public String getIdInternal();
+
+
+    /**
+     * 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
+     */
+    public void setId(String id);
+
+
+    /**
+     * 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?
+     */
+    public 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.
+     */
+    public long getThisAccessedTime();
+
+    /**
+     * @return the last client access time without invalidation check
+     * @see #getThisAccessedTime()
+     */
+    public 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.
+     */
+    public long getLastAccessedTime();
+
+    /**
+     * @return the last client access time without invalidation check
+     * @see #getLastAccessedTime()
+     */
+    public long getLastAccessedTimeInternal();
+
+    /**
+     * @return the idle time (in milliseconds) from last client access time.
+     */
+    public long getIdleTime();
+
+    /**
+     * @return the idle time from last client access time without invalidation check
+     * @see #getIdleTime()
+     */
+    public long getIdleTimeInternal();
+
+    /**
+     * @return the Manager within which this Session is valid.
+     */
+    public Manager getManager();
+
+
+    /**
+     * Set the Manager within which this Session is valid.
+     *
+     * @param manager The new Manager
+     */
+    public void setManager(Manager manager);
+
+
+    /**
+     * @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.
+     */
+    public 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.
+     *
+     * @param interval The new maximum interval
+     */
+    public void setMaxInactiveInterval(int interval);
+
+
+    /**
+     * Set the <code>isNew</code> flag for this session.
+     *
+     * @param isNew The new value for the <code>isNew</code> flag
+     */
+    public void setNew(boolean isNew);
+
+
+    /**
+     * @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>.
+     */
+    public 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
+     * <code>Realm.authenticate()</code> calls on every request.
+     *
+     * @param principal The new Principal, or <code>null</code> if none
+     */
+    public void setPrincipal(Principal principal);
+
+
+    /**
+     * @return the <code>HttpSession</code> for which this object
+     * is the facade.
+     */
+    public HttpSession getSession();
+
+
+    /**
+     * Set the <code>isValid</code> flag for this session.
+     *
+     * @param isValid The new value for the <code>isValid</code> flag
+     */
+    public void setValid(boolean isValid);
+
+
+    /**
+     * @return <code>true</code> if the session is still valid
+     */
+    public boolean isValid();
+
+
+    // --------------------------------------------------------- Public Methods
+
+
+    /**
+     * 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.
+     */
+    public void access();
+
+
+    /**
+     * Add a session event listener to this component.
+     *
+     * @param listener the SessionListener instance that should be notified
+     *   for session events
+     */
+    public void addSessionListener(SessionListener listener);
+
+
+    /**
+     * End access to the session.
+     */
+    public void endAccess();
+
+
+    /**
+     * Perform the internal processing required to invalidate this session,
+     * without triggering an exception if the session has already expired.
+     */
+    public 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.
+     *
+     * @param name Name of the note to be returned
+     */
+    public Object getNote(String name);
+
+
+    /**
+     * @return an Iterator containing the String names of all notes bindings
+     * that exist for this session.
+     */
+    public Iterator<String> getNoteNames();
+
+
+    /**
+     * Release all object references, and initialize instance variables, in
+     * preparation for reuse of this object.
+     */
+    public void recycle();
+
+
+    /**
+     * Remove any object bound to the specified name in the internal notes
+     * for this session.
+     *
+     * @param name Name of the note to be removed
+     */
+    public void removeNote(String name);
+
+
+    /**
+     * Remove a session event listener from this component.
+     *
+     * @param listener remove the session listener, which will no longer be
+     *     notified
+     */
+    public 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.
+     *
+     * @param name Name to which the object should be bound
+     * @param value Object to be bound to the specified name
+     */
+    public void setNote(String name, Object value);
+
+
+    /**
+     * 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?
+     */
+    public 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.
+     * <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
+     * {@link HttpSession#setAttribute(String, Object)}
+     *
+     * @param name  The attribute name
+     * @param value The attribute value
+     *
+     * @return {@code true} if distribution is supported, otherwise {@code
+     *         false}
+     */
+    public boolean isAttributeDistributable(String name, Object value);
+}

java/org/apache/catalina/SessionEvent.java

@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+
+import java.util.EventObject;
+
+
+/**
+ * General event for notifying listeners of significant changes on a Session.
+ *
+ * @author Craig R. McClanahan
+ */
+public final class SessionEvent extends EventObject {
+
+    private static final long serialVersionUID = 1L;
+
+
+    /**
+     * The event data associated with this event.
+     */
+    private final Object data;
+
+
+    /**
+     * The Session on which this event occurred.
+     */
+    private final Session session;
+
+
+    /**
+     * The event type this instance represents.
+     */
+    private final String type;
+
+
+    /**
+     * Construct a new SessionEvent with the specified parameters.
+     *
+     * @param session Session on which this event occurred
+     * @param type Event type
+     * @param data Event data
+     */
+    public SessionEvent(Session session, String type, Object data) {
+
+        super(session);
+        this.session = session;
+        this.type = type;
+        this.data = data;
+
+    }
+
+
+    /**
+     * @return the event data of this event.
+     */
+    public Object getData() {
+        return this.data;
+    }
+
+
+    /**
+     * @return the Session on which this event occurred.
+     */
+    public Session getSession() {
+        return this.session;
+    }
+
+
+    /**
+     * @return the event type of this event.
+     */
+    public String getType() {
+        return this.type;
+    }
+
+
+    @Override
+    public String toString() {
+        return "SessionEvent['" + getSession() + "','" + getType() + "']";
+    }
+
+
+}

java/org/apache/catalina/SessionIdGenerator.java

@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+public interface SessionIdGenerator {
+
+    /**
+     * @return the node identifier associated with this node which will be
+     * included in the generated session ID.
+     */
+    public String getJvmRoute();
+
+    /**
+     * Specify the node identifier associated with this node which will be
+     * included in the generated session ID.
+     *
+     * @param jvmRoute  The node identifier
+     */
+    public void setJvmRoute(String jvmRoute);
+
+    /**
+     * @return the number of bytes for a session ID
+     */
+    public int getSessionIdLength();
+
+    /**
+     * Specify the number of bytes for a session ID
+     *
+     * @param sessionIdLength   Number of bytes
+     */
+    public void setSessionIdLength(int sessionIdLength);
+
+    /**
+     * Generate and return a new session identifier.
+     *
+     * @return the newly generated session id
+     */
+    public String generateSessionId();
+
+    /**
+     * Generate and return a new session identifier.
+     *
+     * @param route   node identifier to include in generated id
+     * @return the newly generated session id
+     */
+    public String generateSessionId(String route);
+}

java/org/apache/catalina/SessionListener.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+import java.util.EventListener;
+
+
+/**
+ * Interface defining a listener for significant Session generated events.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface SessionListener extends EventListener {
+
+
+    /**
+     * Acknowledge the occurrence of the specified event.
+     *
+     * @param event SessionEvent that has occurred
+     */
+    public void sessionEvent(SessionEvent event);
+
+
+}

java/org/apache/catalina/Store.java

@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+
+import java.beans.PropertyChangeListener;
+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.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Store {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * @return the Manager instance associated with this Store.
+     */
+    public Manager getManager();
+
+
+    /**
+     * Set the Manager associated with this Store.
+     *
+     * @param manager The Manager which will use this Store.
+     */
+    public void setManager(Manager manager);
+
+
+    /**
+     * @return the number of Sessions present in this Store.
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public int getSize() throws IOException;
+
+
+    // --------------------------------------------------------- Public Methods
+
+
+    /**
+     * Add a property change listener to this component.
+     *
+     * @param listener The listener to add
+     */
+    public void addPropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * @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
+     */
+    public String[] keys() throws IOException;
+
+
+    /**
+     * 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
+     * @return the loaded Session instance
+     */
+    public 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.
+     *
+     * @param id Session identifier of the Session to be removed
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public void remove(String id) throws IOException;
+
+
+    /**
+     * Remove all Sessions from this Store.
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public void clear() throws IOException;
+
+
+    /**
+     * Remove a property change listener from this component.
+     *
+     * @param listener The listener to remove
+     */
+    public void removePropertyChangeListener(PropertyChangeListener listener);
+
+
+    /**
+     * Save the specified Session into this Store.  Any previously saved
+     * information for the associated session identifier is replaced.
+     *
+     * @param session Session to be saved
+     *
+     * @exception IOException if an input/output error occurs
+     */
+    public void save(Session session) throws IOException;
+
+
+}

java/org/apache/catalina/StoreManager.java

@@ -0,0 +1,38 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+/**
+ * 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.
+     */
+    Store getStore();
+
+    /**
+     * 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
+     */
+    void removeSuper(Session session);
+}

java/org/apache/catalina/ThreadBindingListener.java

@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+
+/**
+ * Callback for establishing naming association when entering the application
+ * scope. This corresponds to setting the context classloader.
+ */
+public interface ThreadBindingListener {
+
+    public void bind();
+    public void unbind();
+
+}

java/org/apache/catalina/TomcatPrincipal.java

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.security.Principal;
+
+import org.ietf.jgss.GSSCredential;
+
+/**
+ * Defines additional methods implemented by {@link Principal}s created by
+ * Tomcat's standard {@link Realm} implementations.
+ */
+public interface TomcatPrincipal extends Principal {
+
+    /**
+     * @return The authenticated Principal to be exposed to applications.
+     */
+    Principal getUserPrincipal();
+
+    /**
+     * @return The user's delegated credentials.
+     */
+    GSSCredential getGssCredential();
+
+    /**
+     * Calls logout, if necessary, on any associated JAASLoginContext. 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
+     *
+     */
+    void logout() throws Exception;
+}

java/org/apache/catalina/TrackedWebResource.java

@@ -0,0 +1,24 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.Closeable;
+
+public interface TrackedWebResource extends Closeable {
+    Exception getCreatedBy();
+    String getName();
+}

java/org/apache/catalina/User.java

@@ -0,0 +1,174 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+
+import java.security.Principal;
+import java.util.Iterator;
+
+
+/**
+ * <p>Abstract representation of a user in a {@link UserDatabase}.  Each user
+ * is optionally associated with a set of {@link Group}s through which he or
+ * she inherits additional security roles, and is optionally assigned a set
+ * of specific {@link Role}s.</p>
+ *
+ * @author Craig R. McClanahan
+ * @since 4.1
+ */
+public interface User extends Principal {
+
+
+    // ------------------------------------------------------------- Properties
+
+
+    /**
+     * @return the full name of this user.
+     */
+    public String getFullName();
+
+
+    /**
+     * Set the full name of this user.
+     *
+     * @param fullName The new full name
+     */
+    public void setFullName(String fullName);
+
+
+    /**
+     * @return the set of {@link Group}s to which this user belongs.
+     */
+    public Iterator<Group> getGroups();
+
+
+    /**
+     * @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>.
+     */
+    public 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>.
+     *
+     * @param password The new logon password
+     */
+    public void setPassword(String password);
+
+
+    /**
+     * @return the set of {@link Role}s assigned specifically to this user.
+     */
+    public Iterator<Role> getRoles();
+
+
+    /**
+     * @return the {@link UserDatabase} within which this User is defined.
+     */
+    public UserDatabase getUserDatabase();
+
+
+    /**
+     * @return the logon username of this user, which must be unique
+     * within the scope of a {@link UserDatabase}.
+     */
+    public String getUsername();
+
+
+    /**
+     * Set the logon username of this user, which must be unique within
+     * the scope of a {@link UserDatabase}.
+     *
+     * @param username The new logon username
+     */
+    public void setUsername(String username);
+
+
+    // --------------------------------------------------------- Public Methods
+
+
+    /**
+     * Add a new {@link Group} to those this user belongs to.
+     *
+     * @param group The new group
+     */
+    public void addGroup(Group group);
+
+
+    /**
+     * Add a {@link Role} to those assigned specifically to this user.
+     *
+     * @param role The new role
+     */
+    public void addRole(Role role);
+
+
+    /**
+     * 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
+     */
+    public 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.
+     *
+     * @param role The role to check
+     * @return <code>true</code> if the user has the specified role
+     */
+    public boolean isInRole(Role role);
+
+
+    /**
+     * Remove a {@link Group} from those this user belongs to.
+     *
+     * @param group The old group
+     */
+    public void removeGroup(Group group);
+
+
+    /**
+     * Remove all {@link Group}s from those this user belongs to.
+     */
+    public void removeGroups();
+
+
+    /**
+     * Remove a {@link Role} from those assigned to this user.
+     *
+     * @param role The old role
+     */
+    public void removeRole(Role role);
+
+
+    /**
+     * Remove all {@link Role}s from those assigned to this user.
+     */
+    public void removeRoles();
+
+
+}

java/org/apache/catalina/UserDatabase.java

@@ -0,0 +1,167 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package 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.
+ *
+ * @author Craig R. McClanahan
+ * @since 4.1
+ */
+public interface UserDatabase {
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * @return the set of {@link Group}s defined in this user database.
+     */
+    public Iterator<Group> getGroups();
+
+
+    /**
+     * @return the unique global identifier of this user database.
+     */
+    public String getId();
+
+
+    /**
+     * @return the set of {@link Role}s defined in this user database.
+     */
+    public Iterator<Role> getRoles();
+
+
+    /**
+     * @return the set of {@link User}s defined in this user database.
+     */
+    public Iterator<User> getUsers();
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Finalize access to this user database.
+     *
+     * @exception Exception if any exception is thrown during closing
+     */
+    public void close() throws Exception;
+
+
+    /**
+     * 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 description The description of this group
+     * @return The new group
+     */
+    public Group createGroup(String groupname, String description);
+
+
+    /**
+     * 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 description The description of this role
+     * @return The new role
+     */
+    public Role createRole(String rolename, String description);
+
+
+    /**
+     * Create and return a new {@link User} defined in this user database.
+     *
+     * @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
+     */
+    public User createUser(String username, String password, String fullName);
+
+
+    /**
+     * @return the {@link Group} with the specified group name, if any;
+     *         otherwise return <code>null</code>.
+     *
+     * @param groupname Name of the group to return
+     */
+    public Group findGroup(String groupname);
+
+
+    /**
+     * @return the {@link Role} with the specified role name, if any; otherwise
+     *         return <code>null</code>.
+     *
+     * @param rolename Name of the role to return
+     */
+    public Role findRole(String rolename);
+
+
+    /**
+     * @return the {@link User} with the specified user name, if any; otherwise
+     *         return <code>null</code>.
+     *
+     * @param username Name of the user to return
+     */
+    public User findUser(String username);
+
+
+    /**
+     * Initialize access to this user database.
+     *
+     * @exception Exception if any exception is thrown during opening
+     */
+    public void open() throws Exception;
+
+
+    /**
+     * Remove the specified {@link Group} from this user database.
+     *
+     * @param group The group to be removed
+     */
+    public void removeGroup(Group group);
+
+
+    /**
+     * Remove the specified {@link Role} from this user database.
+     *
+     * @param role The role to be removed
+     */
+    public void removeRole(Role role);
+
+
+    /**
+     * Remove the specified {@link User} from this user database.
+     *
+     * @param user The user to be removed
+     */
+    public void removeUser(User user);
+
+
+    /**
+     * Save any updated information to the persistent storage location for this
+     * user database.
+     *
+     * @exception Exception if any exception is thrown during saving
+     */
+    public void save() throws Exception;
+
+
+}

java/org/apache/catalina/Valve.java

@@ -0,0 +1,122 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+
+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.
+ *
+ * @author Craig R. McClanahan
+ * @author Gunnar Rjnning
+ * @author Peter Donald
+ */
+public interface Valve {
+
+
+    //-------------------------------------------------------------- Properties
+
+    /**
+     * @return the next Valve in the pipeline containing this Valve, if any.
+     */
+    public Valve getNext();
+
+
+    /**
+     * Set the next Valve in the pipeline containing this Valve.
+     *
+     * @param valve The new next valve, or <code>null</code> if none
+     */
+    public void setNext(Valve valve);
+
+
+    //---------------------------------------------------------- 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.
+     */
+    public 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>
+     * <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).
+     * </ul>
+     *
+     * <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.
+     * </ul>
+     *
+     * @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
+     */
+    public void invoke(Request request, Response response)
+        throws IOException, ServletException;
+
+
+    public boolean isAsyncSupported();
+}

java/org/apache/catalina/WebResource.java

@@ -0,0 +1,171 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.InputStream;
+import java.net.URL;
+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}.
+ */
+public interface WebResource {
+    /**
+     * @return {@link java.io.File#lastModified()}.
+     */
+    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.
+     */
+    String getLastModifiedHttp();
+
+    /**
+     * @return {@link java.io.File#exists()}.
+     */
+    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.
+     *
+     * @return <code>true</code> for a virtual resource
+     */
+    boolean isVirtual();
+
+    /**
+     * @return {@link java.io.File#isDirectory()}.
+     */
+    boolean isDirectory();
+
+    /**
+     * @return {@link java.io.File#isFile()}.
+     */
+    boolean isFile();
+
+    /**
+     * @return {@link java.io.File#delete()}.
+     */
+    boolean delete();
+
+    /**
+     * @return {@link java.io.File#getName()}.
+     */
+    String getName();
+
+    /**
+     * @return {@link java.io.File#length()}.
+     */
+    long getContentLength();
+
+    /**
+     * @return {@link java.io.File#getCanonicalPath()}.
+     */
+    String getCanonicalPath();
+
+    /**
+     * @return {@link java.io.File#canRead()}.
+     */
+    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 '/'.
+     */
+    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 ETag for this resource
+     */
+    String getETag();
+
+    /**
+     * Set the MIME type for this Resource.
+     *
+     * @param mimeType The mime type that will be associated with the resource
+     */
+    void setMimeType(String mimeType);
+
+    /**
+     * @return the MIME type for this Resource.
+     */
+    String getMimeType();
+
+    /**
+     * 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
+     */
+    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.
+     */
+    byte[] getContent();
+
+    /**
+     * @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.
+     */
+    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.
+     */
+    URL getCodeBase();
+
+    /**
+     * @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.
+     *
+     * @see java.util.jar.JarEntry#getCertificates()
+     */
+    Certificate[] getCertificates();
+
+    /**
+     * @return the manifest associated with this resource or @null if none.
+     *
+     * @see java.util.jar.JarFile#getManifest()
+     */
+    Manifest getManifest();
+}

java/org/apache/catalina/WebResourceRoot.java

@@ -0,0 +1,440 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.InputStream;
+import java.net.URL;
+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:
+ * <ol>
+ * <li>Pre  - Resources defined by the &lt;PreResource&gt; 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 &lt;PostResource&gt; 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.
+ * </ul>
+ * 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>
+ * </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
+ */
+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 path 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 '/'.
+     *
+     * @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 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 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
+     */
+    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.
+     *
+     * @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
+     */
+    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)
+     *
+     * @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.
+     */
+    WebResource[] getClassLoaderResources(String path);
+
+    /**
+     * 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 '/'.
+     *
+     * @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.
+     *
+     * @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.
+     */
+    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 '/'.
+     *
+     * @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 '/'.
+     *
+     * @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
+     */
+    boolean write(String path, InputStream is, boolean overwrite);
+
+    /**
+     * 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 '/'.
+     */
+    void createWebResourceSet(ResourceSetType type, String webAppMount, URL url,
+            String internalPath);
+
+    /**
+     * 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 '/'.
+     */
+    void createWebResourceSet(ResourceSetType type, String webAppMount,
+            String base, String archivePath, String internalPath);
+
+
+    /**
+     * 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.
+     */
+    WebResourceSet[] getPreResources();
+
+    /**
+     * 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.
+     */
+    WebResourceSet[] getJarResources();
+
+    /**
+     * 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.
+     */
+    WebResourceSet[] getPostResources();
+
+    /**
+     * @return the web application this WebResourceRoot is associated with.
+     */
+    Context getContext();
+
+    /**
+     * Set the web application this WebResourceRoot is associated with.
+     *
+     * @param context the associated context
+     */
+    void setContext(Context context);
+
+    /**
+     * Configure if this resources allow the use of symbolic links.
+     *
+     * @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
+     */
+    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>
+     */
+    void setCachingAllowed(boolean cachingAllowed);
+
+    /**
+     * @return <code>true</code> if caching is permitted for this web application.
+     */
+    boolean isCachingAllowed();
+
+    /**
+     * Set the Time-To-Live (TTL) for cache entries.
+     *
+     * @param ttl   TTL in milliseconds
+     */
+    void setCacheTtl(long ttl);
+
+    /**
+     * Get the Time-To-Live (TTL) for cache entries.
+     *
+     * @return  TTL in milliseconds
+     */
+    long getCacheTtl();
+
+    /**
+     * Set the maximum permitted size for the cache.
+     *
+     * @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
+     */
+    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}.
+     *
+     * @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}.
+     *
+     * @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.
+     * <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>
+     * </ul>
+     *
+     * @param trackLockedFiles {@code true} to enable it, {@code false} to
+     *                         disable it
+     */
+    void setTrackLockedFiles(boolean trackLockedFiles);
+
+    /**
+     * Has the track locked files feature been enabled?
+     *
+     * @return {@code true} if it has been enabled, otherwise {@code false}
+     */
+    boolean getTrackLockedFiles();
+
+    /**
+     * 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.
+     * @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.
+     */
+    List<URL> getBaseUrls();
+
+    /**
+     * Implementations may cache some information to improve performance. This
+     * method triggers the clean-up of those resources.
+     */
+    void gc();
+
+    enum ResourceSetType {
+        PRE,
+        RESOURCE_JAR,
+        POST,
+        CLASSES_JAR
+    }
+}

java/org/apache/catalina/WebResourceSet.java

@@ -0,0 +1,156 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina;
+
+import java.io.InputStream;
+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.
+ */
+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.
+     *
+     * @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
+     */
+    WebResource getResource(String path);
+
+    /**
+     * 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 '/'.
+     *
+     * @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.
+     *
+     * @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.
+     */
+    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 '/'.
+     *
+     * @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
+     */
+    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
+     * 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>
+     */
+    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>
+     */
+    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.
+     *
+     * @return The base URL for this set of resources
+     */
+    URL getBaseUrl();
+
+    /**
+     * 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
+     *
+     * @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.
+     *
+     * @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.
+     */
+    void gc();
+}

java/org/apache/catalina/Wrapper.java

@@ -0,0 +1,403 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package org.apache.catalina;
+
+
+import javax.servlet.MultipartConfigElement;
+import javax.servlet.Servlet;
+import javax.servlet.ServletException;
+import javax.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.
+ * <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, as well as respecting the existence of
+ * the SingleThreadModel declaration on the servlet class itself.
+ * <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.
+ * <p>
+ * Child Containers are not allowed on Wrapper implementations, so the
+ * <code>addChild()</code> method should throw an
+ * <code>IllegalArgumentException</code>.
+ *
+ * @author Craig R. McClanahan
+ */
+public interface Wrapper extends Container {
+
+    /**
+     * Container event for adding a wrapper.
+     */
+    public static final String ADD_MAPPING_EVENT = "addMapping";
+
+    /**
+     * Container event for removing a wrapper.
+     */
+    public static final String REMOVE_MAPPING_EVENT = "removeMapping";
+
+    // ------------------------------------------------------------- Properties
+
+
+    /**
+     * @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.
+     */
+    public 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.
+     *
+     * @param available The new available date/time
+     */
+    public void setAvailable(long available);
+
+
+    /**
+     * @return the load-on-startup order value (negative value means
+     * load on first call).
+     */
+    public int getLoadOnStartup();
+
+
+    /**
+     * Set the load-on-startup order value (negative value means
+     * load on first call).
+     *
+     * @param value New load-on-startup value
+     */
+    public void setLoadOnStartup(int value);
+
+
+    /**
+     * @return the run-as identity for this servlet.
+     */
+    public String getRunAs();
+
+
+    /**
+     * Set the run-as identity for this servlet.
+     *
+     * @param runAs New run-as identity value
+     */
+    public void setRunAs(String runAs);
+
+
+    /**
+     * @return the fully qualified servlet class name for this servlet.
+     */
+    public String getServletClass();
+
+
+    /**
+     * Set the fully qualified servlet class name for this servlet.
+     *
+     * @param servletClass Servlet class name
+     */
+    public void setServletClass(String servletClass);
+
+
+    /**
+     * 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.
+     *
+     * @return Array of names of the methods supported by the underlying
+     *         servlet
+     *
+     * @throws ServletException If the target servlet cannot be loaded
+     */
+    public String[] getServletMethods() throws ServletException;
+
+
+    /**
+     * @return <code>true</code> if this Servlet is currently unavailable.
+     */
+    public boolean isUnavailable();
+
+
+    /**
+     * @return the associated Servlet instance.
+     */
+    public Servlet getServlet();
+
+
+    /**
+     * Set the associated Servlet instance
+     *
+     * @param servlet The associated Servlet
+     */
+    public void setServlet(Servlet servlet);
+
+    // --------------------------------------------------------- Public Methods
+
+
+    /**
+     * Add a new servlet initialization parameter for this servlet.
+     *
+     * @param name Name of this initialization parameter to add
+     * @param value Value of this initialization parameter to add
+     */
+    public void addInitParameter(String name, String value);
+
+
+    /**
+     * Add a mapping associated with the Wrapper.
+     *
+     * @param mapping The new wrapper mapping
+     */
+    public void addMapping(String mapping);
+
+
+    /**
+     * 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
+     */
+    public void addSecurityReference(String name, String link);
+
+
+    /**
+     * Allocate an initialized instance of this Servlet that is ready to have
+     * its <code>service()</code> method called.  If the Servlet class does
+     * not implement <code>SingleThreadModel</code>, the (only) initialized
+     * instance may be returned immediately.  If the Servlet class implements
+     * <code>SingleThreadModel</code>, the Wrapper implementation must ensure
+     * that this instance is not allocated again until it is deallocated by a
+     * call to <code>deallocate()</code>.
+     *
+     * @exception ServletException if the Servlet init() method threw
+     *  an exception
+     * @exception ServletException if a loading error occurs
+     * @return a new Servlet instance
+     */
+    public Servlet allocate() throws ServletException;
+
+
+    /**
+     * Return this previously allocated servlet to the pool of available
+     * instances.  If this servlet class does not implement SingleThreadModel,
+     * no action is actually required.
+     *
+     * @param servlet The servlet to be returned
+     *
+     * @exception ServletException if a deallocation error occurs
+     */
+    public void deallocate(Servlet servlet) throws ServletException;
+
+
+    /**
+     * @return the value for the specified initialization parameter name,
+     * if any; otherwise return <code>null</code>.
+     *
+     * @param name Name of the requested initialization parameter
+     */
+    public String findInitParameter(String name);
+
+
+    /**
+     * @return the names of all defined initialization parameters for this
+     * servlet.
+     */
+    public String[] findInitParameters();
+
+
+    /**
+     * @return the mappings associated with this wrapper.
+     */
+    public String[] findMappings();
+
+
+    /**
+     * @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
+     */
+    public String findSecurityReference(String name);
+
+
+    /**
+     * @return the set of security role reference names associated with
+     * this servlet, if any; otherwise return a zero-length array.
+     */
+    public String[] findSecurityReferences();
+
+
+    /**
+     * Increment the error count value used when monitoring.
+     */
+    public void incrementErrorCount();
+
+
+    /**
+     * 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
+     */
+    public void load() throws ServletException;
+
+
+    /**
+     * Remove the specified initialization parameter from this Servlet.
+     *
+     * @param name Name of the initialization parameter to remove
+     */
+    public void removeInitParameter(String name);
+
+
+    /**
+     * Remove a mapping associated with the wrapper.
+     *
+     * @param mapping The pattern to remove
+     */
+    public void removeMapping(String mapping);
+
+
+    /**
+     * Remove any security role reference for the specified role name.
+     *
+     * @param name Security role used within this servlet to be removed
+     */
+    public void removeSecurityReference(String name);
+
+
+    /**
+     * 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
+     */
+    public 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.
+     *
+     * @exception ServletException if an unload error occurs
+     */
+    public void unload() throws ServletException;
+
+
+    /**
+     * @return the multi-part configuration for the associated Servlet. If no
+     * multi-part configuration has been defined, then <code>null</code> will be
+     * returned.
+     */
+    public 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.
+     *
+     * @param multipartConfig The configuration associated with the Servlet
+     */
+    public void setMultipartConfigElement(
+            MultipartConfigElement multipartConfig);
+
+    /**
+     * Does the associated Servlet support async processing? Defaults to
+     * <code>false</code>.
+     *
+     * @return <code>true</code> if the Servlet supports async
+     */
+    public boolean isAsyncSupported();
+
+    /**
+     * Set the async support for the associated Servlet.
+     *
+     * @param asyncSupport the new value
+     */
+    public void setAsyncSupported(boolean asyncSupport);
+
+    /**
+     * Is the associated Servlet enabled? Defaults to <code>true</code>.
+     *
+     * @return <code>true</code> if the Servlet is enabled
+     */
+    public boolean isEnabled();
+
+    /**
+     * Sets the enabled attribute for the associated servlet.
+     *
+     * @param enabled the new value
+     */
+    public void setEnabled(boolean enabled);
+
+    /**
+     * This method is no longer used. All implementations should be NO-OPs.
+     *
+     * @param b Unused.
+     *
+     * @deprecated This will be removed in Tomcat 9.
+     */
+    @Deprecated
+    public void setServletSecurityAnnotationScanRequired(boolean b);
+
+    /**
+     * This method is no longer used. All implementations should be NO-OPs.
+     *
+     * @throws ServletException Never thrown
+     *
+     * @deprecated This will be removed in Tomcat 9.
+     */
+    @Deprecated
+    public void servletSecurityAnnotationScan() throws ServletException;
+
+    /**
+     * Is the Servlet overridable by a ServletContainerInitializer?
+     *
+     * @return <code>true</code> if the Servlet can be overridden in a ServletContainerInitializer
+     */
+    public boolean isOverridable();
+
+    /**
+     * Sets the overridable attribute for this Servlet.
+     *
+     * @param overridable the new value
+     */
+    public void setOverridable(boolean overridable);
+}

java/org/apache/catalina/ant/AbstractCatalinaCommandTask.java

@@ -0,0 +1,84 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina.ant;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLEncoder;
+
+import org.apache.tools.ant.BuildException;
+
+public abstract class AbstractCatalinaCommandTask extends AbstractCatalinaTask {
+
+    /**
+     * The context path of the web application we are managing.
+     */
+    protected String path = null;
+
+    public String getPath() {
+        return this.path;
+    }
+
+    public void setPath(String path) {
+        this.path = path;
+    }
+
+    /**
+     * The context version of the web application we are managing.
+     */
+    protected String version = null;
+
+    public String getVersion() {
+        return this.version;
+    }
+
+    public void setVersion(String version) {
+        this.version = version;
+    }
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Create query string for the specified command.
+     *
+     * @param command Command to be executed
+     *
+     * @return The generated query string
+     *
+     * @exception BuildException if an error occurs
+     */
+    public StringBuilder createQueryString(String command) throws BuildException {
+        StringBuilder buffer = new StringBuilder();
+
+        try {
+            buffer.append(command);
+            if (path == null) {
+                throw new BuildException("Must specify 'path' attribute");
+            } else {
+                buffer.append("?path=");
+                buffer.append(URLEncoder.encode(this.path, getCharset()));
+                if (this.version != null) {
+                    buffer.append("&version=");
+                    buffer.append(URLEncoder.encode(this.version, getCharset()));
+                }
+            }
+        } catch (UnsupportedEncodingException e) {
+            throw new BuildException("Invalid 'charset' attribute: " + getCharset());
+        }
+        return buffer;
+    }
+}

java/org/apache/catalina/ant/AbstractCatalinaTask.java

@@ -0,0 +1,341 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina.ant;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.io.OutputStream;
+import java.net.Authenticator;
+import java.net.HttpURLConnection;
+import java.net.PasswordAuthentication;
+import java.net.URL;
+import java.net.URLConnection;
+
+import org.apache.catalina.util.IOTools;
+import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.Project;
+
+/**
+ * Abstract base class for Ant tasks that interact with the <em>Manager</em> web
+ * application for dynamically deploying and undeploying applications. These
+ * tasks require Ant 1.4 or later.
+ *
+ * @author Craig R. McClanahan
+ * @since 4.1
+ */
+public abstract class AbstractCatalinaTask extends BaseRedirectorHelperTask {
+
+    // ----------------------------------------------------- Instance Variables
+
+    /**
+     * manager webapp's encoding.
+     */
+    private static final String CHARSET = "utf-8";
+
+
+    // ------------------------------------------------------------- Properties
+
+    /**
+     * The charset used during URL encoding.
+     */
+    protected String charset = "ISO-8859-1";
+
+    public String getCharset() {
+        return charset;
+    }
+
+    public void setCharset(String charset) {
+        this.charset = charset;
+    }
+
+
+    /**
+     * The login password for the <code>Manager</code> application.
+     */
+    protected String password = null;
+
+    public String getPassword() {
+        return this.password;
+    }
+
+    public void setPassword(String password) {
+        this.password = password;
+    }
+
+
+    /**
+     * The URL of the <code>Manager</code> application to be used.
+     */
+    protected String url = "http://localhost:8080/manager/text";
+
+    public String getUrl() {
+        return this.url;
+    }
+
+    public void setUrl(String url) {
+        this.url = url;
+    }
+
+
+    /**
+     * The login username for the <code>Manager</code> application.
+     */
+    protected String username = null;
+
+    public String getUsername() {
+        return this.username;
+    }
+
+    public void setUsername(String username) {
+        this.username = username;
+    }
+
+    /**
+     * If set to true - ignore the constraint of the first line of the response
+     * message that must be "OK -".
+     * <p>
+     * When this attribute is set to {@code false} (the default), the first line
+     * of server response is expected to start with "OK -". If it does not then
+     * the task is considered as failed and the first line is treated as an
+     * error message.
+     * <p>
+     * When this attribute is set to {@code true}, the first line of the
+     * response is treated like any other, regardless of its text.
+     */
+    protected boolean ignoreResponseConstraint = false;
+
+    public boolean isIgnoreResponseConstraint() {
+        return ignoreResponseConstraint;
+    }
+
+    public void setIgnoreResponseConstraint(boolean ignoreResponseConstraint) {
+        this.ignoreResponseConstraint = ignoreResponseConstraint;
+    }
+
+
+    // --------------------------------------------------------- Public Methods
+
+    /**
+     * Execute the specified command. This logic only performs the common
+     * attribute validation required by all subclasses; it does not perform any
+     * functional logic directly.
+     *
+     * @exception BuildException if a validation error occurs
+     */
+    @Override
+    public void execute() throws BuildException {
+        if ((username == null) || (password == null) || (url == null)) {
+            throw new BuildException("Must specify all of 'username', 'password', and 'url'");
+        }
+    }
+
+
+    /**
+     * Execute the specified command, based on the configured properties.
+     *
+     * @param command Command to be executed
+     *
+     * @exception BuildException if an error occurs
+     */
+    public void execute(String command) throws BuildException {
+        execute(command, null, null, -1);
+    }
+
+
+    /**
+     * Execute the specified command, based on the configured properties. The
+     * input stream will be closed upon completion of this task, whether it was
+     * executed successfully or not.
+     *
+     * @param command Command to be executed
+     * @param istream InputStream to include in an HTTP PUT, if any
+     * @param contentType Content type to specify for the input, if any
+     * @param contentLength Content length to specify for the input, if any
+     *
+     * @exception BuildException if an error occurs
+     */
+    public void execute(String command, InputStream istream, String contentType, long contentLength)
+                    throws BuildException {
+
+        URLConnection conn = null;
+        InputStreamReader reader = null;
+        try {
+            // Set up authorization with our credentials
+            Authenticator.setDefault(new TaskAuthenticator(username, password));
+
+            // Create a connection for this command
+            conn = (new URL(url + command)).openConnection();
+            HttpURLConnection hconn = (HttpURLConnection) conn;
+
+            // Set up standard connection characteristics
+            hconn.setAllowUserInteraction(false);
+            hconn.setDoInput(true);
+            hconn.setUseCaches(false);
+            if (istream != null) {
+                preAuthenticate();
+
+                hconn.setDoOutput(true);
+                hconn.setRequestMethod("PUT");
+                if (contentType != null) {
+                    hconn.setRequestProperty("Content-Type", contentType);
+                }
+                if (contentLength >= 0) {
+                    hconn.setRequestProperty("Content-Length", "" + contentLength);
+
+                    hconn.setFixedLengthStreamingMode(contentLength);
+                }
+            } else {
+                hconn.setDoOutput(false);
+                hconn.setRequestMethod("GET");
+            }
+            hconn.setRequestProperty("User-Agent", "Catalina-Ant-Task/1.0");
+
+            // Establish the connection with the server
+            hconn.connect();
+
+            // Send the request data (if any)
+            if (istream != null) {
+                try (OutputStream ostream = hconn.getOutputStream()) {
+                    IOTools.flow(istream, ostream);
+                } finally {
+                    try {
+                        istream.close();
+                    } catch (Exception e) {
+                    }
+                }
+            }
+
+            // Process the response message
+            reader = new InputStreamReader(hconn.getInputStream(), CHARSET);
+            StringBuilder buff = new StringBuilder();
+            String error = null;
+            int msgPriority = Project.MSG_INFO;
+            boolean first = true;
+            while (true) {
+                int ch = reader.read();
+                if (ch < 0) {
+                    break;
+                } else if ((ch == '\r') || (ch == '\n')) {
+                    // in Win \r\n would cause handleOutput() to be called
+                    // twice, the second time with an empty string,
+                    // producing blank lines
+                    if (buff.length() > 0) {
+                        String line = buff.toString();
+                        buff.setLength(0);
+                        if (!ignoreResponseConstraint && first) {
+                            if (!line.startsWith("OK -")) {
+                                error = line;
+                                msgPriority = Project.MSG_ERR;
+                            }
+                            first = false;
+                        }
+                        handleOutput(line, msgPriority);
+                    }
+                } else {
+                    buff.append((char) ch);
+                }
+            }
+            if (buff.length() > 0) {
+                handleOutput(buff.toString(), msgPriority);
+            }
+            if (error != null && isFailOnError()) {
+                // exception should be thrown only if failOnError == true
+                // or error line will be logged twice
+                throw new BuildException(error);
+            }
+        } catch (Exception e) {
+            if (isFailOnError()) {
+                throw new BuildException(e);
+            } else {
+                handleErrorOutput(e.getMessage());
+            }
+        } finally {
+            closeRedirector();
+            if (reader != null) {
+                try {
+                    reader.close();
+                } catch (IOException ioe) {
+                    // Ignore
+                }
+                reader = null;
+            }
+            if (istream != null) {
+                try {
+                    istream.close();
+                } catch (IOException ioe) {
+                    // Ignore
+                }
+            }
+        }
+    }
+
+
+    /*
+     * This is a hack.
+     * We need to use streaming to avoid OOME on large uploads.
+     * We'd like to use Authenticator.setDefault() for authentication as the JRE
+     * then provides the DIGEST client implementation.
+     * However, the above two are not compatible. When the request is made, the
+     * resulting 401 triggers an exception because, when using streams, the
+     * InputStream is no longer available to send with the repeated request that
+     * now includes the appropriate Authorization header.
+     * The hack is to make a simple OPTIONS request- i.e. without a request
+     * body.
+     * This triggers authentication and the requirement to authenticate for this
+     * host is cached and used to provide an appropriate Authorization when the
+     * next request is made (that includes a request body).
+     */
+    private void preAuthenticate() throws IOException {
+        URLConnection conn = null;
+
+        // Create a connection for this command
+        conn = (new URL(url)).openConnection();
+        HttpURLConnection hconn = (HttpURLConnection) conn;
+
+        // Set up standard connection characteristics
+        hconn.setAllowUserInteraction(false);
+        hconn.setDoInput(true);
+        hconn.setUseCaches(false);
+        hconn.setDoOutput(false);
+        hconn.setRequestMethod("OPTIONS");
+        hconn.setRequestProperty("User-Agent", "Catalina-Ant-Task/1.0");
+
+        // Establish the connection with the server
+        hconn.connect();
+
+        // Swallow response message
+        IOTools.flow(hconn.getInputStream(), null);
+    }
+
+
+    private static class TaskAuthenticator extends Authenticator {
+
+        private final String user;
+        private final String password;
+
+        private TaskAuthenticator(String user, String password) {
+            this.user = user;
+            this.password = password;
+        }
+
+        @Override
+        protected PasswordAuthentication getPasswordAuthentication() {
+            return new PasswordAuthentication(user, password.toCharArray());
+        }
+    }
+}

java/org/apache/catalina/ant/BaseRedirectorHelperTask.java

@@ -0,0 +1,373 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.catalina.ant;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.OutputStream;
+import java.io.PrintStream;
+
+import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.Project;
+import org.apache.tools.ant.Task;
+import org.apache.tools.ant.taskdefs.Redirector;
+import org.apache.tools.ant.types.RedirectorElement;
+
+/**
+ * Abstract base class to add output redirection support for Catalina Ant tasks.
+ * These tasks require Ant 1.5 or later.
+ * <br>
+ * <strong>WARNING:</strong> due to depends chain, Ant could call a Task more
+ * than once and this can affect the output redirection when configured. If you
+ * are collecting the output in a property, it will collect the output of only
+ * the first run, since Ant properties are immutable and once created they
+ * cannot be changed. <br>
+ * If you are collecting output in a file the file will be overwritten with the
+ * output of the last run, unless you set append="true", in which case each run
+ * will append it's output to the file.
+ *
+ *
+ * @author Gabriele Garuglieri
+ * @since 5.5
+ */
+public abstract class BaseRedirectorHelperTask extends Task {
+
+    /** Redirector helper */
+    protected final Redirector redirector = new Redirector(this);
+
+    /** Redirector element for this task */
+    protected RedirectorElement redirectorElement = null;
+
+    /** The stream for info output */
+    protected OutputStream redirectOutStream = null;
+
+    /** The stream for error output */
+    protected OutputStream redirectErrStream = null;
+
+    /** The print stream for info output */
+    PrintStream redirectOutPrintStream = null;
+
+    /** The print stream for error output */
+    PrintStream redirectErrPrintStream = null;
+
+    /**
+     * Whether to fail (with a BuildException) if ManagerServlet returns an
+     * error. The default behavior is to do so. <b> This flag does not control
+     * parameters checking. If the task is called with wrong or invalid
+     * parameters, it will throw BuildException independently from the setting
+     * of this flag. </b>
+     */
+    protected boolean failOnError = true;
+
+    /**
+     * <code>true</code> true when output redirection is requested for this task.
+     * Default is to log on Ant log.
+     */
+    protected boolean redirectOutput = false;
+
+    /**
+     * will be set to <code>true</code> when the configuration of the Redirector
+     * is complete.
+     */
+    protected boolean redirectorConfigured = false;
+
+    /**
+     * Flag which indicates that, if redirected, output should also be always
+     * sent to the log. Default is that output is sent only to redirected
+     * streams.
+     */
+    protected boolean alwaysLog = false;
+
+
+    /**
+     * Whether to fail (with a BuildException) if ManagerServlet returns an
+     * error. The default behavior is to do so.
+     *
+     * @param fail The new value of failonerror
+     */
+    public void setFailonerror(boolean fail) {
+        failOnError = fail;
+    }
+
+
+    /**
+     * Returns the value of the failOnError property.
+     *
+     * @return <code>true</code> if the task should will if an error occurs,
+     *         otherwise <code>false</code>
+     */
+    public boolean isFailOnError() {
+        return failOnError;
+    }
+
+
+    /**
+     * File the output of the task is redirected to.
+     *
+     * @param out name of the output file
+     */
+    public void setOutput(File out) {
+        redirector.setOutput(out);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * File the error output of the task is redirected to.
+     *
+     * @param error name of the error file
+     *
+     */
+    public void setError(File error) {
+        redirector.setError(error);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * Controls whether error output is logged. This is only useful when output
+     * is being redirected and error output is desired in the Ant log
+     *
+     * @param logError if true the standard error is sent to the Ant log system
+     *            and not sent to output stream.
+     */
+    public void setLogError(boolean logError) {
+        redirector.setLogError(logError);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * Property name whose value should be set to the output of the task.
+     *
+     * @param outputProperty property name
+     *
+     */
+    public void setOutputproperty(String outputProperty) {
+        redirector.setOutputProperty(outputProperty);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * Property name whose value should be set to the error of the task.
+     *
+     * @param errorProperty property name
+     *
+     */
+    public void setErrorProperty(String errorProperty) {
+        redirector.setErrorProperty(errorProperty);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * If true, append output to existing file.
+     *
+     * @param append if true, append output to existing file
+     *
+     */
+    public void setAppend(boolean append) {
+        redirector.setAppend(append);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * If true, (error and non-error) output will be redirected as specified
+     * while being sent to Ant's logging mechanism as if no redirection had
+     * taken place. Defaults to false.
+     * <br>
+     * Actually handled internally, with Ant 1.6.3 it will be handled by the
+     * <code>Redirector</code> itself.
+     *
+     * @param alwaysLog <code>boolean</code>
+     */
+    public void setAlwaysLog(boolean alwaysLog) {
+        this.alwaysLog = alwaysLog;
+        redirectOutput = true;
+    }
+
+
+    /**
+     * Whether output and error files should be created even when empty.
+     * Defaults to true.
+     *
+     * @param createEmptyFiles <CODE>boolean</CODE>.
+     */
+    public void setCreateEmptyFiles(boolean createEmptyFiles) {
+        redirector.setCreateEmptyFiles(createEmptyFiles);
+        redirectOutput = true;
+    }
+
+
+    /**
+     * Add a <CODE>RedirectorElement</CODE> to this task.
+     *
+     * @param redirectorElement <CODE>RedirectorElement</CODE>.
+     */
+    public void addConfiguredRedirector(RedirectorElement redirectorElement) {
+        if (this.redirectorElement != null) {
+            throw new BuildException("Cannot have > 1 nested <redirector>s");
+        } else {
+            this.redirectorElement = redirectorElement;
+        }
+    }
+
+
+    /**
+     * Set up properties on the Redirector from RedirectorElement if present.
+     */
+    private void configureRedirector() {
+        if (redirectorElement != null) {
+            redirectorElement.configure(redirector);
+            redirectOutput = true;
+        }
+        /*
+         * Due to depends chain, Ant could call the Task more than once, this is
+         * to prevent that we attempt to configure uselessly more than once the
+         * Redirector.
+         */
+        redirectorConfigured = true;
+    }
+
+
+    /**
+     * Set up properties on the Redirector and create output streams.
+     */
+    protected void openRedirector() {
+        if (!redirectorConfigured) {
+            configureRedirector();
+        }
+        if (redirectOutput) {
+            redirector.createStreams();
+            redirectOutStream = redirector.getOutputStream();
+            redirectOutPrintStream = new PrintStream(redirectOutStream);
+            redirectErrStream = redirector.getErrorStream();
+            redirectErrPrintStream = new PrintStream(redirectErrStream);
+        }
+    }
+
+
+    /**
+     * Ask redirector to close all the streams. It is necessary to call this
+     * method before leaving the Task to have the Streams flush their contents.
+     * If you are collecting output in a property, it will be created only if
+     * this method is called, otherwise you'll find it unset.
+     */
+    protected void closeRedirector() {
+        try {
+            if (redirectOutput && redirectOutPrintStream != null) {
+                redirector.complete();
+            }
+        } catch (IOException ioe) {
+            log("Error closing redirector: " + ioe.getMessage(), Project.MSG_ERR);
+        }
+        /*
+         * Due to depends chain, Ant could call the Task more than once, this is
+         * to prevent that we attempt to reuse the previously closed Streams.
+         */
+        redirectOutStream = null;
+        redirectOutPrintStream = null;
+        redirectErrStream = null;
+        redirectErrPrintStream = null;
+    }
+
+
+    /**
+     * Handles output with the INFO priority.
+     *
+     * @param output The output to log. Should not be <code>null</code>.
+     */
+    @Override
+    protected void handleOutput(String output) {
+        if (redirectOutput) {
+            if (redirectOutPrintStream == null) {
+                openRedirector();
+            }
+            redirectOutPrintStream.println(output);
+            if (alwaysLog) {
+                log(output, Project.MSG_INFO);
+            }
+        } else {
+            log(output, Project.MSG_INFO);
+        }
+    }
+
+
+    /**
+     * Handles output with the INFO priority and flushes the stream.
+     *
+     * @param output The output to log. Should not be <code>null</code>.
+     *
+     */
+    @Override
+    protected void handleFlush(String output) {
+        handleOutput(output);
+        redirectOutPrintStream.flush();
+    }
+
+
+    /**
+     * Handles error output with the ERR priority.
+     *
+     * @param output The error output to log. Should not be <code>null</code>.
+     */
+    @Override
+    protected void handleErrorOutput(String output) {
+        if (redirectOutput) {
+            if (redirectErrPrintStream == null) {
+                openRedirector();
+            }
+            redirectErrPrintStream.println(output);
+            if (alwaysLog) {
+                log(output, Project.MSG_ERR);
+            }
+        } else {
+            log(output, Project.MSG_ERR);
+        }
+    }
+
+
+    /**
+     * Handles error output with the ERR priority and flushes the stream.
+     *
+     * @param output The error output to log. Should not be <code>null</code>.
+     *
+     */
+    @Override
+    protected void handleErrorFlush(String output) {
+        handleErrorOutput(output);
+        redirectErrPrintStream.flush();
+    }
+
+
+    /**
+     * Handles output with ERR priority to error stream and all other priorities
+     * to output stream.
+     *
+     * @param output The output to log. Should not be <code>null</code>.
+     * @param priority The priority level that should be used
+     */
+    protected void handleOutput(String output, int priority) {
+        if (priority == Project.MSG_ERR) {
+            handleErrorOutput(output);
+        } else {
+            handleOutput(output);
+        }
+    }
+}