Deployment of applications

Deployment is an important step in the lifecycle of a Java EE application. So much so that most organizations have a deployer role dedicated to this step. The deployer will configure the application for the environment in which it is being deployed and will identify the resources that the application needs and map them to the correct references in the application. The process of mapping the actual resources to the references in the application is done by means of the Java EE deployment descriptors and server-specific deployment plans. We will now go into the details of these files.

Deployment descriptors

A deployment descriptor is an XML file that describes the Java EE module. It lists the Java EE components that make up the module, and defines the environment for these components. Java EE components have access to a naming service called JNDI, which is used to decouple the component from the resources and other components that it uses. The component will access these resources and other components by looking them up in the JNDI naming context. The names that can be used to access these components and resources in the JNDI context for that component or module are specified in the deployment descriptor. This allows the deployer to map components to different physical resources and components by simply modifying the mapping of the names in the deployment descriptor to server-specific resources. The deployment descriptors are also used to modify the security aspects of the components, as well as to map the components to logical names.

The different types of deployment descriptors, as specified in the Java EE specifications, are as follows:

The component or module-specific JNDI naming context is actually immutable, that is, once it has been created during deployment it cannot be changed. This is mandated by the Java EE 5 specification.

Deployment plans

When we use the term deployment plans, we are referring to the server-specific XML files that help with the deployment. These files can be created by tooling, or by hand. The tooling that is present in Apache Geronimo for creating this is the Geronimo Eclipse Plugin (GEP) and the Plan Creator portlet in the Administration Console. There are the Geronimo-specific deployment plan counterparts for each of the Java EE 5 deployment descriptors. They are described below:

The deployment plans map the resource references in the Java EE deployment descriptors to resources configured in the Application Server. The mapping of resources can therefore be changed by simply changing the server-specific deployment plan to point to another resource. All instances of the resource-ref, resource-env-ref, and message-destination-ref in the Java EE deployment descriptors have corresponding entries in the Geronimo-specific deployment plans, which point to actual server resources. We can see this by means of the following snippets from the descriptors for both web.xml and geronimo-web.xml, as shown below:

<!-- Resource defined in web.xml -->
<resource-ref>
<res-ref-name>jdbc/snoop</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<!-- Resource mapped in Geronimo-web.xml -->
<naming:resource-ref>
<naming:ref-name>jdbc/snoop</naming:ref-name>
<naming:resource-link>DerbyTestPool</naming:resource-link>
</naming:resource-ref>

The server-specific deployment plans can also be specified at deployment time, as an extra attribute to the deployment tooling. In this case, you need not package it with the archive. If you have a deployment plan that is packaged both with the archive and with an external plan that you specify during deployment, then the external plan takes precedence over the packaged one.

The deploy tool

The deploy tool is a standalone tool that can be used for deploying applications and resource adapters onto remote as well as local server instances. The tool can be invoked by using the deploy command. The syntax of the deploy command can be obtained through the options help and help all. Try running deploy help all from the command prompt after changing to the <GERONIMO_HOME>/bin directory to get descriptions on all the options that are possible with the deploy command. The output for this command is shown in the following screenshot:

Running the deploy help all command provides a detailed explanation on the commands that the deploy tool supports. We will also give a few examples of common deploy tool usage below:

• Local deployment

• Remote deployment

• Installing a library

• Installing a plugin

• Offline deployment

• Redeploy

Deployment from the Administration Console

Deployment can also be done by using the Deploy New portlet in the Administration Console. See Chapter 10, Administration, for more details on using this portlet.

Deployment through GShell

GShell is a command-line shell that can be used for administering Apache Geronimo instances. GShell provides commands for deployment related operations. See Chapter 10, Administration, for more details of GShell.

Web modules

Web applications are the most common type of Java EE applications. They are the simplest to develop and understand, and their deployment descriptors are not too verbose. In this section, we will be looking at the deployment descriptors and server-specific deployment plans that are required to deploy a web application on Apache Geronimo. The focus here will be on the deployment plan and the various elements in the plan. We will now see the deployment configuration needed for various web artifacts such as servlets, filters, and listeners.

Servlet

