## org.mortbay.http
Class HttpServer

    java.lang.Object
      |
      +--org.mortbay.http.HttpServer

All Implemented Interfaces:
  LifeCycle, java.io.Serializable

Direct Known Subclasses:
  Server

public class HttpServer
extends java.lang.Object
implements LifeCycle, java.io.Serializable

HTTP Server. Services HTTP requests by maintaining a mapping between a collection of HttpListeners which generate requests and HttpContexts which contain collections of HttpHandlers. This class is configured by API calls. The org.mortbay.jetty.Server class uses XML configuration files to configure instances of this class. The HttpServer implements the BeanContext API so that membership events may be generated for HttpListeners, HttpContexts and WebApplications.

Version:
  $Id: HttpServer.java,v 1.49.2.1 2003/10/16 06:58:06 gregwilkins Exp $
Author:
  Greg Wilkins (gregw)
See Also:
  `HttpContext`, `HttpHandler`, `HttpConnection`, `HttpListener`, `Server`, Serialized Form

Nested Class Summary
`class` `HttpServer.ComponentEvent`
`static interface` `HttpServer.ComponentEventListener`

Constructor Summary
`HttpServer()` Constructor.
`HttpServer(boolean anonymous)` Constructor.

Method Summary
`HttpContext` `addContext(HttpContext context)` Add a context.
`HttpContext` `addContext(java.lang.String contextPath)` Create and add a new context.
`HttpContext` `addContext(java.lang.String virtualHost, HttpContext context)` Add a context.
`HttpContext` `addContext(java.lang.String virtualHost, java.lang.String contextPathSpec)` Create and add a new context.
`void` `addEventListener(java.util.EventListener listener)` Add a server event listener.
`void` `addHostAlias(java.lang.String virtualHost, java.lang.String alias)` Deprecated. Use HttpContext.addVirtualHost
`HttpListener` `addListener(HttpListener listener)` Add a HTTP Listener to the server.
`HttpListener` `addListener(InetAddrPort address)` Create and add a SocketListener.
`HttpListener` `addListener(java.lang.String address)` Create and add a SocketListener.
`UserRealm` `addRealm(UserRealm realm)`
`void` `destroy()` Destroy a stopped server.
`HttpHandler` `findHandler(java.lang.Class handlerClass, java.lang.String uri, java.lang.String[] vhosts)` Find handler.
`int` `getConnections()`
`long` `getConnectionsDurationAve()`
`long` `getConnectionsDurationMax()`
`int` `getConnectionsOpen()`
`int` `getConnectionsOpenMax()`
`int` `getConnectionsRequestsAve()`
`int` `getConnectionsRequestsMax()`
`HttpContext` `getContext(java.lang.String contextPathSpec)` Get or create context.
`HttpContext` `getContext(java.lang.String virtualHost, java.lang.String contextPathSpec)` Get or create context.
`HttpContext` `getContext(java.lang.String virtualHost, java.lang.String contextPathSpec, int i)` Get specific context.
`HttpContext[]` `getContexts()`
`int` `getErrors()`
`java.util.Map` `getHostMap()`
`static java.util.List` `getHttpServerList()` Deprecated. User getHttpServers()
`static java.util.Collection` `getHttpServers()` Get HttpServer Collection.
`HttpListener[]` `getListeners()`
`UserRealm` `getRealm(java.lang.String realmName)` Get a named UserRealm.
`RequestLog` `getRequestLog()`
`int` `getRequests()`
`int` `getRequestsActive()`
`int` `getRequestsActiveMax()`
`long` `getRequestsDurationAve()`
`long` `getRequestsDurationMax()`
`int` `getRequestsPerGC()` Get the requests per GC.
`boolean` `getResolveRemoteHost()`
`boolean` `getStatsOn()`
`long` `getStatsOnMs()`
`boolean` `getTrace()`
`boolean` `isStarted()`
`void` `join()` Join the listeners.
`static void` `main(java.lang.String[] args)` Construct server from command line arguments.
`boolean` `removeContext(HttpContext context)` Remove a context or Web application.
`void` `removeEventListener(java.util.EventListener listener)`
`void` `removeListener(HttpListener listener)` Remove a HTTP Listener.
`UserRealm` `removeRealm(java.lang.String realmName)`
`void` `save(java.lang.String saveat)` Save the HttpServer The server is saved by serialization to the given filename or URL.
`HttpContext` `service(HttpRequest request, HttpResponse response)` Service a request.
`void` `setAnonymous(boolean anonymous)`
`void` `setChunkingForced(boolean forced)` Deprecated.
`void` `setContexts(HttpContext[] contexts)`
`void` `setListeners(HttpListener[] listeners)`
`void` `setRequestLog(RequestLog log)` Set the request log.
`void` `setRequestsPerGC(int requestsPerGC)` Set the requests per GC.
`void` `setResolveRemoteHost(boolean resolveRemoteHost)`
`void` `setStatsOn(boolean on)`
`void` `setTrace(boolean trace)`
`void` `start()` Start all handlers then listeners.
`void` `statsReset()` Reset statistics.
`void` `stop()` Stop all listeners then all contexts.
`void` `stop(boolean graceful)` Stop all listeners then all contexts.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### HttpServer

    public HttpServer()

  Constructor.

