gumdrop

gumdrop is a multipurpose Java server using asynchronous I/O. It provides a servlet container implementing the servlet 2.4 specification. Because the number of threads in the gumdrop servlet container is independent of the number of concurrent connections, it can scale much better than traditional Java web servers like Tomcat. It also avoids dependency on large, slow libraries and is therefore quite fast ☺. It is, however, 100% Java code. Projects are under way to provide HTTPS and JSP support for gumdrop. Future directions also include FTP and WebDAV connectors.

You can get a copy of gumdrop by following these instructions. gumdrop is distributed under the GPL.

If you have any questions, please direct them to Chris Burdess.

Architecture

The server is configured with a number of connectors, which are bound to ports. It then sits in a select loop waiting for socket data. When an accept request is received, it uses the corresponding connector as a factory to create a new connection object to handle that IP connection. Subsequent read requests are demultiplexed to the corresponding connection handlers. Servers based on an asynchronous, or reactor, model can thus be developed quite quickly in response to incoming data.

The servlet container is a rather special case. The servlet connector spawns one or more request handler threads, which wait on a queue of request/response pairs. As data arrives sufficient to construct a request, a request/response pair is initialised (from a pool) and placed in the queue. The request body arrives asynchronously via a pipe. The request handler thread can therefore block waiting for request data while the server supplies it.

Because the number of request-processing threads is completely independent of the number of client TCP connections to the server, gumdrop scales very gracefully in comparison to traditional web servers.

Servlet contexts marked as distributable cause gumdrop to start another thread, used for cluster synchronisation. The mechanism used is a simple UDP broadcast of the changed session data.

Unless otherwise configured, containers also use a separate thread to detect changes in the web application configuration, such as recompilation of Java classes and changes to the deployment descriptor. Such changes cause the context to be reloaded. This process is referred to as hot deploy.

Configuration

The configuration of gumdrop is primarily contained in the gumdroprc file. The remainder of the configuration is supplied by standard Java system properties, e.g. the logging subsystem which uses the java.util.logging package.

Format of the gumdroprc file

The gumdroprc file is an XML file, although it is not intended to be validated, as it may contain attribute names that are specific to properties of the resources to be configured, and which can therefore not be known in advance. However, here is the general format of the file:

• The server element is the root element. This represents the gnu.gumdrop.Server object. It may contain container or connector elements.
• A container element represents a gnu.gumdrop.servlet.Container. It logically groups a set of related resources, contexts, and connectors. The configurable attributes are:
  • hot-deploy - if false, hot deployment of contexts will be disabled
  • cluster-port - the UDP port on which to synchronise a cluster of gumdrop containers containing distributable contexts. Defaults to 8080.
  • cluster-group-address - the IP address to specify as the group address for multiplexed UDP datagrams when synchronising distributable contexts. Defaults to 224.0.80.80.
  It may contain realm, resource, context, and connector elements.
• A connector element represents a gnu.gumdrop.Connector object. This is a service that listens on a particular server port and manages connections made to that port. Its attributes include:
  • class - the subclass of gnu.gumdrop.Connector used to realise the connector.
  • port - the port to which the connector should listen on.
  • addresses - a space-separated list of IP addresses to which the connector should bind. If absent, all known local IP addresses will be bound to.
  The servlet connector (gnu.gumdrop.servlet.ServletConnector) provides the following additional attributes:
  • initial-thread-count - the number of request-handling threads to spawn initially.
  • access-log - the path to the log file for logging accesses (in W3C httpd format), if any.
• A context element represents a web application context, realised by the gnu.gumdrop.servlet.Context class. It has 2 attributes:
  • path - the context path for the context (see the servlet specification for further details)
  • root - the web application root. This may be a directory or the path to a WAR file. Note that gumdrop does not unpack WAR files: if you want to deploy into the filesystem, specify a directory instead.
  This element may contain resource, parameter, and realm elements.
• A parameter element defines an initialisation parameter for a context, the values of which will be accessible via the getInitParameter method. The following attributes are required:
  • name - the parameter name.
  • value - the parameter value, always interpreted as a string.
• resource elements are used to specify objects of almost unlimited type, which can be bound into the JNDI namespace accessible to web applications within a given context or container. There are 2 required attributes:
  • name - the JNDI name (relative to java:comp/env/) to which the resource will be bound.
  • type - the class name of the object to instantiate.
  • value - if specified, the default value of the resource, for value types. The object class must specify a String constructor for initialisation.
  Any other attributes on a resource element are taken to be bean property names, and the associated method will be invoked with the given attribute value (converted to a primitive type if necessary). There are also two special types that can be specified: javax.sql.DataSource and javax.mail.Session. The Session type instantiates a mail Session object. The DataSource type provides access to a pool of connections to a JDBC data source. It must specify the following attributes (all other attributes, e.g. user, password are interpreted as properties for obtaining the connection):
  • driver - the class name of the JDBC driver.
  • url - the JDBC URL to connect to.
• The realm is used to specify a security domain. It has the following attributes:
  • name - the realm name, typically used in challenges.
  • type - the subclass of gnu.gumdrop.Realm used to realise the realm.
  A simple static realm implementation is provided by the gnu.gumdrop.BasicRealm class. This reads its configuration from an XML file specified in the href attribute. A sample basic realm file is provided. More complex, dynamic realm implementations, drawing user and group information from e.g. databases, can use other attributes, which will be invoked as bean properties on the realm instance during configuration.

Where to go from here

Hopefully you will try out some of your own web applications within gumdrop. If the speed, simplicity, and ease of configuration appeals to you, please consider getting involved and developing a new feature. If it doesn't work the way you wanted it to, please let us know!

There are a number of new features planned for gumdrop. We are working on TLS support, which will provide HTTPS capabilities for the servlet container. JSP support is not actively planned, but if you want to work on that, so much the better. In the longer term, the plan is to add a number of asynchronous servers (e.g. FTP, WebDAV) and also to develop intelligent algorithms for spawning and reaping request-processing threads based on demand. If you have an idea, we'd love to hear that too.

gumdrop