org.eclipse.jetty.server.handler

## Class ContextHandler

- java.lang.Object
- - org.eclipse.jetty.util.component.AbstractLifeCycle
  - - org.eclipse.jetty.util.component.AggregateLifeCycle
    - - org.eclipse.jetty.server.handler.AbstractHandler
      - - org.eclipse.jetty.server.handler.AbstractHandlerContainer
        - - org.eclipse.jetty.server.handler.HandlerWrapper
          - - org.eclipse.jetty.server.handler.ScopedHandler
            - - org.eclipse.jetty.server.handler.ContextHandler

- All Implemented Interfaces:
    Handler, HandlerContainer, Server.Graceful, Attributes, Destroyable, Dumpable, LifeCycle
  Direct Known Subclasses:
    MovedContextHandler, ServletContextHandler

      public class ContextHandler
      extends ScopedHandler
      implements Attributes, Server.Graceful

  ContextHandler. This handler wraps a call to handle by setting the context and servlet path, plus setting the context classloader.

  If the context init parameter "org.eclipse.jetty.server.context.ManagedAttributes" is set to a comma separated list of names, then they are treated as context attribute names, which if set as attributes are passed to the servers Container so that they may be managed with JMX.

  The maximum size of a form that can be processed by this context is controlled by the system properties org.eclipse.jetty.server.Request.maxFormKeys and org.eclipse.jetty.server.Request.maxFormContentSize. These can also be configured with `setMaxFormContentSize(int)` and `setMaxFormKeys(int)`

  Apache XBean:
    description="Creates a basic HTTP context"

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `ContextHandler.Context` Context.

    - ### Nested classes/interfaces inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `AbstractLifeCycle.AbstractLifeCycleListener`

    - ### Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

      `LifeCycle.Listener`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ContextHandler.Context` | `_scontext`
    `static String` | `MANAGED_ATTRIBUTES` If a context attribute with this name is set, it is interpreted as a comma separated list of attribute name.

    - ### Fields inherited from class org.eclipse.jetty.server.handler.ScopedHandler

      `_nextScope, _outerScope`

    - ### Fields inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

      `_handler`

    - ### Fields inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `_listeners, FAILED, RUNNING, STARTED, STARTING, STOPPED, STOPPING`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `ContextHandler()`
    `protected` | `ContextHandler(ContextHandler.Context context)`
    `` | `ContextHandler(HandlerContainer parent, String contextPath)`
    `` | `ContextHandler(String contextPath)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addEventListener(EventListener listener)` Add a context event listeners.
    `void` | `addLocaleEncoding(String locale, String encoding)`
    `void` | `addVirtualHosts(String[] virtualHosts)` Either set virtual hosts or add to an existing set of virtual hosts.
    `void` | `callContextDestroyed(javax.servlet.ServletContextListener l, javax.servlet.ServletContextEvent e)`
    `void` | `callContextInitialized(javax.servlet.ServletContextListener l, javax.servlet.ServletContextEvent e)`
    `boolean` | `checkContext(String target, Request baseRequest, javax.servlet.http.HttpServletResponse response)`
    `void` | `checkManagedAttribute(String name, Object value)`
    `void` | `clearAttributes()`
    `void` | `doHandle(String target, Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
    `void` | `doScope(String target, Request baseRequest, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)`
    `protected void` | `doStart()` Start the managed lifecycle beans in the order they were added.
    `protected void` | `doStop()` Stop the joined lifecycle beans in the reverse order they were added.
    `void` | `dump(Appendable out, String indent)`
    `boolean` | `getAllowNullPathInfo()`
    `Object` | `getAttribute(String name)`
    `Enumeration` | `getAttributeNames()`
    `Attributes` | `getAttributes()`
    `Resource` | `getBaseResource()`
    `ClassLoader` | `getClassLoader()`
    `String` | `getClassPath()` Make best effort to extract a file classpath from the context classloader
    `String[]` | `getConnectorNames()`
    `String` | `getContextPath()`
    `static ContextHandler.Context` | `getCurrentContext()` Get the current ServletContext implementation.
    `String` | `getDisplayName()`
    `ErrorHandler` | `getErrorHandler()`
    `EventListener[]` | `getEventListeners()`
    `String` | `getInitParameter(String name)`
    `Enumeration` | `getInitParameterNames()`
    `Map<String,String>` | `getInitParams()`
    `String` | `getLocaleEncoding(Locale locale)` Get the character encoding for a locale.
    `String` | `getLocaleEncoding(String locale)`
    `Logger` | `getLogger()`
    `int` | `getMaxFormContentSize()`
    `int` | `getMaxFormKeys()`
    `MimeTypes` | `getMimeTypes()`
    `Resource` | `getResource(String path)`
    `String` | `getResourceBase()`
    `Set<String>` | `getResourcePaths(String path)`
    `ContextHandler.Context` | `getServletContext()`
    `String[]` | `getVirtualHosts()` Get the virtual hosts for the context.
    `String[]` | `getWelcomeFiles()`
    `void` | `handle(Runnable runnable)`
    `boolean` | `isAliases()`
    `boolean` | `isAvailable()`
    `boolean` | `isCompactPath()`
    `protected boolean` | `isProtectedTarget(String target)` Check the target.
    `boolean` | `isShutdown()`
    `Class<?>` | `loadClass(String className)`
    `Resource` | `newResource(String urlOrPath)` Convert a URL or path to a Resource.
    `Resource` | `newResource(URL url)` Convert URL to Resource wrapper for `Resource.newResource(URL)` enables extensions to provide alternate resource implementations.
    `void` | `removeAttribute(String name)`
    `void` | `removeVirtualHosts(String[] virtualHosts)` Removes an array of virtual host entries, if this removes all entries the _vhosts will be set to null
    `void` | `restrictEventListener(EventListener listener)` Apply any necessary restrictions on a programmatically added listener.
    `void` | `setAliases(boolean aliases)`
    `void` | `setAllowNullPathInfo(boolean allowNullPathInfo)`
    `void` | `setAttribute(String name, Object value)`
    `void` | `setAttributes(Attributes attributes)`
    `void` | `setAvailable(boolean available)` Set Available status.
    `void` | `setBaseResource(Resource base)`
    `void` | `setClassLoader(ClassLoader classLoader)`
    `void` | `setCompactPath(boolean compactPath)`
    `void` | `setConnectorNames(String[] connectors)` Set the names of accepted connectors.
    `void` | `setContextPath(String contextPath)`
    `void` | `setDisplayName(String servletContextName)`
    `void` | `setErrorHandler(ErrorHandler errorHandler)`
    `void` | `setEventListeners(EventListener[] eventListeners)` Set the context event listeners.
    `String` | `setInitParameter(String name, String value)`
    `void` | `setLogger(Logger logger)`
    `void` | `setManagedAttribute(String name, Object value)`
    `void` | `setMaxFormContentSize(int maxSize)` Set the maximum size of a form post, to protect against DOS attacks from large forms.
    `void` | `setMaxFormKeys(int max)` Set the maximum number of form Keys to protect against DOS attack from crafted hash keys.
    `void` | `setMimeTypes(MimeTypes mimeTypes)`
    `void` | `setResourceBase(String resourceBase)`
    `void` | `setServer(Server server)`
    `void` | `setShutdown(boolean shutdown)` Set shutdown status.
    `void` | `setVirtualHosts(String[] vhosts)` Set the virtual hosts for the context.
    `void` | `setWelcomeFiles(String[] files)`
    `protected void` | `startContext()` Extensible startContext.
    `String` | `toString()`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.ScopedHandler

      `handle, never, nextHandle, nextScope`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.HandlerWrapper

      `destroy, expandChildren, getHandler, getHandlers, getNestedHandlerByClass, setHandler`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandlerContainer

      `expandHandler, findContainerOf, getChildHandlerByClass, getChildHandlers, getChildHandlersByClass`

    - ### Methods inherited from class org.eclipse.jetty.server.handler.AbstractHandler

      `dumpThis, getServer`

    - ### Methods inherited from class org.eclipse.jetty.util.component.AggregateLifeCycle

      `addBean, addBean, contains, dump, dump, dump, dump, dumpObject, dumpStdErr, getBean, getBeans, getBeans, isManaged, manage, removeBean, removeBeans, unmanage`

    - ### Methods inherited from class org.eclipse.jetty.util.component.AbstractLifeCycle

      `addLifeCycleListener, getState, getState, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.eclipse.jetty.server.Handler

      `destroy, getServer, handle`

    - ### Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

      `addLifeCycleListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeLifeCycleListener, start, stop`

- - ### Field Detail

    - #### MANAGED_ATTRIBUTES

          public static final String MANAGED_ATTRIBUTES

      If a context attribute with this name is set, it is interpreted as a comma separated list of attribute name. Any other context attributes that are set with a name from this list will result in a call to `setManagedAttribute(String, Object)`, which typically initiates the creation of a JMX MBean for the attribute value.
      See Also:
        Constant Field Values

    - #### _scontext

          protected ContextHandler.Context _scontext

  - ### Constructor Detail

    - #### ContextHandler

          public ContextHandler()

    - #### ContextHandler

          protected ContextHandler(ContextHandler.Context context)

    - #### ContextHandler

          public ContextHandler(String contextPath)

    - #### ContextHandler

          public ContextHandler(HandlerContainer parent,
                        String contextPath)

  - ### Method Detail

    - #### getCurrentContext

          public static ContextHandler.Context getCurrentContext()

      Get the current ServletContext implementation.
      Returns:
        ServletContext implementation

    - #### dump

          public void dump(Appendable out,
                  String indent)
                    throws IOException

      Specified by:
        `dump` in interface `Dumpable`
      Overrides:
        `dump` in class `AbstractHandlerContainer`
      Throws:
        `IOException`

    - #### getServletContext

          public ContextHandler.Context getServletContext()

    - #### getAllowNullPathInfo

          public boolean getAllowNullPathInfo()

      Returns:
        the allowNullPathInfo true if /context is not redirected to /context/

    - #### setAllowNullPathInfo

          public void setAllowNullPathInfo(boolean allowNullPathInfo)

      Parameters:
        `allowNullPathInfo` - true if /context is not redirected to /context/

    - #### setServer

          public void setServer(Server server)

      Specified by:
        `setServer` in interface `Handler`
      Overrides:
        `setServer` in class `HandlerWrapper`

    - #### setVirtualHosts

          public void setVirtualHosts(String[] vhosts)

      Set the virtual hosts for the context. Only requests that have a matching host header or fully qualified URL will be passed to that context with a virtual host name. A context with no virtual host names or a null virtual host name is available to all requests that are not served by a context with a matching virtual host name.
      Parameters:
        `vhosts` - Array of virtual hosts that this context responds to. A null host name or null/empty array means any hostname is acceptable. Host names may be String representation of IP addresses. Host names may start with '*.' to wildcard one level of names.

    - #### addVirtualHosts

          public void addVirtualHosts(String[] virtualHosts)

      Either set virtual hosts or add to an existing set of virtual hosts.
      Parameters:
        `virtualHosts` - Array of virtual hosts that this context responds to. A null host name or null/empty array means any hostname is acceptable. Host names may be String representation of IP addresses. Host names may start with '*.' to wildcard one level of names.

    - #### removeVirtualHosts

          public void removeVirtualHosts(String[] virtualHosts)

      Removes an array of virtual host entries, if this removes all entries the _vhosts will be set to null
      Parameters:
        `virtualHosts` - Array of virtual hosts that this context responds to. A null host name or null/empty array means any hostname is acceptable. Host names may be String representation of IP addresses. Host names may start with '*.' to wildcard one level of names.

    - #### getVirtualHosts

          public String[] getVirtualHosts()

      Get the virtual hosts for the context. Only requests that have a matching host header or fully qualified URL will be passed to that context with a virtual host name. A context with no virtual host names or a null virtual host name is available to all requests that are not served by a context with a matching virtual host name.
      Returns:
        Array of virtual hosts that this context responds to. A null host name or empty array means any hostname is acceptable. Host names may be String representation of IP addresses. Host names may start with '*.' to wildcard one level of names.

    - #### getConnectorNames

          public String[] getConnectorNames()

      Returns:
        an array of connector names that this context will accept a request from.

    - #### setConnectorNames

          public void setConnectorNames(String[] connectors)

      Set the names of accepted connectors. Names are either "host:port" or a specific configured name for a connector.
      Parameters:
        `connectors` - If non null, an array of connector names that this context will accept a request from.

    - #### getAttribute

          public Object getAttribute(String name)

      Specified by:
        `getAttribute` in interface `Attributes`

    - #### getAttributeNames

          public Enumeration getAttributeNames()

      Specified by:
        `getAttributeNames` in interface `Attributes`

    - #### getAttributes

          public Attributes getAttributes()

      Returns:
        Returns the attributes.

    - #### getClassLoader

          public ClassLoader getClassLoader()

      Returns:
        Returns the classLoader.

    - #### getClassPath

          public String getClassPath()

      Make best effort to extract a file classpath from the context classloader
      Returns:
        Returns the classLoader.

    - #### getContextPath

          public String getContextPath()

      Returns:
        Returns the _contextPath.

    - #### getInitParameter

          public String getInitParameter(String name)

    - #### setInitParameter

          public String setInitParameter(String name,
                                String value)

    - #### getInitParameterNames

          public Enumeration getInitParameterNames()

    - #### getInitParams

          public Map<String,String> getInitParams()

      Returns:
        Returns the initParams.

    - #### getDisplayName

          public String getDisplayName()

    - #### getEventListeners

          public EventListener[] getEventListeners()

    - #### setEventListeners

          public void setEventListeners(EventListener[] eventListeners)

      Set the context event listeners.
      Parameters:
        `eventListeners` - the event listeners
      See Also:
        `ServletContextListener`, `ServletContextAttributeListener`, `ServletRequestListener`, `ServletRequestAttributeListener`

    - #### addEventListener

          public void addEventListener(EventListener listener)

      Add a context event listeners.
      See Also:
        `ServletContextListener`, `ServletContextAttributeListener`, `ServletRequestListener`, `ServletRequestAttributeListener`

    - #### restrictEventListener

          public void restrictEventListener(EventListener listener)

      Apply any necessary restrictions on a programmatically added listener. Superclasses should implement.
      Parameters:
        `listener` -

    - #### isShutdown

          public boolean isShutdown()

      Returns:
        true if this context is accepting new requests

    - #### setShutdown

          public void setShutdown(boolean shutdown)

      Set shutdown status. This field allows for graceful shutdown of a context. A started context may be put into non accepting state so that existing requests can complete, but no new requests are accepted.
      Specified by:
        `setShutdown` in interface `Server.Graceful`
      Parameters:
        `shutdown` - true if this context is (not?) accepting new requests

    - #### isAvailable

          public boolean isAvailable()

      Returns:
        false if this context is unavailable (sends 503)

    - #### setAvailable

          public void setAvailable(boolean available)

      Set Available status.

    - #### getLogger

          public Logger getLogger()

    - #### setLogger

          public void setLogger(Logger logger)

    - #### doStart

          protected void doStart()
                          throws Exception

      Description copied from class: `AggregateLifeCycle`
      Start the managed lifecycle beans in the order they were added.
      Overrides:
        `doStart` in class `ScopedHandler`
      Throws:
        `Exception`
      See Also:
        `HandlerWrapper.doStart()`

    - #### startContext

          protected void startContext()
                               throws Exception

      Extensible startContext. this method is called from `doStart()` instead of a call to super.doStart(). This allows derived classes to insert additional handling (Eg configuration) before the call to super.doStart by this method will start contained handlers.
      Throws:
        `Exception`
      See Also:
        `ContextHandler.Context`

    - #### callContextInitialized

          public void callContextInitialized(javax.servlet.ServletContextListener l,
                                    javax.servlet.ServletContextEvent e)

    - #### callContextDestroyed

          public void callContextDestroyed(javax.servlet.ServletContextListener l,
                                  javax.servlet.ServletContextEvent e)

    - #### doStop

          protected void doStop()
                         throws Exception

      Description copied from class: `AggregateLifeCycle`
      Stop the joined lifecycle beans in the reverse order they were added.
      Overrides:
        `doStop` in class `HandlerWrapper`
      Throws:
        `Exception`
      See Also:
        `AbstractLifeCycle.doStart()`

    - #### checkContext

          public boolean checkContext(String target,
                             Request baseRequest,
                             javax.servlet.http.HttpServletResponse response)
                               throws IOException,
                                      javax.servlet.ServletException

      Throws:
        `IOException`
        `javax.servlet.ServletException`

    - #### doScope

          public void doScope(String target,
                     Request baseRequest,
                     javax.servlet.http.HttpServletRequest request,
                     javax.servlet.http.HttpServletResponse response)
                       throws IOException,
                              javax.servlet.ServletException

      Specified by:
        `doScope` in class `ScopedHandler`
      Throws:
        `IOException`
        `javax.servlet.ServletException`
      See Also:
        `ScopedHandler.doScope(java.lang.String, org.eclipse.jetty.server.Request, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

    - #### doHandle

          public void doHandle(String target,
                      Request baseRequest,
                      javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response)
                        throws IOException,
                               javax.servlet.ServletException

      Specified by:
        `doHandle` in class `ScopedHandler`
      Throws:
        `IOException`
        `javax.servlet.ServletException`
      See Also:
        `ScopedHandler.doHandle(java.lang.String, org.eclipse.jetty.server.Request, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)`

    - #### handle

          public void handle(Runnable runnable)

    - #### isProtectedTarget

          protected boolean isProtectedTarget(String target)

      Check the target. Called by `ScopedHandler.handle(String, Request, HttpServletRequest, HttpServletResponse)` when a target within a context is determined. If the target is protected, 404 is returned. The default implementation always returns false.

    - #### removeAttribute

          public void removeAttribute(String name)

      Specified by:
        `removeAttribute` in interface `Attributes`

    - #### setAttribute

          public void setAttribute(String name,
                          Object value)

      Specified by:
        `setAttribute` in interface `Attributes`

    - #### setAttributes

          public void setAttributes(Attributes attributes)

      Parameters:
        `attributes` - The attributes to set.

    - #### clearAttributes

          public void clearAttributes()

      Specified by:
        `clearAttributes` in interface `Attributes`

    - #### checkManagedAttribute

          public void checkManagedAttribute(String name,
                                   Object value)

    - #### setManagedAttribute

          public void setManagedAttribute(String name,
                                 Object value)

    - #### setClassLoader

          public void setClassLoader(ClassLoader classLoader)

      Parameters:
        `classLoader` - The classLoader to set.

    - #### setContextPath

          public void setContextPath(String contextPath)

      Parameters:
        `contextPath` - The _contextPath to set.

    - #### setDisplayName

          public void setDisplayName(String servletContextName)

      Parameters:
        `servletContextName` - The servletContextName to set.

    - #### getBaseResource

          public Resource getBaseResource()

      Returns:
        Returns the resourceBase.

    - #### getResourceBase

          public String getResourceBase()

      Returns:
        Returns the base resource as a string.

    - #### setBaseResource

          public void setBaseResource(Resource base)

      Parameters:
        `base` - The resourceBase to set.

    - #### setResourceBase

          public void setResourceBase(String resourceBase)

      Parameters:
        `resourceBase` - The base resource as a string.

    - #### isAliases

          public boolean isAliases()

      Returns:
        True if aliases are allowed

    - #### setAliases

          public void setAliases(boolean aliases)

      Parameters:
        `aliases` - aliases are allowed

    - #### getMimeTypes

          public MimeTypes getMimeTypes()

      Returns:
        Returns the mimeTypes.

    - #### setMimeTypes

          public void setMimeTypes(MimeTypes mimeTypes)

      Parameters:
        `mimeTypes` - The mimeTypes to set.

    - #### setWelcomeFiles

          public void setWelcomeFiles(String[] files)

    - #### getWelcomeFiles

          public String[] getWelcomeFiles()

      Returns:
        The names of the files which the server should consider to be welcome files in this context.
      See Also:
        The Servlet Specification, `setWelcomeFiles(java.lang.String[])`

    - #### getErrorHandler

          public ErrorHandler getErrorHandler()

      Returns:
        Returns the errorHandler.

    - #### setErrorHandler

          public void setErrorHandler(ErrorHandler errorHandler)

      Parameters:
        `errorHandler` - The errorHandler to set.

    - #### getMaxFormContentSize

          public int getMaxFormContentSize()

    - #### setMaxFormContentSize

          public void setMaxFormContentSize(int maxSize)

      Set the maximum size of a form post, to protect against DOS attacks from large forms.
      Parameters:
        `maxSize` -

    - #### getMaxFormKeys

          public int getMaxFormKeys()

    - #### setMaxFormKeys

          public void setMaxFormKeys(int max)

      Set the maximum number of form Keys to protect against DOS attack from crafted hash keys.
      Parameters:
        `max` -

    - #### isCompactPath

          public boolean isCompactPath()

      Returns:
        True if URLs are compacted to replace multiple '/'s with a single '/'

    - #### setCompactPath

          public void setCompactPath(boolean compactPath)

      Parameters:
        `compactPath` - True if URLs are compacted to replace multiple '/'s with a single '/'

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### loadClass

          public Class<?> loadClass(String className)
                             throws ClassNotFoundException

      Throws:
        `ClassNotFoundException`

    - #### addLocaleEncoding

          public void addLocaleEncoding(String locale,
                               String encoding)

    - #### getLocaleEncoding

          public String getLocaleEncoding(String locale)

    - #### getLocaleEncoding

          public String getLocaleEncoding(Locale locale)

      Get the character encoding for a locale. The full locale name is first looked up in the map of encodings. If no encoding is found, then the locale language is looked up.
      Parameters:
        `locale` - a `Locale` value
      Returns:
        a `String` representing the character encoding for the locale or null if none found.

    - #### getResource

          public Resource getResource(String path)
                               throws MalformedURLException

      Throws:
        `MalformedURLException`

    - #### newResource

          public Resource newResource(URL url)
                               throws IOException

      Convert URL to Resource wrapper for `Resource.newResource(URL)` enables extensions to provide alternate resource implementations.
      Throws:
        `IOException`

    - #### newResource

          public Resource newResource(String urlOrPath)
                               throws IOException

      Convert a URL or path to a Resource. The default implementation is a wrapper for `Resource.newResource(String)`.
      Parameters:
        `urlOrPath` - The URL or path to convert
      Returns:
        The Resource for the URL/path
      Throws:
        `IOException` - The Resource could not be created.

    - #### getResourcePaths

          public Set<String> getResourcePaths(String path)

Copyright © 1995-2012 Mort Bay Consulting. All Rights Reserved.