Servlets extend the capabilities of a server application that uses a request-response model. Servlets are commonly used with the HTTP protocol. Typically, servlets are used to process data submitted by an HTML form, generating dynamic content and managing state over the stateless HTTP protocol. An xml-fragment in the deployment descriptor used to define a servlet and map the servlet to a URL pattern is given below.

<servlet>
<servlet-name>HelloworldServlet</servlet-name>
<servlet-class>sample.HelloworldServlet</servlet-class>
<init-param>
<param-name>greeting</param-name>
<param-value>Namaskar</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>HelloworldServlet</servlet-name>
<url-pattern>/HelloworldServlet</url-pattern>
</servlet-mapping>

The name of the servlet is specified by using the servlet-name element under the servlet tag. The servlet-class element is used to specify the fully-qualified name of the java class for this servlet. This class should implement the javax.servlet.Servlet interface. A servlet may have zero or more initialization parameters defined using the init-param tag. The name of the parameter is specified by using the param-name element and the value is specified using param-value element. These parameters can be retrieved from the ServletConfig file in the init() lifecycle method, as shown in the following snippet:

private String greeting;
public void init(ServletConfig config) {
greeting = config.getInitParameter("greeting");
}

The URLs that the servlet will be serving are specified by using the servlet-mapping element. The servlet-name element under servlet-mapping specifies the name of the servlet, and the url-pattern element specifies the pattern of URLs that will be served by this servlet. Note that more than one servlet-mapping can be present for a servlet.

Filter

Filters are used to intercept the web requests before the requests are passed on to the web resources for a service. Filters do not create requests or responses. A filter that has no dependency on a specific web resource can be associated with more than one web resource. Filters are typically used to examine the incoming request and take the appropriate action, modify the requests and responses (headers, data, attributes, and so on), and block requests and responses. An XML fragment in the deployment descriptor used to define a filter and map the filter to a URL pattern is given below:

<filter>
<filter-name>HelloworldFilter</filter-name>
<filter-class>sample.HelloworldFilter</filter-class>
<init-param>
<param-name>param1</param-name>
<param-value>Aloha</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>HelloworldFilter</filter-name>
<url-pattern>/HelloworldServlet</url-pattern>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>

The name of the filter is specified by using the filter-name element under the filter tag. The filter-class element is used to specify the fully-qualified name of the java class for this filter. This class should implement the javax.servlet.Filter interface. A filter may have zero or more initialization parameters, defined by using the init-param tag. The name of the parameter is specified by using the param-name element and the value is specified by using the param-value element. These parameters can be retrieved from the FilterConfig in the init() lifecycle method. The URLs that the filter will be filtering is specified by using the filter-mapping element. The filter-name element under filter-mapping specifies the name of the filter and the url-pattern element specifies the pattern of URLs that will be filtered by this filter. Note that more than one filter can filter the requests, and in this case, these filters will form a filter chain through which the requests pass. If a filter is to be applied to a particular servlet, then use servlet-name, instead of url-pattern, under filter-mapping. The servlet-name element can use wildcard characters so that the filter is applied to more than one servlet. The dispatcher element specifies the type of requests to which the filter applies. Allowed values for the dispatcher are REQUEST, FORWARD, INCLUDE, and ERROR. Multiple dispatcher elements can be used to specify a combination of these values. The explanation of these values is as follows:

• REQUEST: Filter applies to requests coming from clients

• FORWARD: Filter applies to requests forwarded to a component

• INCLUDE: Filter applies when the request is processed by an included component

• ERROR: Filter applies when the request is processed by an error page mechanism

The order in which filters are invoked is the order in which filter-mapping declarations, which match a request URI to a servlet, appear in the list of filter-mapping elements.

Listener

Monitoring events in a servlet's lifecycle can be done by defining listener objects that get invoked upon the occurrence of the lifecycle events. The various listeners that are supported are as follows:

• Servlet context listener: A servlet context listener implements the javax.servlet.ServletContextListener interface. The methods from this listener are invoked when a web application's context is initialized or destroyed. A ServletContextEvent containing a ServletContext object is passed as a parameter to the listener method.

• Servlet context attribute listener: A servlet context attribute listener implements the javax.servlet.ServletContextAttributeListener interface. The methods from this listener are invoked when an attribute is added to, removed from, or replaced in the web application's context. A ServletContextAttributeEvent object containing the ServletContext, a name, and the value of the attribute are passed as parameters to the listener method.

