Wombat - a Perl servlet container

- NAME
- SYNOPSIS
- DESCRIPTION
- CONTAINER CONFIGURATION

- CONTAINER DIRECTORIES
- CONTAINER DEPLOYMENT DESCRIPTOR

- WEB APPLICATION CONFIGURATION

- WEB APPLICATION DIRECTORIES
- WEB APPLICATION DEPLOYMENT DESCRIPTOR

- SERVLET API SUPPORT
- OTHER NOTES
- SEE ALSO
- AUTHORS

# NAME

Wombat - a Perl servlet container

# SYNOPSIS

# DESCRIPTION

Wombat is a servlet container for Perl. It is not an executable program itself; rather, it is a library that can be used by programs to embed a servlet container. Embedding programs must provide implementations of Connector API classes that adapt Wombat to the surrounding environment. One such connector is Apache::Wombat which embeds a Wombat servlet container within an Apache httpd built with mod_perl.

Currently no developer documentation for Wombat itself is provided beyond the contents of this document and the POD for each Wombat class.

# CONTAINER CONFIGURATION

## CONTAINER DIRECTORIES

Web application directories are generally located beneath a single application base directory which in turn is usually located beneath the container's home directory. Each Host configured in the container can use the same application base directory (called `webapps` by default) or provide its own, possibly located outside the container's home directory. As well, each Application configured in the container has the option of locating its webapp directory outside its Host's application base directory.

A typical directory structure for Wombat embedded within Apache/mod_perl might be:

      # container's home dir
      /usr/local/apache
      # default hosts's appbase dir
      /usr/local/apache/webapps
      # examples app's webapp dir
      /usr/local/apache/webapps/examples
      # another host's appbase dir
      /home/bcm/maz.org/webapps
      # another app's webapp dir
      /home/bcm/maz.org/webapps/comics

## CONTAINER DEPLOYMENT DESCRIPTOR

The behavior and attributes of the Wombat servlet container are controlled by a container deployment descriptor (usually named `server.xml`). This file is modeled after the Tomcat 4 equivalent, but it does have slight differences. A full Configuration Guide will be published; until then, the definitions included below are the only documentation:

Elements supported in `server.xml` (named with XPath paths, example attribute settings included inline):

Server
  Represents the entire perl interpreter, into which one or more Services are deployed. Only one Server may be specified.

Server/Service
  Represents a collection of one or more Connectors that share a single Engine (and therefore the web applications visible within that Engine). A display name for the Service (`name="HTTP Service"`) may be specified. Many Services may be specified for the single Server.

Server/Service/Connector
  Represents an endpoint by which requests are received and responses are returned. Each Connector passes requests on to its associated Container for processing. The name of a class that implements the Wombat::Connector interface MUST be specified (`className="Apache::Wombat::Connector"`), as well as a scheme (`scheme="http"` attribute) and any attributes needed by the implementation. A secure flag (`secure="1"`) may also be set to indicated that the request was transported using SSL. Many Connectors may theoretically be specified for a particular Service, but at this time, the Wombat internals need some refactoring before they can support Connectors for protocols other than HTTP.

Server/Service/Engine
  Represents the highest level Container associated with a set of Connectors. The Engine discriminates between virtual hosts as necessary and passes the request along to the appropriate Host. A display name for the Engine (`name="Apache-Wombat"`) may be specified, as well as the name of a default host (`defaultHost="localhost"` attribute) to receive requests that are not mapped to other specifically configured Hosts. Only one Engine may be specified for a particular Service.

Server/Service/Engine/Logger
  Unless overridden in a lower level Container, all log messages will be handled by this Logger. The name of a class that implements the Wombat::Logger interface MUST be specified (`className="Apache::Wombat::Logger"`), as well as any attributes needed by the implementation. A minimum log level (`level="DEBUG"`) may also be specified. If no Logger is specified, logging will be disabled for the Container. Only one Logger may be specified for a particular Container.