### HttpServer

    public HttpServer(boolean anonymous)

  Constructor.

Parameters:
  `anonymous` - If true, the server is not included in the static server lists and stopAll methods.

Method Detail

### getHttpServers

    public static java.util.Collection getHttpServers()

  Get HttpServer Collection. Get a collection of all known HttpServers. Servers can be removed from this list with the setAnonymous call.

  Returns:
    Collection of all servers.

### getHttpServerList

    public static java.util.List getHttpServerList()

  Deprecated. User getHttpServers()

### setAnonymous

    public void setAnonymous(boolean anonymous)

  Parameters:
    `anonymous` - If true, the server is not included in the static server lists and stopAll methods.

### setListeners

    public void setListeners(HttpListener[] listeners)

  Parameters:
    `listeners` - Array of HttpListeners.

### getListeners

    public HttpListener[] getListeners()

  Returns:
    Array of HttpListeners.

### addListener

    public HttpListener addListener(java.lang.String address)
                             throws java.io.IOException

  Create and add a SocketListener. Conveniance method.

  Parameters:
    `address` -
  Returns:
    the HttpListener.
  Throws:
    `java.io.IOException`

### addListener

    public HttpListener addListener(InetAddrPort address)
                             throws java.io.IOException

  Create and add a SocketListener. Conveniance method.

  Parameters:
    `address` -
  Returns:
    the HttpListener.
  Throws:
    `java.io.IOException`

### addListener

    public HttpListener addListener(HttpListener listener)
                             throws java.lang.IllegalArgumentException

  Add a HTTP Listener to the server.

  Parameters:
    `listener` - The Listener.
  Throws:
    `java.lang.IllegalArgumentException` - If the listener is not for this server.

### removeListener

    public void removeListener(HttpListener listener)

  Remove a HTTP Listener.

  Parameters:
    `listener` -

### setContexts

    public void setContexts(HttpContext[] contexts)

### getContexts

    public HttpContext[] getContexts()

### addContext

    public HttpContext addContext(HttpContext context)

  Add a context.

  Parameters:
    `context` -

### removeContext

    public boolean removeContext(HttpContext context)
                          throws java.lang.IllegalStateException

  Remove a context or Web application.

  Throws:
    `java.lang.IllegalStateException` - if context not stopped

### addContext

    public HttpContext addContext(java.lang.String virtualHost,
                                  HttpContext context)

  Add a context. As contexts cannot be publicly created, this may be used to alias an existing context.

  Parameters:
    `virtualHost` - The virtual host or null for all hosts.
    `context` -

### addContext

    public HttpContext addContext(java.lang.String contextPath)

  Create and add a new context. Note that multiple contexts can be created for the same virtualHost and contextPath. Requests are offered to multiple contexts in the order they where added to the HttpServer.

  Parameters:
    `contextPath` -
  Returns:
    A HttpContext instance created by a call to newHttpContext.

### addContext

    public HttpContext addContext(java.lang.String virtualHost,
                                  java.lang.String contextPathSpec)

  Create and add a new context. Note that multiple contexts can be created for the same virtualHost and contextPath. Requests are offered to multiple contexts in the order they where added to the HttpServer.

  Parameters:
    `virtualHost` - Virtual hostname or null for all hosts.
    `contextPathSpec` - Path specification relative to the context path.
  Returns:
    A HttpContext instance created by a call to newHttpContext.

### getContext

    public HttpContext getContext(java.lang.String virtualHost,
                                  java.lang.String contextPathSpec,
                                  int i)

  Get specific context.

  Parameters:
    `virtualHost` - The virtual host or null for all hosts.
    `contextPathSpec` - Path specification relative to the context path.
    `i` - Index among contexts of same virtualHost and pathSpec.
  Returns:
    The HttpContext or null.