• Servlet request listener: A servlet request listener implements the javax.servlet.ServletRequestListener interface. Methods from this listener are invoked when the request comes into or goes out of scope in a web application. A request is defined as coming into scope when it is about to enter the first servlet or filter in the web application, and is defined as going out of scope when it exits the last servlet or the first filter in the chain. A ServletRequestEvent object, containing the ServletContext and the ServletRequest, is passed as a parameter to the listener method.

• Servlet request attribute listener: A servlet request attribute listener implements the javax.servlet.ServletRequestAttributeListener interface. Methods from this listener are invoked when an attribute is added to, removed from, or replaced in a ServletRequest when the request is within the scope of the web application. A ServletRequestAttributeEvent object containing the ServletContext, the ServletRequest, the name, and value of the attribute is passed as a parameter to the listener method.

• HTTP session listener: An HTTP session listener implements the javax.servlet.http.HttpSessionListener interface. The methods from this listener are invoked when an HTTP session is created or destroyed. An HttpSessionEvent object containing the HttpSession is passed as a parameter to the listener method.

• HTTP session attribute listener: An HTTP session attribute listener implements the javax.servlet.http.HttpSessionAttributeListener interface. Methods from this listener are invoked when an attribute is added to, removed from, or replaced in an HTTP session. An HttpSessionBindingEvent object containing the HttpSession, the name, and value of the attribute is passed as a parameter to the method.

• HTTP session binding listener: An object that wants to be notified when it is bound or unbound to an HttpSession as an attribute can implement the javax.servlet.http.HttpSessionBindingListener interface. Methods from this listener are invoked when the object is bound to or unbound from an HTTP session. An HttpSessionBindingEvent object containing the HttpSession, and the name and value of the attribute is passed as a parameter to the method.

• HTTP session activation listener: An object that wants to be notified when the HTTP session to which it is bound to as an attribute is being activated or passivated can implement the javax.servlet.http.HttpSessionActivationListener interface. Methods from this listener are invoked when an HttpSession to which the object is bound to is activated or passivated. An HttpSessionEvent object containing the HttpSession is passed as a parameter to the listener method.

Servlet context listener, servlet context attribute listener, servlet request listener, servlet request attribute listener, HTTP session listener, and HTTP session attribute listener are registered in a web application by using the web application deployment descriptor. A sample XML fragment for registering such listeners is shown below:

<listener>
<listener-class>sample.HelloworldServletContextListener </listener-class>
</listener>
<listener>
<listener-class>sample.HelloworldServletContextAttributeListener </listener-class>
</listener>
<listener>
<listener-class>sample.HelloworldServletRequestListener </listener-class>
</listener>
<listener>
<listener-class>sample.HelloworldServletRequestAttributeListener </listener-class>
</listener>
<listener>
<listener-class>sample.HelloworldHttpSessionListener </listener-class>
</listener>
<listener>
<listener-class>sample.HelloworldHttpSessionAttributeListener </listener-class>
</listener>

The listener-class element specifies the fully qualified name of the Java class of the listener.

HTTP session binding listeners and HTTPS session activation listeners get registered when an object implementing the respective interfaces is bound to an HTTP session as an attribute.

Web deployment descriptor

The following are various elements in a web application deployment descriptor web.xml, the schema of which is given at http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd.

• context-param: The context-param element contains the declaration of a web application's servlet context initialization parameters.

• session-config: The session-config element defines the session parameters for the web application.

• mime-mapping: The mime-mapping element defines a mapping between an extension and a mime type.

• welcome-file-list: The welcome-file-list element contains an ordered list of welcome-file elements. The welcome-file element contains the filename to be used as a default welcome file, such as index.html.

• error-page: The error-page element contains the mapping of an error code or exception type to the path of a resource in the web application. The error-code parameter contains an HTTP error code, ex: 404. The exception-type parameter contains the fully-qualified class name of a Java exception type. The location element contains the location of the resource in the web application, relative to the root of the web application. The value of the location must have a leading '/'.

