The GlassFish WebContainer is based on the Tomcat Servlet implementation called Catalina. The Catalina architecture, introduced in Tomcat 4.x, was designed to easily allow developer to extends it. There is several interception point in Catalina that can be extended:

• Valve: A Valve is a request processing component associated with a particular virtual-server(host) or web-module (servlet). A series of Valves are generally associated with each other into a Pipeline. Developer will usually inject their valves in order to have access to the Catalina internal objects, and manipulate the request/response object before filters or servlets are invoked. As an example, the access logging mechanism in GlassFish is implemented as a Valve.
• ContainerListener: A listener for significant Container generated events. As an example, every time a WAR is deployed, a ContainerListener implementation will be notified for every new created Servlet, TagLib or Filter.
• InstanceListener: A listener for significant events related to a specific servlet instance. An implementation of this interface will get notified everytime a Servlet is about to be invoked or when some operations are made on the Servlet (like when calling its ServletContextListeners).
• LifecycleListener: A listener for significant events (including "virtual server start" and "web module stop") generated by a component that implements the Lifecycle interface. An implementation of this interface will get notified by mostly all internal objects when an it is started|stopped (like when a new virtual-server is created). As an example, we are using this interface internally to notify the other GlassFish's containers.

Virtual server supports the injection of Valve, ContainerListener and LifecycleListener. Web module supports the same as the virtual server with the addition of the InstanceListener.

Once you have your extension implemented, you need to install it in GlassFish. To install an extension:

For virtual-server

• Add your classes into a jar file (ex: glassfish-ext.jar)
• Place your jar under ${glassfish.home}/lib
• Edit ${glassfish.home}/domains/domain1/config/domain.xml, locate the virtual-server element, and add <property name="type" value="fully qualified class name"> where type can be valve_ or listener_, with a unique number allowing you to define more than one type.

  Ex: <property name="valve_1" value="org.apache.catalina.valves.RequestDumperValve"/>

For web-module

• Same as for virtual-server, but under the web-module element of domain.xml. Except you can bundle your implementation under WEB-INF/lib or WEB-INF/classes (easier to deploy to several GlassFish installations)

  Ex: <property name="listener_1" value="org.glassfish.MyServletListener"/>

Very easy, is it :-). This is supported starting in GlassFish v2 build 17.

technorati: web container glassfish