### getContext

    public HttpContext getContext(java.lang.String virtualHost,
                                  java.lang.String contextPathSpec)

  Get or create context.

  Parameters:
    `virtualHost` - The virtual host or null for all hosts.
    `contextPathSpec` -
  Returns:
    HttpContext. If multiple contexts exist for the same virtualHost and pathSpec, the most recently added context is returned. If no context exists, a new context is created by a call to newHttpContext.

### getContext

    public HttpContext getContext(java.lang.String contextPathSpec)

  Get or create context.

  Parameters:
    `contextPathSpec` - Path specification relative to the context path.
  Returns:
    The HttpContext If multiple contexts exist for the same pathSpec, the most recently added context is returned. If no context exists, a new context is created by a call to newHttpContext.

### getTrace

    public boolean getTrace()

  Returns:
    True if the TRACE method is fully implemented.

### setTrace

    public void setTrace(boolean trace)

  Parameters:
    `trace` - True if the TRACE method is fully implemented.

### getRequestsPerGC

    public int getRequestsPerGC()

  Get the requests per GC. If this is set greater than zero, then the System garbage collector will be invoked after approximately this number of requests. For predictable response, it is often best to have frequent small runs of the GC rather than infrequent large runs. The request count is only approximate as it is not synchronized and multi CPU machines may miss counting some requests.

  Returns:
    Approx requests per garbage collection.

### setRequestsPerGC

    public void setRequestsPerGC(int requestsPerGC)

  Set the requests per GC. If this is set greater than zero, then the System garbage collector will be invoked after approximately this number of requests. For predictable response, it is often best to have frequent small runs of the GC rather than infrequent large runs. The request count is only approximate as it is not synchronized and multi CPU machines may miss counting some requests.

  Parameters:
    `requestsPerGC` - Approx requests per garbage collection.

### start

    public void start()
               throws MultiException

  Start all handlers then listeners. If a subcomponent fails to start, it's exception is added to a org.mortbay.util.MultiException and the start method continues.

  Specified by:
    `start` in interface `LifeCycle`
  Throws:
    `MultiException` - A collection of exceptions thrown by start() method of subcomponents of the HttpServer.

### isStarted

    public boolean isStarted()

  Specified by:
    `isStarted` in interface `LifeCycle`
  Returns:
    True if the LifeCycle has been started.

### stop

    public void stop()
              throws java.lang.InterruptedException

  Stop all listeners then all contexts. Equivalent to stop(false);

  Specified by:
    `stop` in interface `LifeCycle`
  Throws:
    `java.lang.InterruptedException` - If interrupted, stop may not have been called on everything.

### stop

    public void stop(boolean graceful)
              throws java.lang.InterruptedException

  Stop all listeners then all contexts.

  Parameters:
    `graceful` - If true and statistics are on for a context, then this method will wait for requestsActive to go to zero before stopping that context.
    `java.lang.InterruptedException`

### join

    public void join()
              throws java.lang.InterruptedException

  Join the listeners. Join all listeners that are instances of ThreadPool.

  Throws:
    `java.lang.InterruptedException`

### addHostAlias

    public void addHostAlias(java.lang.String virtualHost,
                             java.lang.String alias)

  Deprecated. Use HttpContext.addVirtualHost

  Define a virtual host alias. All requests to the alias are handled the same as request for the virtualHost.

  Parameters:
    `virtualHost` - Host name or IP
    `alias` - Alias hostname or IP

### setRequestLog

    public void setRequestLog(RequestLog log)

  Set the request log.

  Parameters:
    `log` - RequestLog to use.

### getRequestLog

    public RequestLog getRequestLog()

### service

    public HttpContext service(HttpRequest request,
                               HttpResponse response)
                        throws java.io.IOException,
                               HttpException

  Service a request. Handle the request by passing it to the HttpHandler contained in the mapped HttpContexts. The requests host and path are used to select a list of HttpContexts. Each HttpHandler in these context is offered the request in turn, until the request is handled. If no handler handles the request, 404 Not Found is returned.

  Parameters:
    `request` -
    `response` -
  Returns:
    The HttpContext that completed handling of the request or null.
  Throws:
    `java.io.IOException`
    `HttpException`

### findHandler

    public HttpHandler findHandler(java.lang.Class handlerClass,
                                   java.lang.String uri,
                                   java.lang.String[] vhosts)

  Find handler. Find a handler for a URI. This method is provided for the servlet context getContext method to search for another context by URI. A list of hosts may be passed to qualify the search.

  Parameters:
    `uri` - URI that must be satisfied by the servlet handler
    `vhosts` - null or a list of virtual hosts names to search
  Returns:
    HttpHandler