• jsp-config: The jsp-config element is used to provide global configuration information for the JSP files in a web application. It has two sub-elements: taglib and jsp-property-group. The taglib element defines the syntax for declaring that a tag library is available to the application in the deployment descriptor. This can be done to override implicit map entries from TLD files and from the container.

• security-constraint: The security-constraint is used to associate security constraints with one or more web resource collections. See Chapter 6, Security, for more details on this element.

• login-config: The login-config is used to configure the authentication method that should be used, the realm name that should be used for this application, and the attributes that are needed by the form login mechanism. See Chapter 6, Security, for more details on this element.

• security-role: The security-role contains the definition of a security role. The definition consists of an optional description of the security role and the security role name. See Chapter 6, Security, for more details on this element.

• jndiEnvironmentRefsGroup: This group keeps the use of the contained JNDI environment reference elements consistent across Java EE deployment descriptors.

• message-destination: The message-destination specifies a message destination. The logical destination described by this element is mapped to a physical destination by the deployer.

• locale-encoding-mapping-list: The locale-encoding-mapping-list contains one or more locale-encoding-mapping(s). The locale-encoding-mapping contains locale name and encoding name. The locale name must be either Language-code, such as "ja", defined by ISO-639 or Language-code_Country-code, such as "ja_JP". The Country-code is defined by ISO-3166.

Annotations

The use of annotations in web artifact classes enables you to avoid JNDI lookups for resources, and EJB references as annotations provide for injection. The following are some annotations that are used in web artifact classes such as Servlets.

Resource annotation

The @Resource annotation is used to annotate resources such as JMS Connection Factories, JMS Queues, JMS Topics, DataSources, and so on. This annotation can be used on a field or a setter method. The name attribute of this annotation specifies the name relative to the java:comp/env where the resource is bound in the JNDI (See Chapter 8, JNDI). For example, an @Resource annotation with the name jms/TestQueue will result in the corresponding resource bound in the JNDI at java:comp/env/jms/TestQueue. For example, consider the @Resource annotation in the following code snippet:

@Resource(name="jms/TestQueue")
private Queue queue;

This results in the binding of the resource in the JNDI at java:comp/env/jms/TestQueue. The following is the resource mapping in the web deployment plan for this resource:

<nam:resource-env-ref xmlns:nam= "http://geronimo.apache.org/xml/ns/naming-1.2">
<nam:ref-name>jms/TestQueue</nam:ref-name>
<nam:pattern>
<nam:groupId>org.apache.geronimo.configs</nam:groupId>
<nam:artifactId>activemq-ra</nam:artifactId>
<nam:name>SendReceiveQueue</nam:name>
</nam:pattern>
</nam:resource-env-ref>

Here, the servlet field queue is injected with the physical resource SendReceiveQueue, mapped in the deployment plan.

An @Resource annotation on a field of type Boolean, Byte, Character, String, Short, Integer, Long, Float, or Double will result in an injection of the corresponding env-entry value defined in the deployment descriptor. For example, consider the @Resource annotation defined in the following code snippet:

@Resource(name="const/myEnvEntry")
private String country;

This results in the env-entry value defined in the following deployment descriptor being injected into servlet field:

<env-entry>
<env-entry-name>const/myEnvEntry</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>India</env-entry-value>
</env-entry>

Here, the servlet field country is injected with the value India.

EJB annotation

The @EJB annotation is used to define an EJB reference in a web artifact class (for example, a Servlet). This annotation can be used on either a field or a setter method. The name attribute of the annotation specifies the name relative to the java:comp/env where the resource is bound in the JNDI (See Chapter 8, JNDI). For example, consider the @EJB annotation in the following code snippet:

@EJB(name="ejb/LanguageService")
LanguageService langService;

This results in an EJB reference bound in the local JNDI at java:comp/env/ejb/LanguageService. The following is a snippet from a deployment plan that maps the EJB reference to an EJB:

<nam:ejb-ref xmlns:nam="http://geronimo.apache.org/xml/ns/ naming-1.2">
<nam:ref-name>ejb/LanguageService</nam:ref-name>
<nam:pattern>
<nam:groupId>test</nam:groupId>
<nam:artifactId>simple-app</nam:artifactId>
<nam:version>1.0</nam:version>
<nam:module>simple-ejb.jar</nam:module>
<nam:name>LanguageServiceBean</nam:name>
</nam:pattern>
</nam:ejb-ref>