Server/Service/Engine/Realm
  Unless overridden in a lower level Container, all web applications will be subject to this security Realm. The name of a class that implements the Wombat::Realm interface MUST be specified (`className="Wombat::Realm::DBIRealm"`), as well as any attributes needed by the implementation. If no Realm is specified, security will be disabled for the Container. Only one Realm may be specified for a particular Container.

  Note that security MUST be also enabled in a particular web application's deployment descriptor in order for the Realm to be relevant to that web application. Therefore a Realm may be configured for an entire Container but only in use for a single Application.

Server/Service/Engine/SessionManager
  Unless overridden in a lower level Container, all sessions will be managed by this SessionManager. The name of a class that implements the Wombat::SessionManager interface MUST be specified (`className="Wombat::SessionManager::StandardSessionManager"`), as well as any attributes needed by the implementation. A maximum inactivity interval/idle out time may also be specified (`maxInactiveInterval="300"`). If no SessionManager element is specified, sessions will be disabled for the Container. Only one SessionManager may be specified for a particular Container.

  The type of SessionManager used will depend heavily on the environment provided by the embedding program. For instance, a multiprocess Apache/mod_perl server embedding Wombat will require a SessionManager that caches sessions in shared memory, on disk or in some other location that all processes can access, whereas a multithreaded daemon embedding Wombat might use a simple memory-based SessionManager.

Server/Service/Engine/Valve
  Represents a request-processing component that ``wraps'' around the Servlet that is ultimately responsible for processing the request. The name of a class that implements the Wombat::Valve interface MUST be specified (`className="Wombat::Valve::RequestDumperValve"`), as well as any attributes needed by the implementation. Many Valves may be specified for a single Container.

  Valves are used to add container functionality for specific Containers, much like Filters are used to add application functionality for specific Servlets. An example of a commonly-used Valve might be a one that logs information about each request (an AccessLogValve perhaps).

Server/Service/Engine/Host
  Represents a Container associated with a particular virtual host. A Host maps the request URI to a particular web application and passes the request along to the appropriate Application. The name of the host MUST be specified (`name="localhost"`), as well as the application base directory (`appBase="webapps"`) which can be specified absolutely or relative to the container's home directory. Many Hosts (at least one, corresponding to the Engine's default host attribute) may be specified for a single Engine.

Server/Service/Engine/Host/Alias
  Represents an alternate name or names for the virtual host. For a Host named 'maz.org', the Alias '*.maz.org' might be configured to catch requests for specific hosts and subdomains in the domain. The name of the alias MUST be specified (`name="*.maz.org"`). Many Aliases may be specified for a particular Host.

Server/Service/Engine/Host/Logger
  A Logger configured for a Host overrides any Logger configured at the Engine level.

Server/Service/Engine/Host/Realm
  A Realm configured for a Host overrides any Realm configured at the Engine level.

Server/Service/Engine/Host/SessionManager
  A SessionManager configured for a Host overrides any SessionManager configured at the Engine level.

Server/Service/Engine/Host/Valve
  Any Valves configured for a Host add to (and execute after) any Valves configured at the Engine level.