### addRealm

    public UserRealm addRealm(UserRealm realm)

### getRealm

    public UserRealm getRealm(java.lang.String realmName)

  Get a named UserRealm.

  Parameters:
    `realmName` - The name of the realm or null.
  Returns:
    The named realm. If the name is null and only a single realm is known, that is returned.

### removeRealm

    public UserRealm removeRealm(java.lang.String realmName)

### setChunkingForced

    public void setChunkingForced(boolean forced)

  Deprecated.

  Set Chunking Forced.

### getHostMap

    public java.util.Map getHostMap()

### getResolveRemoteHost

    public boolean getResolveRemoteHost()

  Returns:
    True if the remote host name of connections is resolved.

### setResolveRemoteHost

    public void setResolveRemoteHost(boolean resolveRemoteHost)

  Parameters:
    `resolveRemoteHost` - True if the remote host name of connections is resolved.

### statsReset

    public void statsReset()

  Reset statistics.

### setStatsOn

    public void setStatsOn(boolean on)

### getStatsOn

    public boolean getStatsOn()

  Returns:
    True if statistics collection is turned on.

### getStatsOnMs

    public long getStatsOnMs()

  Returns:
    Timestamp stats were started at.

### getConnections

    public int getConnections()

  Returns:
    Number of connections accepted by the server since statsReset() called. Undefined if setStatsOn(false).

### getConnectionsOpen

    public int getConnectionsOpen()

  Returns:
    Number of connections currently open that were opened since statsReset() called. Undefined if setStatsOn(false).

### getConnectionsOpenMax

    public int getConnectionsOpenMax()

  Returns:
    Maximum number of connections opened simultaneously since statsReset() called. Undefined if setStatsOn(false).

### getConnectionsDurationAve

    public long getConnectionsDurationAve()

  Returns:
    Sliding average duration in milliseconds of open connections since statsReset() called. Undefined if setStatsOn(false).

### getConnectionsDurationMax

    public long getConnectionsDurationMax()

  Returns:
    Maximum duration in milliseconds of an open connection since statsReset() called. Undefined if setStatsOn(false).

### getConnectionsRequestsAve

    public int getConnectionsRequestsAve()

  Returns:
    Sliding average number of requests per connection since statsReset() called. Undefined if setStatsOn(false).

### getConnectionsRequestsMax

    public int getConnectionsRequestsMax()

  Returns:
    Maximum number of requests per connection since statsReset() called. Undefined if setStatsOn(false).

### getErrors

    public int getErrors()

  Returns:
    Number of errors generated while handling requests. since statsReset() called. Undefined if setStatsOn(false).

### getRequests

    public int getRequests()

  Returns:
    Number of requests since statsReset() called. Undefined if setStatsOn(false).

### getRequestsActive

    public int getRequestsActive()

  Returns:
    Number of requests currently active. Undefined if setStatsOn(false).

### getRequestsActiveMax

    public int getRequestsActiveMax()

  Returns:
    Maximum number of active requests since statsReset() called. Undefined if setStatsOn(false).

### getRequestsDurationAve

    public long getRequestsDurationAve()

  Returns:
    Average duration of request handling in milliseconds since statsReset() called. Undefined if setStatsOn(false).

### getRequestsDurationMax

    public long getRequestsDurationMax()

  Returns:
    Get maximum duration in milliseconds of request handling since statsReset() called. Undefined if setStatsOn(false).

### addEventListener

    public void addEventListener(java.util.EventListener listener)

  Add a server event listener. Listeners are sent HttpServer.ComponentEvent instances when components such as listeners and contexts are added to the HttpServer.

  Parameters:
    `listener` - HttpServer.ComponentEventListener

### removeEventListener

    public void removeEventListener(java.util.EventListener listener)

### save

    public void save(java.lang.String saveat)
              throws java.net.MalformedURLException,
                     java.io.IOException

  Save the HttpServer The server is saved by serialization to the given filename or URL.

  Parameters:
    `saveat` - A file or URL to save the configuration at.
  Throws:
    `java.net.MalformedURLException`
    `java.io.IOException`

### destroy

    public void destroy()

  Destroy a stopped server. Remove all components and send notifications to all event listeners. The HttpServer must be stopped before it can be destroyed.

### main

    public static void main(java.lang.String[] args)

  Construct server from command line arguments.

  Parameters:
    `args` -

Copyright © 2000 Mortbay Consulting Pty. Ltd. All Rights Reserved.