The reference mapped in the deployment plan is injected into the web artifact class at runtime. Here, the servlet field langService is injected with a reference to the LanguageServiceBean. The EJB can be looked up in the web application by using the following code:

InitialContext ic = new InitialContext();
ic.lookup("java:comp/env/ejb/LanguageService");

Web deployment plan

The deployment plan for a web application named geronimo-web.xml can be packaged within the WAR file as WEB-INF/geronimo-web.xml or supplied as an external plan file during deployment. The schema geronimo-web-2.0.1.xsd of the deployment plan is shown graphically in the next screenshot:

• environment: Denotes the environment in which the application executes. This includes the class loading behavior, dependencies, and the module ID of the application. See Appendix A, Deployment plans, for more details.

• context-root: The context-root that identifies the application. This is the first part of the URL that is used to access the web application. The context-root must start with a '/' and end with a string.

• work-dir: The work directory name for use by the web application.

• web-container: The web container in which the application will run.

• container-config: Geronimo supports both Jetty and Tomcat web containers. This element for the web application needs to take container specific settings. It can hold a Tomcat element, a Jetty element, or both.

• jndiEnvironmentRefsGroup: This group captures resource mapping to JNDI names. See Chapter 8, Naming and JNDI, for more details.

• message-destination: message-destination is used to configure a JMS Queue or Topic, which acts like a destination for the messages delivered.

• security-realm-name: The name of the security realm against which the application will authenticate. See Chapter 6, Security, for more details.

• security: This is an abstract element that is used to support application level security features, that is, in the actual plan, this element will be replaced by other elements that implement this element.

• service: This is an abstract element that is provided so that any schema elements that implement this can be used here. For example, the <gbean> element for declaring GBeans are packaged along with this enterprise application.

• persistence: Persistence configuration for the application.

Tomcat specific configuration

Web applications that are intended to be deployed only on Geronimo with Tomcat as a web container can use a deployment plan conforming to the schema geronimo-tomcat-2.0.1.xsd, which is shown in the next screenshot:

The following is an explanation of the elements:

• host: The host element maps the web application to this particular host name.

• cross-context: The cross-context is an indicative element to specify that the web application will use a dispatch request to other applications, and this cross context should be enabled.

• disable-cookies: The presence of the disable-cookies element indicates that the cookies will not be used by the Tomcat web application and should be disabled.

• valve-chain: The valve-chain provides the list of first element Tomcat valves chain for this web application.

• listener-chain: The listener-chain provides the list of first element Tomcat lifecycle listener chains for this web application.

• tomcat-realm: The tomcat-realm specifies the Tomcat security realm used by this web application.

• manager: The manager provides the clustering implementation used by this web application.

• cluster: The cluster provides the name of the cluster that this web application belongs to.

• jndiEnviromentRefsGroup: The JNDI environment references group elements are used to map the resources to JNDI names. See Chapter 8, Naming and JNDI.

Jetty specific configuration

Web applications that are intended to be deployed only on Geronimo with Jetty as the web container can use a deployment plan conforming to the schema geronimo-jetty-2.0.2.xsd, which is shown in the next screenshot:

The following is an explanation of the elements:

• host: The host element maps the web application to this particular host name.

• virtual-host: The virtual-host element maps the web application to this particular host name.

• session-manager: The session-manager provides the fully-qualified class name of the clustering implementation org.codehaus.wadi.jetty5.JettyManager used by this web application.

• compact-path: Setting this to true makes paths such as http://localhost:8080/myapp//myresource.htm act the same as http://localhost:8080/myapp/myresource.htm

Sample web application

We have a sample web application named Helloworld-webapp, that has servlets, filters, and listeners. The source code for this application is provided in the samples for this book. After deploying the application, access the application at http://localhost:8080/helloworld. Enter a name, and click on the getGreeting button. Notice that the output from filter and servlet is displayed in the browser. Also notice the injected values of the country and queue fields that is displayed in the server console window. Access the link http://localhost:8080/helloworld/hello.jsp to see the invocation of various listeners.