Server/Service/Engine/Host/Application
  Represents a Container associated with a particular web application. An Application inspects the request URI and passes the request along to the appropriate Servlet (as configured in the web application's deployment descriptor). The display name of the application (`displayName="Examples Application"`) and the URI path base for the application (`path="/wombat-examples"`) MUST be specified, as well as the webapp directory (`docBase="examples"`) which can be specified absolutely or relative to the parent Host's application base directory. Many Applications (at least one, corresponding to the URI path '/') may be specified for a single Host.

Server/Service/Engine/Host/Application/Logger
  A Logger configured for an Application overrides any Logger configured at a higher level.

Server/Service/Engine/Host/Application/Realm
  A Realm configured for an Application overrides any Realm configured at a higher level.

Server/Service/Engine/Host/Application/SessionManager
  A SessionManager configured for an Application overrides any SessionManager configured at a higher level.

Server/Service/Engine/Host/Application/Valve
  Any Valves configured for an Application add to (and execute after) any Valves configured at a higher level.

# WEB APPLICATION CONFIGURATION

## WEB APPLICATION DIRECTORIES

Each web application's resources (images, static HTML files, templates and classes) are located in a single webapp directory. This makes it trivially easy to organize and deploy individual web applications.

Each webapp directory MUST contain a directory named `WEB-INF`. This directory MUST contain the web application deployment descriptor, `web.xml` (see WEB APPLICATION CONFIGURATION). Additionally it MAY contain a `lib` directory in which application-specific modules are located. If the `lib` directory exists, it will be added to `@INC` when the application is loaded so that application classes are visible.

All contents of the webapp directory EXCEPT the `WEB-INF` directory and everything beneath it will be visible at the path specified for the Application in the container's deployment descriptor (see CONTAINER CONFIGURATION). For example, if an application's path is configured as ``/wombat-examples'', then the file named `index.html` located inside the webapp directory would be visible at the URI ``/wombat-examples/index.html''. The context-relative path of the file would be ``/index.html''.

## WEB APPLICATION DEPLOYMENT DESCRIPTOR

The behavior and attributes of a particular web application are controlled by a web application deployment descriptor (`web.xml`) as specified in the Java (TM) servlet specification. The elements that may be included in `web.xml` are defined in the servlet specification and in the DTD included in the libservlet distribution.

Web application deployment descriptor elements recognized by Wombat:

web-app
web-app/context-param
web-app/context-param/param-name
web-app/context-param/param-value
web-app/display-name
web-app/login-config
web-app/login-config/auth-method
web-app/login-config/realm-name
web-app/security-constraint
web-app/security-constraint/auth-constraint
web-app/security-constraint/auth-constraint/role-name
web-app/security-constraint/display-name
web-app/security-constraint/user-data-constraint
web-app/security-constraint/user-data-constraint/transport-guarantee
web-app/security-constraint/web-resource-collection
web-app/security-constraint/web-resource-collection/http-method
web-app/security-constraint/web-resource-collection/url-pattern
web-app/security-constraint/web-resource-collection/web-resource-name
web-app/servlet
web-app/servlet/init-param
web-app/servlet/init-param/param-name
web-app/servlet/init-param/param-value
web-app/servlet/security-role-ref
web-app/servlet/security-role-ref/role-name
web-app/servlet/security-role-ref/role-link
web-app/servlet/servlet-class
web-app/servlet/servlet-name
web-app/servlet-mapping
web-app/servlet-mapping/url-pattern
web-app/servlet-mapping/servlet-name
web-app/session-config
web-app/session-timeout

Elements currently not recognized by Wombat, or for which Wombat does not currently provide feature support:

web-app/context-param/description
web-app/description
web-app/distributable
web-app/ejb-local-ref/description
web-app/ejb-local-ref/ejb-ref-name
web-app/ejb-local-ref/ejb-ref-type
web-app/ejb-local-ref/local-home
web-app/ejb-local-ref/local
web-app/ejb-local-ref/ejb-link
web-app/ejb-ref/description
web-app/ejb-ref/ejb-ref-name
web-app/ejb-ref/ejb-ref-type
web-app/ejb-ref/home
web-app/ejb-ref/remote
web-app/ejb-ref/ejb-link
web-app/env-entry
web-app/env-entry/description
web-app/env-entry/env-entry-name
web-app/env-entry/env-entry-value
web-app/env-entry/env-entry-type
web-app/error-page
web-app/error-page/error-code
web-app/error-page/exception-type
web-app/error-page/location
web-app/filter
web-app/filter/icon
web-app/filter/icon/small-icon
web-app/filter/icon/large-icon
web-app/filter/init-param
web-app/filter/init-param/param-name
web-app/filter/init-param/param-value
web-app/filter/filter-name
web-app/filter/display-name
web-app/filter/description
web-app/filter/filter-class
web-app/filter/init-param
web-app/filter-mapping
web-app/filter-mapping/filter-name
web-app/filter-mapping/url-pattern
web-app/filter-mapping/servlet-name
web-app/icon
web-app/icon/small-icon
web-app/icon/large-icon
web-app/listener
web-app/listener-class
web-app/login-config/form-login-config
web-app/login-config/form-login-config/form-login-page
web-app/login-config/form-login-config/form-error-page
web-app/mime-mapping
web-app/mime-mapping/extension
web-app/mime-mapping/mime-type
web-app/resource-env-ref
web-app/resource-env-ref/description
web-app/resource-env-ref/resource-env-ref-name
web-app/resource-env-ref/resource-env-ref-type
web-app/resource-ref
web-app/resource-ref/description
web-app/resource-ref/res-auth
web-app/resource-ref/res-ref-name
web-app/resource-ref/res-sharing-scope
web-app/resource-ref/res-type
web-app/security-constraint/auth-constraint/description
web-app/security-constraint/user-data-constraint/description
web-app/security-constraint/web-resource-collection/description
web-app/security-role
web-app/security-role/description
web-app/security-role/role-name
web-app/servlet/description
web-app/servlet/display-name
web-app/servlet/icon
web-app/servlet/icon/small-icon
web-app/servlet/icon/large-icon
web-app/servlet/jsp-file
web-app/servlet/load-on-startup
web-app/servlet/run-as/description
web-app/servlet/run-as/role-name
web-app/servlet/security-role-ref/description
web-app/taglib
web-app/taglib/taglib-uri
web-app/taglib/taglib-location
web-app/welcome-file-list
web-app/welcome-file-list/welcome-file

# SERVLET API SUPPORT

Wombat will eventually implement the entire Java (TM) servlet specification as adapted to Perl by libservlet. Currently it supports just enough to be classified as a 'proof of concept' servlet container.

Features currently not supported by Wombat but likely to be supported in the near future include:

Application class reloading (SRV.3.7)
Application replacing (SRV.9.8)
Application events (SRV.10)
Auth methods: client cert, digest, form (SRV.12.5)
Compartmentalized class loading (SRV.9.7.2)
Secure connector redirection
Clustering/session distribution (SRV.2.2, SRV.3.4.1, SRV.7.7.2, SRV.10.6)
Environment entries (SRV.9.11)
Environment/external resources (SRV.9.11)
Error handling request attributes and pages (SRV.9.9)
Filtering (SRV.6)
Internationalization (SRV.4.8, SRV.4.9, SRV.5.4)
MIME mappings
Multiple protocol support
Named request dispatchers (SRV.8.2)
Request dispatcher attributes (SRV.8.3, SRV.8.4)
Request path translation (SRV.4.5)
Security roles (SRV.12.3)
Servlet context resources (SRV.3.5)
Servlet context working directories (SRV.3.7.1)
Servlet load-on-startup (SRV.2.3.1)
Session tracking via SSL or URL rewriting (SRV.7.1)
Session events (SRV.7.4, SRV.7.5, SRV.10.7)
SSL attributes (SRV.4.7)
Welcome files (SRV.9.10)

Features not likely to ever be supported include:

EJB
Icons
JSP files
Taglibs

# OTHER NOTES

No consideration has been given to threading. When the threading environment in perl has settled down, this may change.

# SEE ALSO

Apache::Wombat, mod_perl, Servlet

Java (TM) Servlet 2.3 Specification: http://www.jcp.org/aboutJava/communityprocess/final/jsr053/

# AUTHORS

Brian Moseley, bcm@maz.org

Largely inspired by Tomcat, the Apache Java (TM) servlet container at http://jakarta.apache.org/tomcat/. Many thanks!