| 14.2. J2EE Application Clients | ||
|---|---|---|
 | Chapter 14. Client Applications (Client JARs) [IN PROGRESS] |  |
| 14.2. J2EE Application Clients | ||
|---|---|---|
| | Chapter 14. Client Applications (Client JARs) [IN PROGRESS] | |
A J2EE application client has several advantages over a J2SE client, as a result of running in a client container:
It has access to a component-local java:comp/env/ JNDI space like other j2EE components. That means that EJBs and other resources can be declared and placed in that JNDI space, and then resolved to actual server resources using a deployment descriptor.
While normally only EJBs can be accessed remotely, the client container can handle remote access to J2EE connectors, meaning database connection pools and JMS resources are available to the application, as well as any third-party connectors.
The container can handle the server login process, providing secure access to the server without requiring specific application security code.
Generally speaking, these advantages mean that a J2EE Application Client is more portable than a J2SE client, since server-specific security and resource access code can be eliminated in favor of configuration in the deployment plan. However, this does mean that every application client requires a standard J2EE deployment descriptor (META-INF/application-client.xml), and most likely a Geronimo deployment plan.
Th rest of this section describes writing a J2EE application client, running a J2EE application client in the Geronimo client container, and the Geronimo deployment plan format in detail.
Geronimo doesn't have any special requirements for application client files -- any application client produced according to the standard process should work in Geronimo. However, there are a couple points to note:
Geronimo requires that every client JAR file has a standard META-INF/application-client.xml deployment descriptor. This may be for J2EE 1.2, J2EE 1.3, or J2EE 1.4, and should follow the appropriate XML format (see below).
If the client JAR file is included in an application EAR, then Geronimo will respect Class-Path entries in the META-INF/MANIFEST.MF file of the client JAR. Any JARs referenced there should also be packaged within the EAR, and paths to JAR files will be resolved relative to the position of the client JAR file in the EAR. If the client JAR file is not included in an EAR, then manifest class path entries will be ignored. In either case, external libraries can also be placed in the Geronimo server repository and referenced with dependency elements in the Geronimo deployment plan (see Section 12.3.1, “Customizing the Class Path”).
The application client should have a class with a method public static void main(String args[]) just like a traditional client. The client JAR should have a Manifest file with a Main-Class entry pointing to the class with the main method (in other words, it should be a standard executable JAR). A typical Manifest file might look like this:
Manifest-Version: 1.0 Main-Class: com.something.MainClient
Then the client JAR can be created including this manifest with a command like this:
jar -cmf ManifestFile OutputFile [files to include...]
Geronimo expects the META-INF/application-client.xml file to obey one of the following standard formats:
Defined by the DTD at http://java.sun.com/j2ee/dtds/application-client_1_2.dtd,an application client deployment descriptor for J2EE 1.2 looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application-client PUBLIC
"-//Sun Microsystems, Inc.//DTD J2EE Application Client 1.2//EN"
"http://java.sun.com/j2ee/dtds/application-client_1_2.dtd">
<application-client>
...
</application-client>Defined by the DTD at http://java.sun.com/dtd/application-client_1_3.dtd, an application client deployment descriptor for J2EE 1.3 looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application-client PUBLIC
"-//Sun Microsystems, Inc.//DTD J2EE Application Client 1.3//EN"
"http://java.sun.com/dtd/application-client_1_3.dtd">
<application-client>
...
</application-client>Defined by the XML schema at http://java.sun.com/xml/ns/j2ee/application-client_1_4.xsd, an application client deployment descriptor for J2EE 1.4 looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<application-client 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-client_1_4.xsd"
version="1.4">
...
</application-client>As of Milestone 4, the client container must run from the same Geronimo installation as the server, which also means that it must be run on the same machine, using the bin/client.jar file in the server's Geronimo directory. The command line to start a J2EE application client looks like this:
java -jar bin/client.jar ConfigName [arg1] [arg2] [arg3] ...
The first argument should match the clientConfigId specified for the client in the Geronimo deployment plan (described in the next section). That basically tells the client container which application client to start.
The rest of the arguments (if any) will be passed to the main method of the main application client class.
The geronimo-application-client.xml Geronimo deployment plan for an application client JAR is an XML document. It is defined by the geronimo-application-client.xsd schema, which can be found in the schema/ subdirectory of the main Geronimo installation directory. The deployment plan for a client JAR may be:
Included in the client JAR, in which case it should be named META-INF/geronimo-application-client.xml
Included in an EAR (but outside of the client JAR) and referenced by an alt-dd element of the EAR deployment plan (see Section 15.3.2, “Configuring Application Modules”).
Saved as a separate file and provided to the deploy tool when the client JAR module is deployed (though this doesn't work when the client JAR is in an EAR).
Created from scratch using a JSR-88 configuration tool, in which case the tool manages saving and loading the deployment plan and passing it to the server when the client JAR is deployed. For more information on JSR-88 tools see Section 10.6, “JSR-88 Configuration & Deployment Tools”.
The deployment plan should always use the Geronimo client namespace, and it typically requires elements from the Geronimo Naming, Geronimo Security, and Geronimo System namespaces. Additionally, it has a required attribute to identify its configuration name, and an optional attribute to select a parent configuration. A typical client deployment plan looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<application-client
xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-client"
xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
xmlns:security="http://geronimo.apache.org/xml/ns/security"
xmlns:sys="http://geronimo.apache.org/xml/ns/deployment"
configId="MyClientConfiguration"
clientConfigId="MyClient"
parentId="geronimo/j2ee-server/1.0/car"
clientParentId="geronimo/client/1.0/car">
...
</application-client>In contrast to other Geronimo deployment plans, the application client has a Config ID and Parent ID for both the server-side client configuration and the client-side client configuration. The configId and parentId elements apply to the server's environment, so when that configuration is running, its dependencies may force other resources to be available in the server environment. The clientConfigId and clientParentId apply to the client container environment, so the clientConfigId will be used to start the client and the clientParentId is not typically very useful.
In any case, a full description of the attributes here is:
The main namespace for the deployment plan, which should always be http://geronimo.apache.org/xml/ns/j2ee/application-client
A secondary namespace, used to identify the common elements for resolving EJB references, resource references, and web services references. If any of those need to be resolved in the deployment plan, this attribute must be present, and should be set to http://geronimo.apache.org/xml/ns/naming
A secondary namespace, used to identify the common elements for security configuration. If there are any security settings in the deployment plan, this attribute must be present, and should be set to http://geronimo.apache.org/xml/ns/security
A secondary namespace, used to identify the common elements for common libraries and module-scoped services. If there are any of those present in the deployment plan, this attribute must be present, and should be set to http://geronimo.apache.org/xml/ns/deployment
A unique name identifying this module on the server side. If deployed as a standalone client JAR, this name is used to identify the module to the deployment tool. It can be used to start or stop the server-side module (any dependencies are only forced to be running while this module is running), as well as to undeploy or redeploy the client JAR as a whole.
Identifies the parent configuration for the server-side module (the value specified here should match the configId for the parent module). If deployed as a standalone client JAR, this can be used to make the client JAR depend on another module such as a database pool or JMS configuration (or it should otherwise be set to the usual parent for J2EE modules, geronimo/j2ee-server/1.0/car). If deployed as part of an EAR this is usually not necessary, as EAR configuration will be the parent of this module, and it will inherit dependencies from the EAR. In any case, this only controls dependencies that must be running on the server side; it does not actually change the ClassPath of the application client itself.
A unique name identifying the client-side application module. This name is used to identify the module to the client container (to run the application client). This name should not be used with the normal deploy tool, only the client container.
Identifies the parent configuration for the client-side applciation module (the value specified here should match the configId for that module). This should normally be omitted or set to the usual parent for clients, geronimo/client/1.0/car.
The deployment plan for application clients usually contains:
Class path customization for the application client.
Security settings indicating what the default user should be, if no login information was provided in the standard application-client.xml file (using the callback-handler element).
Details to resolve EJB references, resource references, and web services references declared by the client in the application-client.xml deployment descriptor. This isn't always necessary for EJB references (which may be resolved using an ejb-link in the application-client.xml) but generally is for the other types of references.
For the simplest application clients these settings may not be required or the defaults may be sufficient, but in most cases the Geronimo application client deployment plan will need a substantial amount of information.
The ejb-ref element lets you map EJB references to specific EJBs.
Since the EJBs are usually in a different JVM, be aware that the current application would need to include the EJB client interfaces for the remote EJBs.
The ejb-ref element is used to connect to an EJB through its remote home and remote interfaces.
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-ref elements 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 client module.
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 client modules.
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 client module.
The elements used to map a resource environment reference are:
The gbean element lets you configure additional Geronimo services which will be deployed when client is run. Normally, the implementation classes for these services are still included at the server level, and referenced using a dependency element (see Section 14.2.4.2, “Adding Common Libraries to the ClassPath”).
The specific 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.
| |  | |
| Chapter 14. Client Applications (Client JARs) [IN PROGRESS] |  | 14.3. J2SE Application Clients |
