| 15.3. Structure of the Deployment Plan | ||
|---|---|---|
 | Chapter 15. Enterprise Applications (EARs) [DRAFT (1.0)] |  |
| 15.3. Structure of the Deployment Plan | ||
|---|---|---|
| | Chapter 15. Enterprise Applications (EARs) [DRAFT (1.0)] | |
The internal structure of the enterprise 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 15.1, “Enterprise Application Deployment Plan Overview”, and that's the order the elements are discussed in below. Of these elements, only the header (discussed above) is required.
The elements in the classloader-infoGroup are used to customized the application's class path. Any additions to the application class path will be visible to all modules within the application -- EJBs, J2EE Connectors, and Web Applications.
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 application will add the class loader for that configuration as a parent. Additionally, the parent configuration will be started before the application is started.
Adds a third-party library to the class path for the 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 application. This is typically used when the 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 application wanted to use a newer version, it could include the newer version 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 application should always load from a parent class loader, and never load from its own class path.
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 be a path to the dependency JAR, relative to the repository/ directory of the Geronimo installation. For example, specifying regexp/jars/regexp-1.3.jar would select the JAR geronimo/repository/regexp/jars/regexp-1.3.jar. If there is no such JAR available, the application 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 15.1. Enterprise 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. An 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>
The J2EE deployment descriptor (META-INF/application.xml) lists the modules in the application and gives some basic options for each, including:
A context root for web application modules
The ability to store the J2EE deployment descriptors for each module in the EAR (instead of packaged within each module)
The Geronimo deployment plan provides two different options for overriding the usual packaging of the module-level Geronimo deployment plans within the modules:
The deployment plan for a module can be stored in the EAR
The deployment plan for a module can be embedded in the deployment plan for the application
The structure of the module elements looks like this:
Each module entry must have one of the following elements to identify the module:
Holds the location of a J2EE Connector module. Must match the same element in application.xml
Holds the location of an EJB module. Must match the same element in application.xml
Holds the location of an application client module. Must match the same element in application.xml
Holds the location of a web application module. Must match the web-uri in application.xml
There are two possibilities for identifying the deployment plan of the module:
Specifies a location inside the EAR where the Geronimo deployment plan for this module can be found. Note that the alt-dd element in application.xml specifies an alternate location for the module's J2EE deployment descriptor, whereas the alt-dd here specifies an alternate location for the module's Geronimo deployment plan.
The module's entire Geronimo deployment plan may be embedded in the EAR deployment plan at this location. It should use the same elements and namespaces as normal. Note that this is commonly used by JSR-88 deployment tools (which must save a single deployment plan for the application and all its modules), but is used less frequently for handcrafted deployment plans.
Example 15.2. Enterprise Application: Module Configuration Example
If the J2EE deployment descriptor defined two modules like this:
META-INF/application.xml
<application
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/application_1_4.xsd"
version="1.4">
<module>
<ejb>example-ejbs.jar</ejb>
<alt-dd>dds/my-ejb-jar.xml</alt-dd>
</module>
<module>
<web>
<web-uri>example-web.war</web-uri>
<context-root>example</context-root>
</web>
</module>
</application>Then the Geronimo deployment plan could include separate deployment plans for both modules like this:
META-INF/geronimo-application.xml
<application
xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.0"
configId="MyConfigName"
parentId="ParentConfigName">
<module>
<ejb>example-ejbs.jar</ejb>
<alt-dd>dds/my-ejb-geronimo-plan.xml</alt-dd>
</module>
<module>
<web>example-web.war</web>
<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>
</web-app>
</module>
</application>In this case, the EJB deployment plan is stored inside the EAR (in a directory called dds/ that also holds a replacement for ejb-jar.xml for that module). The Web application deployment plan is actually right there inside the EAR deployment plan, in its entirety.
In addition to configuring modules listed in application.xml, the Geronimo plan can add references to new modules, either in the EAR or located in the Geronimo repository. The ext-module element is used for this:
The elements here are:
Same as described previously; these identify the module (though they don't need to match anything in application.xml in this case).
The internal path indicates that the module is packaged in the EAR, and a path specified here is relative to the root of the EAR.
The external path indicates that the module is located in the Geronimo repository. In fact, the value specified here is not a path at all, but is a URI formatted according to the standard repository URI syntax (e.g. tranql/tranql-connector/1.1/rar).
If the Geronimo deployment plan for the module is not packaged in the module, it must be included here.
In many cases, multiple modules within the same application will use the same security roles (for example, a web application that talks to EJBs in an EJB JAR). In that case, it's possible to provide the security role mapping information once at the application level, instead of separately for the web application and EJB JAR. To do this, first list the relevant security roles in application.xml and then use the following block in geronimo-application.xml:
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:
Groups the security role mapping settings for the application.
May be true or false. If set to true, any work done by the 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 enterprise applications.
Holds a principal which will be used any time no security applies (for example, when an unauthenticated user accesses an unsecured page in a web application). Normally this would result in no principal being used, but you can specify a default here. This would, for example, allow an insecure web page to access a secured EJB. This element is described in more detail below.
Holds the information mapping roles declared in the application.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 application.xml. This is described in more detail below.
The default-principal element looks like this:
Holds the default principal to be used when no normal authentication applies.
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 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-mapping element looks like this:
The elements used here are:
Holds the set of principals that map to a single role from application.xml.
The name used to identify this role. Must match a role-name specified in application.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 component has a run-as role set (e.g. a servlet with a run-as role in web.xml or an EJB with a run-as role in ejb-jar.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 component has a run-as role set (in its J2EE deployment descriptor). 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 enterprise application deployment descriptor, using simple mapping:
Example 15.3. Enterprise 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 web page within this application, 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 resources. If a servlet or EJB in the application declares a run-as role of User, then the server will behave as if the user Bob was logged in while that component executes.
The gbean element lets you configure additional Geronimo services which will be deployed when the application is deployed (and stopped when the application is stopped). Normally, the implementation classes for these services are still included at the server level, and referenced using a dependency element (see Section 15.3.1, “Customizing the 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”)
Application-specific logic (for example, that should run during startup and shutdown) can be included as a GBean
| |  | |
| 15.2. The Enterprise Application Geronimo Deployment Plan |  | Chapter 16. Web Services [DRAFT(1.0)] |
