| 11.3. Structure of the Deployment Plan | ||
|---|---|---|
 | Chapter 11. Web Applications (WARs) [DRAFT (1.0)] |  |
| 11.3. Structure of the Deployment Plan | ||
|---|---|---|
| | Chapter 11. Web Applications (WARs) [DRAFT (1.0)] | |
The internal structure of the web application deployment plan looks like this:
The following sections discuss the elements of the deployment plan in more detail. Note that the order of the elements is fixed as shown in Figure 11.1, “Web Application Deployment Plan Overview”, and that's the order the elements are discussed in below. Of these elements, only the header (discussed above) and the context-priority-classloader (covered in Section 11.3.2, “Basic Web Application Settings”) are required.
The elements in the classloader-infoGroup are used to customized the web application's class path.
The elements here are:
Refers to another configuration deployed in the server. That configuration will be added as a parent of this one (a configuration may have more than one parent). The main effect is that the class loader for the web application will add the class loader for that configuration as a parent. Additionally, the parent configuration will be started before the web application.
Adds a third-party library to the class path for the web application. Any common libraries used in this manner should be located in a subdirectory of the repository/ directory of the main Geronimo installation.
Lists packages or classes that may be in a parent class loader, but should not be exposed from there to the web application. This is typically used when the web application wants to use a different version of a library that one of its parent configurations (or Geronimo itself) uses. For example, Geronimo 1.0 uses Log4J 1.2.8. If the web application wanted to use a newer version, it could include the newer version in WEB-INF/lib and then add org.apache.log4j to the list of hidden-classes so that the Log4J classes could not be loaded from a parent class loader.
Lists packages or classes that the web application should always load from a parent class loader, and never load from WEB-INF/lib or WEB-INF/classes. This might be used to force a web application to share the same instance of a common library with other web applications, even if they each include it in their own WAR.
Used to list classes or packages. The format is a comma-separated list of packages or fully-qualified class names (for example: javax.servlet,javax.ejb).
The import and dependency element both ultimately need to identify a URI. In the case of an import, the URI must match the configId of another deployed module or configuration. In the case of a dependency, the URI must identify an entry in the Geronimo repository.
The Geronimo repository uses URIs divided into four components: the Group ID, Artifact ID, Type, and Version. For example, for Log4J, the Group ID is "log4j", the Type is "jar", the Artifact ID is "log4j", and the version included with Geronimo is "1.2.8". These components correspond to the path to the file in the repository directory of the file system, which is normally repository/groupId/types/artifactId-version.type (so for Log4J, repository/log4j/jars/log4j-1.2.8.jar). The URI format used by the repository looks like groupId/artifactId/version/type (so, log4j/log4j/1.0/jar). Therefore, the dependency element must use a URI of this format, either listing it as a whole string or identifying each of the component parts.
The URIs used by the import element, however, need to match the configId of another module or configuration in the server. The configurations shipped with Geronimo also obey the standard URI format mentioned above, but that is strictly optional. When you provide configIds for your own modules, you may choose to use that format or not as you please. For example, you could use the configId MyWebApp, or you could use the configId MyCompany/MyWebapp/1.0.2/war. Therefore, the import element may list a configId URI as a whole String (matching exactly the configId for the other module). It may instead identify each of the component parts, but only if the configuration it's referring to used the URI syntax described above.
This syntax is used to specify the complete URI as a String:
The value of this element should identify the JAR or configuration, using the syntax described above. For example, specifying regexp/regexp/1.3/jar would select the JAR geronimo/repository/regexp/jars/regexp-1.3.jar. If there is no such JAR available, the module will fail to start.
Instead of a single URI, this creates a URI out of several components. Again, this works for all dependency elements, but only works for an import element if the targeted configuration used a URI composed of all these parts separated by slashes.
Identifies the "group" of the targeted library or configuration, which is usually either the name of the vendor who produced it, or an identifier for the application or project in question.
The name of the specific library or configuration (without any version information).
The version number of the specific library or configuration.
The type of the library or configuration (jar, war, ear, rar, etc.). If omitted, defaults to jar. Note that many of the components shipped with Geronimo use a type of car (for Configuration ARchive), since the Geronimo server is built from a number of separate configurations.
Here are some sample imports and dependencies.
Example 11.1. Web Application: Imports and Dependencies
Assume the repository has a file repository/postgresql/jars/postgresql-8.0-314.jdbc3.jar, and the server has a JMS configuration called MessagingResources. A web application could refer to them like this:
<import><uri>MessagingResources</uri></import> <dependency> <uri>postgresql/postgresql-8.0/314.jdbc3/jar</uri> </dependency>
It's also possible to refer to the dependency using the split-up syntax, but the import cannot use that syntax because the module that's being imported did not use that syntax in its configId. That would look like this:
<import><uri>MessagingResources</uri></import> <dependency> <groupId>postgresql</groupId> <artifactId>postgresql-8.0</artifactId> <version>314.jdbc3</version> </dependency>
There are two simple elements that provide some basic web application options:
The context root is the first segment of the URL used to access the web application. For example, if the context-root was example then a typical URL to the application would start with http://host:port/example/
If the web application is packaged in an EAR, then the context root can be specified in the EAR's application.xml deployment descriptor. If the web applications is instead deployed as standalone WAR, then this element is necessary unless you want the context root to default to the WAR name.
This element takes a value of true or false. When set to true, the web application is spec-compliant and loads classes and resources from the web application ClassLoader if possible before falling back to the application and server ClassLoaders. When set to false, the web application uses the normal ClassLoader behavior (namely, always try to load from the parent ClassLoader first). The default is false.
While Geronimo supports both Tomcat and Jetty, there are some settings that only apply to one container or the other (mainly, virtual host settings). This block holds that kind of container-specific information:
The container-config element holds arbitrary XML content which can be used to provide container-specific settings above and beyond the standard settings included in this container-neutral deployment plan. In practice, it holds either a tomcat element or a jetty element or both, with the content discussed in the following sections.
The container-config settings for Tomcat are:
The elements introduced here are:
Holds all the settings related to Tomcat. This should be a direct child of the container-config element.
Associates this web application with a particular Tomcat host. If this is set, it means the web application will only be exposed through the host name or IP address configured for that host. By default, only one Tomcat host is defined in Geronimo (and it listens on all available interfaces), but if you define additional hosts, you can assign this web application to one of them. The value here must match the name specified in the initParams for the host GBean.
If this element is present, then cross-context dispatching is enabled (that is, one web application can dispatch requests to a different web application). This is required, for example, when a portal server in one WAR attempt to invoke portlets in another WAR. This element has no content, it is simply present or not present.
Lets you associate a list of Tomcat valves with the current web application. This must match the name of a GBean representing the first valve in the chain..
Lets you specify the Tomcat security realm used for this web application. This must match the name of a GBean that represents a Tomcat security realm.
Selects the clustering implementation to be used for this web application. This must match the name of a GBean that is a subclass of org.apache.geronimo.tomcat.ManagerGBean. If this element is omitted, clustering is disabled. Clustering requires additional configuration above and beyond the elements here. Note: the syntax for configuring clustering will likely change in the next release of Geronimo.
Indicates which cluster this web application should be a member of. This must match the name of a GBean of type org.apache.geronimo.tomcat.cluster.CatalinaClusterGBean. Note: the syntax for configuring clustering will likely change in the next release of Geronimo.
![[Note]](images/note.png) | Note |
|---|---|
The Tomcat elements described here use the namespace http://geronimo.apache.org/xml/ns/web/tomcat/config-1.0 from the schema geronimo-tomcat-config-1.0.xsd. | |
The container-config settings for Jetty are:
The elements introduced here are:
Holds all the settings related to Jetty. This should be a direct child of the container-config element.
Any number of virtual host entries may be listed here, in which case the web application will be exposed only to requests to those host names or IP addresses. Otherwise, the web application will be exposed to any host names or IP addresses that Geronimo is listening on (which is all the interfaces for the machine, by default).
Selects a clustering implementation to be used for this web application. This must be the fully-qualified class name of a class... The only value currently supported is org.codehaus.wadi.jetty5.JettyManager. Clustering requires additional configuration above and beyond the elements here. Note: the syntax for configuring clustering will likely change in the next release of Geronimo.
| Note |
|---|---|
The Jetty elements described here use the namespace http://geronimo.apache.org/xml/ns/web/jetty/config-1.0 from the schema geronimo-jetty-config-1.0.xsd. | |
A web application that needed to associate with a particular virtual host for either web container might use a block like this:
Example 11.2. Web Application: Configuring Virtual Hosts
<container-config>
<tomcat
xmlns="http://geronimo.apache.org/xml/ns/web/tomcat/config-1.0">
<host>virtual.host.com</host>
</tomcat>
<jetty
xmlns="http://geronimo.apache.org/xml/ns/web/jetty/config-1.0">
<virtual-host>virtual.host.com</virtual-host>
</jetty>
</container-config>However, note that for this to work in Tomcat, a Host GBean must have been deployed with the name virtual.host.com (no additional configuration is required when using Jetty). This GBean would look like this (though it typically should not be deployed as part of the web application, since it wouldn't work in a Jetty configuration):
<gbean name="MyVirtualHost"
class="org.apache.geronimo.tomcat.HostGBean">
<attribute name="className">
org.apache.catalina.core.StandardHost
</attribute>
<attribute name="initParams">
name=virtual.host.com
appBase=
workDir=work
</attribute>
</gbean>The ejb-jar.xml file may declare several types of references:
EJB references
Resource references
Message destination references
Web services references
This section describes how the geronimo-web.xml file maps those references to specific items available in the server environment.
| Note |
|---|---|
The schema includes a placeholder element (gbean-ref) for GBean references (that is, putting a reference to an arbitrary GBean in the component's java:comp/env JNDI space), but that is not yet working in Geronimo 1.0 so it is not covered here. | |
All of the resource types use common elements to refer to GBeans running in the server. These elements are known as the objectNameGroup, and look like this:
The elements introduced here are:
The domain name portion of the GBean Name identifying the EJB or resource to map to. This should usually be geronimo.server, and if not specified, it defaults to the domain of the JSR-77 J2EEServer that was configured for the deployer GBean that's deploying the current module -- which is going to be geronimo.server unless you have substantially altered your default configuration.
The J2EE Server portion of the GBean Name identifying the EJB or resource to map to. This should usually be geronimo, and if not specified, it defaults to the name of the JSR-77 J2EEServer that was configured for the deployer GBean that's deploying the current module -- which is going to be geronimo unless you have substantially altered your default configuration.
The name of the application that the target EJB or resource is in. If the target module was deployed standalone, this would be null. If it was deployed as part of an EAR, this should be the applicationId specified for the EAR, or the configId if no applicationId was specified.
The configId of the module that the target EJB or resource is in.
Should identify the type of the EJB or resource that this is pointing to. For EJBs, this should be one of StatefulSessionBean, StatelessSessionBean, EntityBean, or MessageDrivenBean, depending on the type of the target EJB. For a typical connection factory resource (such as a JDBC pool or JMS connection factory), this should be JCAManagedConnectionFactory. For a CORBA CSS, this should be CORBACSS.
The JSR-77 name of the target object. This would be the ejb-name for an EJB, the connectiondefinition-instance/name for a connection factory, or the GBean name for a CORBA CSS.
The ejb-ref and ejb-local-ref elements let you map EJB references to specific EJBs outside of the current application. (These elements are not necessary for EJBs within the current application, because an ejb-link can be used in the standard J2EE deployment descriptor and then no Geronimo-specific configuration is necessary.)
Since EJBs requiring mapping are usually in a different application, be aware that the current application would need to include the EJB client interfaces for the remote EJBs. To avoid this, the current application may refer to the application containing the remote EJBs with an import element (see Section 11.3.1, “Customizing the Web Application Class Path”), and then the interface classes will be available through the parent ClassLoader.
The ejb-ref element is used to connect to an EJB through its remote home and remote interfaces. The EJB need not necessarily be located in a different server or JVM; sometimes the semantics of the remote interface are simply preferable to those of the local interface (for example, when an EJB will be accessed by both local and remote clients and doesn't want to worry about arguments being copied in some cases and passed by reference in others).
![[Warning]](images/warning.png) | Warning |
|---|---|
Geronimo does not currently support EJB references to EJBs running outside the current server except via CORBA. Support for that will be added in a future release. | |
The ejb-local-ref element is used to connect to an EJB through its local home and local interfaces. The EJB is usually defined in the same EAR as the web application, though it may also be in an EJB JAR or application EAR which is defined as a parent of the current application.
An EJB reference can currently be mapped one of three ways. Every EJB reference here will have a ref-name and then use either the target-name, the ejb-link, or the objectNameGroup of elements to identify the specific EJB to map to.
Each reference must have a ref-name, which is used to match the definition here to the EJB reference in web.xml. The value here must match the ejb-ref-name in the ejb-ref or ejb-local-ref in web.xml.
See Section 11.3.4.1, “Common Resource Mapping Elements” for a full description of the elements in the objectNameGroup.
Refers to an EJB using CORBA as the lookup and communication mechanism. The corbaNameGroup is described in detail in the next section.
Instead of splitting out all the components using the objectNameGroup, you can specify a single GBean Name containing all that information to identify the EJB. This may be used to map an EJB in a different application. It would typically look like: geronimo.server:J2EEApplication=ear-name,J2EEModule=ejb-jar-name.jar, J2EEServer=geronimo,j2eeType=StatelessSessionBean,name=EJBName
An ejb-link can be specified here to identify an EJB in the same application EAR by name (must match the ejb-name for the EJB in its ejb-jar.xml). A value specified here overrides any ejb-link specified for the same EJB reference in web.xml.
The corbaNameGroup can be used to resolve an EJB reference to an EJB running in a remote machine:
Besides identifying a specific remote EJB, this block selects a Client Security Service (CSS) to be used to manage security settings for the CORBA connection. The CSS is a GBean deployed elsewhere in Geronimo, so that multiple EJB references can share the same CSS settings by pointing to the same CSS. There are several ways to identify a CSS. The simplest is the css-link, which selects a CSS by name, assuming it is deployed in the same application or in a standalone plan. Otherwise the CSS can be identified by its GBean Name, either as a single String (using css-name) or split into the various components (under the css element).
Identifies the CORBA name server that has a reference to the target object. This would typically look like: corbaloc::localhost:1050/NameService
The name of the target EJB as known to the CORBA name server. For EJBs exposed via CORBA in Geronimo, this is usually the ejb-name of the EJB.
Holds a series of individual GBean Name components, which are used together to build a GBean Name to identify the target CSS.
See Section 11.3.4.1, “Common Resource Mapping Elements” for a full description of the elements in the objectNameGroup.
Identifies a CSS by its name alone (the same as the name= component of its GBean Name). This searches for a CSS with a matching name in the same application, and then deployed at the top level of the server (outside of any application). If this would result in multiple matches, the CSS must be identified by its full GBean Name (using the css-name or css) instead.
The full GBean Name of the target CSS. This may be used to map to a CSS in a different application. It would typically look like: geronimo.server:J2EEApplication=ear-name,J2EEModule=module-name.jar, J2EEServer=geronimo,j2eeType=CORBACSS,name=MyCSSConfig
Example 11.3. Web Application: EJB Reference Example
The web.xml deployment descriptor might include two EJB references like this:
WEB-INF/web.xml
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4">
...
<ejb-ref>
<ejb-ref-name>ejb/RemoteSession</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<home>com.example.RemoteSessionHome</home>
<remote>com.example.RemoteSession</remote>
</ejb-ref>
<ejb-local-ref>
<ejb-ref-name>ejb/LocalSession</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home>com.example.LocalSessionHome</local-home>
<local>com.example.LocalSession</local>
<ejb-link>LocalSession</ejb-link>
</ejb-local-ref>
</web-app>The first (remote) reference needs to be resolved in the Geronimo deployment plan. The second (local) reference has an EJB Link, so that one is ready to go as it. The remote reference could be resolved to an EJB in a different J2EE application in Geronimo like this.
WEB-INF/geronimo-web.xml
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
configId="MyWebApp">
<naming:ejb-ref>
<naming:ref-name>ejb/RemoteSession</naming:ref-name>
<naming:target-name>
geronimo.server:J2EEApplication=other-ear-name,
J2EEModule=other-ejbs.jar,J2EEServer=geronimo,
j2eeType=StatelessSessionBean,name=RemoteSession
</naming:target-name>
</naming:ejb-ref>
</web-app>Note that the target-name value should be specified all on one line; it is only split here to fit on one page!
The resource-ref and resource-env-ref elements let you map resource references (typically JDBC or JMS resources) to specific resources available in the server. In general, a resource-env-ref is used to reference an administered object deployed as part of a J2EE Connector, while a resource-ref is used to reference a JDBC resource, JMS connection factory, or other type of resource. In J2EE 1.3, resource-env-refs were used to reference JMS destinations as well, but as of J2EE 1.4 the message-destination-ref element of the web.xml deployment descriptor can be used, and no Geronimo-specific mapping is required in the deployment plan for the web module (this is discussed further in Section 11.3.4.4, “Resolving JMS Destination References”).
The resource-ref is used for most resource types. The deployment plan elements described here are used to identify a specific resource to map to the reference declared by the web application.
There are several ways to identify a resource reference. One is to specify the component by a simple name (resource-link), while the other is to use a more complex ObjectName (target-name, or the individual components in the objectNameGroup). The resource-link handles most common resource situations (J2EE connectors in the same application or deployed standalone, including JDBC pools and JMS connection factories) while the target-name or objectNameGroup can be used for any resource. This might be important if, for example, two resource adapter deployments use the same name for their connection factory, so the resource-link does not uniquely identify one and it must be fully-qualified. Finally, in the special case of URL resources, the url element provides a value for the resource (instead of looking something else up in the server environment).
Each reference must have a ref-name, which is used to match the definition here to the resource reference in web.xml. Specifically, the value here must match the res-ref-name in the resource-ref in web.xml.
See Section 11.3.4.1, “Common Resource Mapping Elements” for a full description of the elements in the objectNameGroup. This can be used to identify the GBean for a resource running anywhere in the current Geronimo server.
Can be used to identify any resource deployed as a J2EE connector (including JDBC pools and JMS connection factories). The resource-link specified here should match the connectiondefinition-instance/name element in the Geronimo deployment plan for the connector.
A way to uniquely identify any type of resource running in the server. This should be a GBean Name identifying the resource, such as geronimo.server:J2EEServer=geronimo,J2EEApplication=null, J2EEModule=some-ra.rar,j2eeType=JCAManagedConnectionFactory,name=MyDatasource
If the resource type was java.net.URL, this element can be used to provide a value for the URL reference.
The resource-env-ref is used for administered objects deployed as part of a J2EE Connector. In J2EE 1.3 applications, it's also used for JMS topics and queues. The deployment plan elements described here are used to map a specific administered object in the server environment to the reference declared by the web application.
Note that there are four possible ways to resolve a resource environment reference. The elements used here are:
Each reference must have a ref-name, which is used to match the definition here to the resource environment reference in web.xml. Specifically, the value here must match the resource-env-ref-name in the resource-env-ref in web.xml.
See Section 11.3.4.1, “Common Resource Mapping Elements” for a full description of the elements in the objectNameGroup. This can be used to identify an admin object GBean to map the resource environment reference to.
Can be used to identify any admin object deployed as part a J2EE connector (typically JMS topics and queues). The message-destination-link value specified here should match the message-destination-name element in the admin object section of the Geronimo deployment plan for the connector. This element is deprecated and will be removed in a future release in favor of admin-object-link.
Due to a bug, this mapping style does not work in releases earlier than Geronimo 1.0.1. If the admin-object-link is used, this can be used to identify the module that the admin object was deployed in. If admin-object-link is used but this element is left out, the current module will be searched for a matching admin object, as well as any connectors deployed at the top level of the server (e.g. not in an EAR).
Due to a bug, this mapping style does not work in releases earlier than Geronimo 1.0.1. Can be used to identify any admin object deployed as part a J2EE connector. The value specified here should match the message-destination-name element in the admin object section of the Geronimo deployment plan for the connector.
Uniquely identifies an admin object running elsewhere in Geronimo. This should be a GBean Name identifying the admin object, such as geronimo.server:J2EEServer=geronimo,J2EEApplication=null, J2EEModule=some-ra.rar,j2eeType=JCAAdminObject,name=MyQueue
Example 11.4. Web Application: Resource Reference Example
The web.xml deployment descriptor might include a resource reference and a resource environment reference like this:
WEB-INF/web.xml
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" version="2.4">
...
<resource-ref>
<res-ref-name>jms/AConnectionFactory</res-ref-name>
<res-type>javax.jms.ConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-env-ref>
<resource-env-ref-name>jms/ATopic</resource-env-ref-name>
<resource-env-ref-type>
javax.jms.Topic
</resource-env-ref-type>
</resource-env-ref>
</web-app>These references need to be resolved in the Geronimo deployment plan. Assuming a JMS connector has been deployed with settings like in Example 7.1, “JMS Resource Group Deployment Plan”, the resources could be resolved like this:
WEB-INF/geronimo-web.xml
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
configId="MyWebApp">
<naming:resource-ref>
<naming:ref-name>jms/AConnectionFactory</naming:ref-name>
<naming:resource-link>
MyConnectionFactory
</naming:resource-link>
</naming:resource-ref>
<naming:resource-env-ref>
<naming:ref-name>jms/ATopic</naming:ref-name>
<naming:message-destination-link>
MyTopic
</naming:message-destination-link>
</naming:resource-env-ref>
</web-app>JMS destination references are an odd case because the preferred syntax changed between J2EE 1.3 and J2EE 1.4. The advantage to the newer syntax is that there is usually no Geronimo-specific configuration required in the WAR, whereas J2EE 1.3 requires settings in both the web.xml and geronimo-web.xml files. In either case, the references need to be matched up to the settings used when the JMS destination was deployed (for more information on deploying JMS resources, see Chapter 7, JMS Configuration [DRAFT (1.0)]).
As of J2EE 1.4, a reference to a topic or queue can be configured specifically in the web.xml file, like this:
WEB-INF/web.xml
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
...
<message-destination-ref>
<message-destination-ref-name>
jms/ATopic
</message-destination-ref-name>
<message-destination-type>
javax.jms.Topic
</message-destination-type>
<message-destination-usage>
Produces
</message-destination-usage>
<message-destination-link>MyTopic</message-destination-link>
</message-destination-ref>
<message-destination>
<message-destination-name>MyTopic</message-destination-name>
</message-destination>
</web-app>The message-destination element declares the Topic, and the message-destination-ref declares a reference to it and places the destination into the java:comp/env JNDI space for the web application components. This works automatically in Geronimo if the message-destination-name specified above matches the adminobject/message-destination-name in the Geronimo deployment plan for the JMS destination (though the message destination should have been deployed already). In this case there's no need for any more configuration in the WAR -- in particular, no settings are necessary in the geronimo-web.xml deployment plan.
For reference, here's a snippet from a JMS connector deployment plan that matches the WAR configuration above:
META-INF/geronimo-ra.xml
<connector
xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.0"
version="1.5"
configId="MyJMSResources"
parentId="MyJMSServer">
...
<adminobject>
<adminobject-interface>
javax.jms.Topic
</adminobject-interface>
<adminobject-class>
org.codehaus.activemq.message.ActiveMQTopic
</adminobject-class>
<adminobject-instance>
<message-destination-name>
MyTopic
</message-destination-name>
<config-property-setting name="PhysicalName">
MyTopic
</config-property-setting>
</adminobject-instance>
</adminobject>
</connector>If the message-destination-name values don't match, then the following Geronimo configuration block can be used:
Note that there are several possible ways to resolve a message destination. The elements used here are:
Each reference must have a message-destination-name, which is used to match the definition here to the message destination declared in web.xml. Specifically, the value here must match the message-destination-name in the message-destination in web.xml.
See Section 11.3.4.1, “Common Resource Mapping Elements” for a full description of the elements in the objectNameGroup. This can be used to identify an admin object GBean to map the message destination reference to.
If the admin-object-link is used, this can be used to identify the module that the admin object was deployed in. If admin-object-link is used but this element is left out, the current module will be searched for a matching admin object, as well as any connectors deployed at the top level of the server (e.g. not in an EAR).
Can be used to identify any admin object deployed as part a J2EE connector. The value specified here should match the message-destination-name element in the admin object section of the Geronimo deployment plan for the connector.
Uniquely identifies an admin object running elsewhere in Geronimo. This should be a GBean Name identifying the admin object, such as geronimo.server:J2EEServer=geronimo,J2EEApplication=null, J2EEModule=some-ra.rar,j2eeType=JCAAdminObject,name=MyQueue
Using this syntax, the message-destination declared in web.xml above could be mapped like this:
WEB-INF/geronimo-web.xml
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
configId="MyWebApp">
<naming:message-destination>
<naming:message-destination-name>
MyTopic
</naming:message-destination-name>
<naming:admin-object-link>
MyApplicationTopic
</naming:admin-object-link>
</naming:resource-env-ref>
</web-app>This means that the destination known to the web application as MyTopic (and present in JNDI at java:comp/env/jms/ATopic) will actually connect to a topic configured using an admin object named MyApplicationTopic in the JMS connector deployment plan (and may have still another physical name in the underlying JMS server!).
The message-destination and message-destination-ref elements didn't exist in J2EE 1.3. Instead, JMS destination references were declared using resource-env-ref elements, and these would be resolved in the Geronimo deployment plan. For example, the same Topic reference in J2EE 1.3 would look like this:
WEB-INF/web.xml
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
...
<resource-env-ref>
<resource-env-ref-name>jms/ATopic</resource-env-ref-name>
<resource-env-ref-type>
javax.jms.Topic
</resource-env-ref-type>
</resource-env-ref>
</web-app>Then this would be mapped as described in Section 11.3.4.3.2, “resource-env-ref for J2EE Connector Administered Objects”:
WEB-INF/geronimo-web.xml
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
configId="MyWebApp">
<naming:resource-env-ref>
<naming:ref-name>jms/ATopic</naming:ref-name>
<naming:message-destination-link>
MyTopic
</naming:message-destination-link>
</naming:resource-env-ref>
</web-app>Note that you're still depending on the definition of the JMS destination in the Geronimo deployment plan for the JMS resource -- the message-destination-link above needs to match the same adminobject/message-destination-name value.
As of J2EE 1.4, web applications can declare reference to web services, which may be running in Geronimo or elsewhere. Fully configuring web services references is somewhat complex (involving separate files), and is addressed in more detail in Chapter 16, Web Services [DRAFT(1.0)]. This section describes the elements that appear in the geronimo-web.xml deployment plan.
In order to make sense of this configuration scheme, there are several important things to understand about web services references:
One web service may include multiple "ports", each of which is a mapping of a connection URL to a "binding" (ultimately consisting of one or more operations and associated configuration within the service). A web service reference points to one or more ports. So for a web service with multiple ports, there might be several references to the same service but targeting different ports, or there may be one service reference with several ports the client can use.
Normally, the WSDL file for a web service specifies all the ports that the service provides, including accurate connectivity information to access the port. This is contained in a service element in the WSDL, which also specifies a name for the service.
Not all WSDL files are complete -- they may be missing the service element, and the ports may not have a correct URL to connect to the web service. However the WSDL must always include the bindings.
Therefore, there are two possible approaches to resolving web services references. One is to select one or more existing ports from the WSDL (using service-ref/port), potentially overriding the URL to the server hosting the web service (in case, for example, the WSDL incorrectly specifies "localhost" for the server name). The other approach is used for incomplete WSDL files, and is used to fill out all the missing information for the service and the ports it contains (using service-ref/service-completion). This latter approach is not preferred, since it requires including a lot of information that should be in the WSDL in the geronimo-web.xml plan instead, but it can be used when the WSDL is incomplete and cannot be changed (because it is provided by a third party, etc.).
Each reference must have a service-ref-name, which is used to match the definition here to the web service reference in web.xml. Specifically, the value here must match the service-ref-name in the service-ref in web.xml.
If the WSDL for the web service is not complete, this element holds missing information. The service reference will be configured to target all ports defined here. If this element is not used, the WSDL must be complete, and the service reference will target the subset of ports listed instead.
Specifies the name of the service, which normally would have been specified in the missing service block of the WSDL file.
If specified within a service-completion element, fully defines a port by providing all the data missing from the WSDL file. If specified directly under the service-ref element, designates the ports that should be available through this service reference. In either case, the port specifies some or all of the URL used to connect to the web service. This is split into several child elements, so the actual URL would look like protocol://host:port/uri. If this is not in a service-completion, the protocol, host, and network port default to the values provided in the WSDL.
The port element looks like this:
The elements introduced here are:
The name that identifies this port.
Part of the connection information used to connect to the port. This is the network protocol, typically http or https.
Part of the connection information used to connect to the port. This is the host that the port runs on.
Part of the connection information used to connect to the port. This is the network port used to connect to the web service port.
Part of the connection information used to connect to the port. This is the path information used once the server connection is established.
When a caller invokes a secure web service, their current Geronimo security information is used to authenticate. In case the web service uses different logins than the Geronimo application, the Geronimo security information may include multiple sets of authentication information (credentials), each with a name that identifies it. If that's the case, the name provided here identifies which set of credentials should be passed to the web service. So for example, a user may sign on as "jsmith" and get set up in Geronimo as (jsmith with password foo) and also a second credential (john_smith with password bar) where that second credential is named "ws_credentials". Then if the credentials_name field isn't present they'd log into a secure web service as jsmith, or if the credentials-name was set to ws_credentials they'd log in to the web service as john_smith. Of course, the Geronimo security realm must be configured properly to support this (see Chapter 9, Security Configuration [DRAFT (1.0-pre)]).
A port is essentially a mapping of a binding to a URL. The other components in the port element specify the URL, and the value here names the binding. There must be a binding with this name in the WSDL file.
The security element maps security roles declared in the web.xml deployment descriptor to specific users or groups in the security realms configured in Geronimo. It also allows you to specify a default user or group to be used when the end user has not yet logged in.
Note that the description elements are the standard J2EE 1.4 -- there may be many of them at each appropriate location (typically with different languages for each occurrence in the group).
The other elements here are:
The name of the Geronimo security realm that will authenticate user logins. This should match the name specified for the security realm GBean. (The standard security realm in Geronimo is named geronimo-properties-realm -- to deploy additional security realms, see Chapter 9, Security Configuration [DRAFT (1.0-pre)].)
Groups the security role mapping settings for the web application.
May be true or false. If set to true, any work done by the web application will be performed as the calling Subject, instead of "as the application server". This can be used to hook into the Java JVM security sandbox (for example, to only allow trusted users to access the server filesystem). It is not usually necessary, as the application-level security features are typically sufficient. When it is enabled, you may want to adjust the security policy used for the server to control certain permissions by subject. This element is optional and the default is false.
May be true or false. The default is false, but advanced JACC users may enable it to insert their own code in the JACC processing chain.
This attribute is not applicable to web applications.
Holds a principal which will be used any time an unauthenticated user accesses an unsecured page. Normally this would result in no principal being used, but you can specify a default here. This would, for example, allow an insecure page to access a secured EJB. This element is described in more detail below.
Holds the information mapping roles declared in the web.xml deployment descriptor to specific principals present in the security realms available to Geronimo.
Holds the set of principals that map to a single role from web.xml. This is described in more detail below.
The default-principal element looks like this:
Configures a principal using simple principal mapping. Principal elements are discussed in the next section.
Configures a principal using login domain specific mapping. Principal elements are discussed in the next section.
Configures a principal using login domain and realm specific mapping. Principal elements are discussed in the next section.
Named credentials are used by external resources (e.g. a J2EE Connector or Web Service) that use per-user authentication, but require different authentication than the calling web application. So for example, a the default principal may be a user "jsmith" and this element can be used to set up a second credential ("john_smith" with password "foo") where that second credential is named "ws_credentials". Then when the user invokes a web service, the web service reference can be configured to look for and use a credential named "ws_credentials" instead of the normal principal. Normally named credentials are added by the Geronimo security realm, but in the case of the default principal, they must be manually configured here.
The name to store this credential under (ws_credentials in the example above)
The username that this credential should contain.
The password that this credential should contain.
The role element used for role mapping looks like this:
The elements used here are:
Holds the set of principals that map to a single role from web.xml.
The name used to identify this role. Must match a role-name specified in web.xml.
Configures a principal using simple principal mapping. Principal elements are discussed in the next section.
Configures a principal using login domain specific mapping. Principal elements are discussed in the next section.
Configures a principal using login domain and realm specific mapping. Principal elements are discussed in the next section.
Used for client certificate authentication.
The value here is matched against the distinguished name on the certificate presented by the client.
This boolean attribute is used to indicate which principal should be used if the web application has a run-as role set (in web.xml). If the run-as is set to the role that this principal is a member of, and this principal's designated-run-as is set to true, then this principal will be used to represent the user for the duration of the run-as call.
There are three types of principal elements available to specify either a default principal or the principals that should be included in a role.
Principals are normally identified by their principal class and principal name. Both values must match one of the principals for the current user in order for the user to successfully qualify for the application role. However, if the Support Advanced Mapping flag is enabled for the login modules used by the security realm that produced the principals (see Chapter 9, Security Configuration [DRAFT (1.0-pre)]), those principals are also identified by their login domain name and realm name, and the security mapping process can distinguish based on those characteristics of the principal as well.
The principal element is the most straightforward of the three:
The attributes used here are:
Each principal is represented by an object of a particular class by the security realm (e.g. an LDAP realm might use the classes com.foo.LDAPUser and com.foo.LDAPGroup). This attribute holds the fully qualified Java class name of the principal class. The class is necessary to distinguish between different types of principals that may have the same name (such as a group Administrator and a user Administrator). The principal classes used by the default Geronimo security realms are org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal (for users) and org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal (for groups).
This attribute holds the name of the principal, which should be unique among principals of a particular class if you're using simple mapping.
This boolean attribute is used to indicate which principal should be used if a Servlet has a run-as role set (in web.xml). If the run-as is set to the role that this principal is a member of, and this principal's designated-run-as is set to true, then this principal will be used to represent the user for the duration of the run-as call. This attribute should not be used for principals within the default-principal element.
The login-domain-principal element let principals be identified by the login module that produced them, as well as by their class and name:
This includes all the same attributes as the principal element, plus:
Must match the login-domain-name set for the JAAS Login Module that produced this principal in order for the principal to qualify the user to be in the current role. Additionally, the LoginModule must have its advanced mapping (also known as principal wrapping) flag enabled.
The realm-principal element let principals be identified by the realm that they came from, as well as by their class, name, and login domain:
This includes all the same attributes as the login-domain-principal element, plus:
Must match the realm-name set for the Geronimo security realm that produced this principal in order for the principal to qualify the user to be in the current role. Additionally, the LoginModules that produced this principal must have its advanced mapping (also known as principal wrapping) flag enabled.
Here's an example of the security block from a Geronimo web application deployment plan, using simple mapping:
Example 11.5. Web Application Security Example
<security xmlns="http://geronimo.apache.org/xml/ns/security-1.1">
<default-principal>
<principal class="com.example.LDAPUserPrincipal"
name="Anonymous" />
</default-principal>
<role-mappings>
<role name="Administrator">
<principal class="com.example.LDAPUserPrincipal"
name="Aaron" />
</role>
<role name="User">
<principal class="com.example.LDAPGroupPrincipal"
name="ApplicationUsers" />
<principal class="com.example.LDAPUserPrincipal"
name="Bob" designated-run-as="true" />
</role>
</role-mappings>
</security>In this example, there is only one realm in use (an LDAP realm). When an unauthenticated user views an unsecured page, they will be treated as the user Anonymous. If they log in they may end up in the Administrator role or the User role. The LDAP user Aaron would be an administrator, while the LDAP user Bob or anyone in the LDAP group ApplicationUsers would be a user. Anyone else would not get any application roles, which means they will not be able to access any secured pages. If a servlet in the web application declares a run-as role of User, then the server will behave as if the user Bob was logged in while that servlet executes.
The gbean element lets you configure additional Geronimo services which will be deployed when the web application is deployed. Normally, the implementation classes for these services are still included at the server level, and referenced using a dependency element (see Section 11.3.1, “Customizing the Web Application Class Path”).
A full description of the syntax for deploying GBeans is covered in Chapter 18, GBeans: Adding New Services to Geronimo [EMPTY]. In general, the gbean element and its attributes define a GBean, and the child elements are used to configure the GBean.
Some situations where you might want to deploy GBeans include:
A security realm that should be deployed with the application (see Section 9.2.1.7, “Generate a Plan for an Application Scoped Realm”)
A database connection pool that should be deployed with the application (see Section 6.3.4, “Generate a Plan for an Application or Client Scoped Pool”)
Clustering features may require GBeans to be included with the web application
Application-specific logic (for example, that should run during startup and shutdown) can be included as a GBean
![[Tip]](images/tip.png) | Tip |
|---|---|
GBeans do not have access to classes included in WEB-INF/lib or WEB-INF/classes. The classes required by a GBean must be accessed from the parent modules or from dependencies declared in this module (see Section 11.3.1, “Customizing the Web Application Class Path”). | |
| |  | |
| 11.2. The Web App Geronimo Deployment Plan |  | 11.4. Web Application Login |
