A deployment descriptor is an XML file that describes a 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 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. By deployment plans, we refer to the server-specific XML files that help in deployment. These files can be created by tooling or by hand.
The different types of deployment descriptors, as specified in the Java EE specifications, are as follows:
Web deployment descriptor: This file should be named
web.xml, and should be present in theWEB-INFdirectory of your web module.EJB deployment descriptor: This file should be named
ejb-jar.xml, and should be present in theMETA-INFdirectory of the EJB module.Application deployment descriptor: This file should be named
application.xml, and should be present in theMETA-INFdirectory of the EAR file in which the application is packaged.Application Client deployment descriptor: This file should be named
application-client.xml, and should be present in theMETA-INFdirectory of the application client module.Resource Adapter deployment descriptor: This file should be named
ra.xml, and should be present in the META-INF directory of the resource adapter module.
There are Geronimo-specific deployment plan counterparts for each of the Java EE 5 deployment descriptors. These are given below:
Web deployment plan: This file should be named
geronimo-web.xml, and should be present in theWEB-INFdirectory of your web module. This maps the resource references in theweb.xmlfile to server resources.EJB deployment plan: This file should be named
openejb-jar.xml, and should be present in theMETA-INFdirectory of the EJB module. This maps the resource references in theejb-jar.xmlfile to resources on the server.Application deployment plan: This file should be named
geronimo-application.xml, and should be present in theMETA-INFdirectory of the EAR file in which the application is packaged.Application Client deployment plan: This file should be named
geronimo-application-client.xml, and should be present in theMETA-INFdirectory of the application client module.Resource Adapter deployment plan: This file should be named
geronimo-ra.xml, and should be present in theMETA-INFdirectory of the resource adapter module.
An external deployment plan can also be specified during deployment. In this case, the plan file can have any name, and will override any deployment plan packaged within the archives.
Deployment plans are used to deploy services such as security realms into Geronimo. If the Service deployment plan is provided internally in the Java archive, it should be named geronimo-service.xml, and located under the META-INF directory.
All deployment plans use some common elements, such as environment and gbean definitions. In this appendix, we will examine these common elements.
The environment element defines elements that are used to store information such as the Module ID, dependencies, and the class loader for the module. This element is used in all of the Services and application modules' deployment plans. This element is defined in the namespace http://geronimo.apache.org/xml/ns/deployment-1.2. The schema representation is shown below:
The description of various elements under environment is as follows:
moduleId: moduleIdholds elements for thegroupId, artifactId, version, andtypeof the module. Module IDs are normally specified with slashes between the four components, such as GroupID/ArtifactID/Version/Type.groupId:This ID is used to name the group containing this module. WhengroupIdis not specified, by default, it is considered 'default' for declaration and wildcard '*' for dependencies.artifactId:This ID is used to name the module in a specified group. If noarticfactIdis provided, it will be defaulted to the file name of the module file. In case of dependencies,artifactIdmust be provided.version:This is used to specify the version number of the module, formatted by dot-separated numbers. If no version is provided, then it will be defaulted to a numeric timestamp generated bySystem.currentTimeMillis()at deploy time. In case of dependencies, the latest available version in the repository will be used.type:This element defines the type of the module. The type could be CAR, JAR, EAR, WAR, and so on. If no type is provided, then it will be defaulted appropriately by the deployer, depending upon the type of deployed module. In the case of dependencies, JAR will be used.
dependencies:Thedependencieselement defines all of the dependencies of this module on other modules and repository artifacts. You can specify zero or more dependencies by using thedependencychild element. Each dependency element may containgroupId, artifactId, version, type, andimportelements. SeemoduleIdabove, for a description ofgroupId, artifactId, version, andtype.import:Theimportelement is a restrictive element used to define the type of dependency. The default (when omitted) is to include the specified dependency in the class loader (as a parent or URL). If defined as "classes", it means that the classes must be included in the current module's class loader but the dependency does not need to be started. Specifying "services" means that the dependency (a module) must be started before the current module, but it is not included as a parent class loader.
hidden-classes:This element is used to specify a list of classes that will never be loaded from parent class loaders of this module. For example, if Log4J was listed here, the module would never see Geronimo's copy of Log4J. If the module provides its own Log4J JAR then it would use that. Otherwise, it would not be able to load Log4J at all. The classes are specified in zero or more childfilterelements, where each filter element specifies a fully-qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed in this element will be treated as hidden.non-overridable-classes:This element is used to specify a list of classes that will only be loaded from parent class loaders of this module (never from the module's own class loader). For example, this is used to prevent a web application from redefiningjavax.servlet, so those classes will always be loaded from the server instead of the web application's own class-path. The classes are specified in zero or more childfilterelements, where each filter element specifies a fully-qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as non-overridable.inverse-classloading:If this element is specified, the standard class loading delegation model is to be reversed for this module.suppress-default-environment:If this element is specified, then any default environment built by a builder when deploying the plan will be suppressed. An example of where this is useful is when deploying a connector on an application client in a separate (standalone) module (not as part of a client plan). The connector builder default Environment includes some server modules that won't work on an application client, so you need to suppress the default environment and supply a complete environment including all parents for a non-application-client module that you want to run on an application client.
A typical environment element in a deployment plan looks like the block of code below:
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/ deployment-1.2"> <dep:moduleId> <dep:groupId>packt-samples</dep:groupId> <dep:artifactId>helloworld</dep:artifactId> <dep:version>1.0</dep:version> <dep:type>war</dep:type> </dep:moduleId> <dep:dependencies> <dep:dependency> <dep:groupId>log4j</dep:groupId> <dep:artifactId>log4j</dep:artifactId> <dep:version>1.2.14</dep:version> <dep:type>jar</dep:type> <dep:import>classes</dep:import> </dep:dependency> </dep:dependencies> <dep:hidden-classes> <dep:filter>org.apache.log4j</dep:filter> </dep:hidden-classes> <dep:non-overridable-classes> <dep:filter>javax.servlet</dep:filter> </dep:non-overridable-classes> <dep:inverse-classloading/> </dep:environment>
Here the module will be deployed under the ID packt-samples/helloworld/1.0/war. The module has a dependency on the log4j/log4j/1.2.14/jar repository artifact. All classes in the package org.apache.log4j and its sub-packages in the parent class loader are hidden and will be loaded in the module's class loader. All classes in the package javax.servlet and its sub-packages will be loaded from the parent class loader and will never be overridden in the module's class loader. The class loader uses inverse class loading.