Client-module deployment

This article explains how to deploy a Client-module to the Orion Application Server.

Introduction
The structure of a Client-module in brief
Connecting to the application
Deploying a standalone Client-module manually
Deployment configuration
Running Application-clients

1 Introduction

This article provides a step-by-step guide to deploying an existing Client-module to an Orion Application Server. It also gives a brief overview of the structure of a Client-module. Information about deploying a full J2EE application can be found in the Application Deployment article.

2 The structure of a Client-module in brief

This section briefly describes the structure of a J2EE Client-module.

A J2EE Client-module is one of the J2EE Module types that are parts of a J2EE Application (others are EJB-modules, Connector-modules and Web-modules).

A Client-module can be contained wihin a J2EE Application, but can also be deployed on its own.

A Client-module consists of classes, optional property files, an Application-client descriptor and a manifest file.

Amongst the classes is the class that is the launch point of the application-client. This class should contain a main method and be stated as the value of the Main-Class attribute of the Client-modules MANIFEST.MF file. Depending on the service the application-client supports, other classes could be home/remote interfaces for EJB beans, helper classes and such like.

The descriptor describes the application-client and contains any references it may use to gain access to server-side resources.

Regardless of if the application-client-module is packaged or not, the file structure should look something like in the following example:

/jndi.properties
/com/acme/foo/client.class
/com/acme/foo/ejb/home.class
/com/acme/foo/ejb/remote.class
/META-INF/application-client.xml
/META-INF/MANIFEST.MF

Listing 1: EJB-module file structure example

The jndi.properties file in the example above is an optional property file holding JNDI properties for the InitialContextFactory to use when connecting the Server to obtain a Context.

As this article is about deploying Client-modules and not about creating them, the structure of application-clients will not be further explored here. Please see the J2EE specification for more information about the application-client structure.

3 Connecting to the application

In order for the application-client to be able to lookup resources on the server it needs to have access to a JNDI context held by a deployed Application on the server.

The applicaton-client reaches the JNDI context by constructing a InitialContext, providing the InitialContext with the full classname of the InitialContextFactory implementation to use for name resolutions on the context it is about to connect to.

The classname of the InitialContextFactory implementation to use is given to the InitialContext either as part of the Properties given to its constructor, as system properties or as properties in a resource-file named jndi.properties.

#Orion JNDI properties
#Wed Jun 11 22:39:22 CEST 2003
java.naming.provider.url=ormi\://127.0.0.1\:23791/forum
java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory

Listing 2: A jndi.properties file generated by Orion during the deployment of a Client-module.

In listing 2 above, notice that the InitialContextFactory implementation to use is given as the value of the java.naming.factory.initial property. The properties are further discussed in the next section.

When a J2EE application containing a Client-module is deployed, Orion will add a jndi.properties file to the deployed client-module's archive.

3.1 InitialContext Properties

Properties are given to the InitialContext either through its constructor, as system properties or as properties in a resource-file named jndi.properties. These properties are then passed on to the InitialContextFactory used.

Apart from the classname of the InitialContextFactory implementation that the InitialContext should use, Both InitialContextFactories take the following parameters:

java.naming.factory.initial
dedicated.connection
java.naming.provider.url
http.tunnel.path
java.naming.security.principal
java.naming.security.credentials

3.1.1 java.naming.factory.initial

Used to specify the IntialContextFactory implementation that the InitialContext should utilize. Orion comes with two implementations:

ApplicationClientInitialContextFactory - This ContextFactory is to be used by application-client-modules. It supports an application-local context where reference names stated in the application-client.xml descriptor can be looked up. This InitialContextFactory requires that the connector-module configuration file is present in the META-INF directory of the Client-module.

RMIInitialContextFactory - This ContextFactory is to be used by stand-alone applications rather than application-clients. It does not support a application-local context (only J2EE modules have an application-local context) but gives access to the global context. A requirement in the EJB 1.1 specification results in the possibility to lookup EJBs with Remote interfaces using their EJB names through the Global Context.

The ApplicationClientInitialContextFactory is primary used by J2EE Client-modules while the RMIInitialContextFactory is primary used by other types of clients.

3.1.2 dedicated.connection

Used to specify if the connection for the context should be dedicated (socket level) or not. Useful if you want to connect to other servers and avoid looking up local object instances first. The default is false.

With dedicated.connection set to true, a new ORMI connection will be opened instead of reusing any existing connections (as when dedicated.connection is set to false). When done, the connection is closed if dedicated.connection is set to true.

3.1.3 java.naming.provider.url

Used to specify The target URL to the Application's context.

{[http:|https:]ormi:|lookup:}//hostname[:port]/[applicationname]

Listing 3: java.naming.provider.url format

As listing 3 above defines, each url (multiple urls can be given by separating them with a comma-sign) is using the ormi protocol. The URL can be prefixed with "http:" or "https:" to enable http(s) tunneling.

ormi is a custom wire protocol for RMI. RMI defines a way to invoke remote methods without being bound to a special wire protocol. The most common wire protocol for RMI is Sun's JRMP, but for performance and other reasons the leading application server vendors make their own wire protocol implementations. For example, WebLogic's custom wire protocol is known as 'T3;' Orion's is called 'ORMI' (for Orion Remote Method Invocation).

ormi://localhost/atm

Listing 4: java.naming.provider.url using ormi

Although the EJB 2.0 spec mandates that the server must support IIOP as one of the wire protocols for interoperability, it is still valid to provide a more optimized vendor specific protocol as well.

lookup is used to connect to a cluster of Servers.

lookup://localhost/atm

Listing 6: java.naming.provider.url using lookup to discover cluster nodes

When connecting, the client will be informed about the locations of the other nodes in the cluster.

http(s) tunneling is enabled by prefixing the URL with "http" or "https:" as explained in the RMI HTTP-tunneling article.

http:ormi://localhost/atm

Listing 7: java.naming.provider.url using ormi tunneled through http

When a number of locations are specified, the built-in failover handling will retry any transactions that failed due to a lost connection on another location than the currently used one.

View this article for information about setting up the Server to be accessible for RMI requests.

3.1.4 http.tunnel.path

Used to specify an alternative RMIHttpTunnelServlet path if the default should not be used. The default is /servlet/rmi (at which location the tunnel servlet should be bound to the target site's web-app).

3.1.5 java.naming.security.principal

Used to specify the username of the user to access as. If no username is given a swing popup will request this information when the InitialContextFactory is first used.

The specified User needs to be part of a Group with the permission to login to the Server over RMI. In order to be able to read from the context, the specified user needs to be part of a Group that is configured to have read access to the context of the Application.

3.1.6 java.naming.security.credentials

Used to specify the password of the user to access as. If no password is given a swing popup will request this information when the InitialContextFactory is first used.

4 Deploying a standalone Client-module manually

If the Client-module to deploy is not part of a J2EE application, the following steps can be followed to add it to the default application shipped with Orion:

Step 1: Add the Client-module to the default Application

4.1 Step 1: Add the Client-module to the default Application

Add an entry like the one given in listing 8 below to the orion-application.xml file of the Server you are deploying to:

<client-module
path="../applications/name.jar"
auto-start="true"
user="admin"
/>

Listing 8: Adding a client entry to /orion/config/application.xml

The syntax of the Client-module tag can be found here.

Replace the value of the path attribute with the path to the Client-module, either to the .jar file or the root directory of an unpackaged Client-module (the directory holding the Client-module's META-INF directory).

Replace the value of the auto-start attribute with either "true" or "false", with "false" being the default and "true" implying that this Client-module should be started in-process when the Server starts up. Notice that running the client in-process requires that the value of the user attribute is a valid user that the Server will run the client as. Step-by-step instructions for auto-starting an application-client is available here

5 Deployment configuration

After a Client-module has been deployed (standalone or as part of a J2EE application), it is possible to modify its deployment configuration by editing the generated orion-application-client.xml file. This file is normally located in the Client-modules directory within the deployment directory of the Application that the Client-module is part of (The default Application when adding standalone Client-modules).

/orion/application-deployments/default/Client-module name/orion-application-client.xml

Listing 9: Location of the deployment configuration file if the Client-module was added to the default Application. Notice that "Client-module name" should be replaced with the actual name of the Client-module (including the .jar suffix if was a packaged archive).

Deployment configurations can be distributed with the Client-module by placing the orion-application-client.xml file within the META-INF directory (next to the application-client.xml file) of the Client-module. The container will then use the distributed deployment configuration file as base when deploying the Client-module for the first time. When re-deploying the Client-module the deployment configuration file of the Client-module's deployment directory will be used as the base.

The settings available for deployment configuration of a Client-module are:

Configuring environment entries
Configuring EJB references
Configuring resource reference mappings

5.1 Configuring environment entries

To override the value of a certain environment entry with a deployment specific value, add an entry like shown in listing 10 below to the Client-module's orion-application-client.xml file.

<orion-application-client>
<env-entry-mapping name="theName">deploymentValue</env-entry-mapping>
</orion-application-client>

Listing 10: Overriding environment entries..

Where the name attribute of the env-entry tag holds the name of the environment entry to override, and the body of the env-entry-mapping tag holds the new value that should be given to the named environment entry.

5.2 Configuring EJB references

An Applicaton-client uses JNDI to lookup EJBs. These JNDI names need to be mapped to an actual JNDI locations of EJBs with home/remote interfaces (local-home/local for Locals) matching the specified home/remote (local-home/local for Locals) interfaces of the ejb-reference. By default, Orion maps the ejb-reference to the first encountered EJB that matches the home/remote (or local-home/local) interfaces specified in the ejb-reference tag. As multiple EJBs might be using the same home/remote (or local-home/local) interfaces, it is sometimes necessary to manually configure the mapping between the ejb-reference and the actual EJB. This is done through entries like the one shown in listing 11 below.

<orion-application-client>
<ejb-ref-mapping location="ejb/thePayroll" name="ejb/myPayroll"/>
</orion-application-client>

Listing 11: Mapping a SessionBeans ejb-reference to the location of an EJB.

Where the value of the name attribute would be the name used by the Application-client to reference the EJB. The value of the location would be the JNDI location of the actual EJB (and match the location value for the EJBs entry in its EJB-mobules orion-ejb-jar.xml file).

...
Context context=new InitialContext();
LocalPayRollHome payroll=(LocalPayRollHome)context.lookup("java:comp/env/ejb/myPayroll");
...

Listing 12: Example of looking up an EJB from an Application-client.

5.3 Configuring resource reference mappings

An Application-client uses JNDI to lookup resources in its context. These JNDI names need to be mapped to an actual resource JNDI location. By default, Orion maps the default resource of the specified type to the resource reference of the EJB. As an example, any DataSource resource references the Application-client has would be mapped to the first configured DataSource available. In order to change this behaviour, add an entry like shown in listing 13 below to the Client-module's orion-application-client.xml file:

<orion-application-client>
<resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS"/>
</orion-application-client>

Listing 13: Mapping an Application-client's resource reference to a resource

Where the value of the location attribute would be the JNDI location of the previously defined resource and maps this to the name specified in the name attribute.

...
Context context=new InitialContext();
DataSource ds=(DataSource)context.lookup("java:comp/env/jdbc/myDS");
...

Listing 14: Example of looking up a DataSource from within an Application-client:

If the resource needs to be looked up from a context other than the default one, such as when using a external third party resource, an entry like the one describe in listing 15 below can be used:

<orion-application-client>
<resource-ref-mapping location="jdbc/HyperSonicDS" name="jdbc/myDS">
<lookup-context location="foreign/resource/location">
<context-attribute name="java.naming.factory.initial" value="classname" />
<context-attribute name="name" value="value" />
</lookup-context>
</resource-ref-mapping>
</orion-application-client>

Listing 15: Specifying the context to use when looking up the resource.

Where the value of the location attribute would be the name used to lookup the resource in the foreign context.

Additional context attributes can be specified by using the context-attribute tag where the name attribute holds the name and the value attribute holds the value for each name-value pair.

Please notice that the context attribute named "java.naming.factory.initial" is an obligatory attribute that should have the context factory class as its value.

6 Running Application-clients

There are multiple ways of executing application-clients. Below are guidelines for the following scenarios:

Using the console
Auto-starting
Using the application-launcher
Out of process

6.1 Using the console

Using the Orion Application Server Console, a Client-module can be launched through the following steps:

Select the Host that the application-client is deployed on from the list of available hosts
Explode the "Applications" node under the selected host
Explode the J2EE application containing the Client-module from the list of available modules under the selected application
Select the Client-module and select "launch(locally)" from the context menu

The application-client should now be launched.

Please remember that the application's output/input is redirected to the same source as the host is using.

Exiting the application-client with a System.exit might bring down the console. If the console is running in-process with your server, this might also take down your server.

6.2 Auto-starting

Configuring an application-client to auto-start will make sure that the Container launches the application-client to be started when the Application is started. In order to perform this service the Container needs to know what user to run the application-client as.

Go through the following steps to set up an application-client to auto-start on Application startup:

Edit the deployment configuration of the Application that the Client-module is part of and enable auto-start as described in this article.
Save the changes.

The next time the application is started the Container will try to invoke the application-client as the specified user.

6.3 Using the application-launcher

The Orion distribution contains a tool named application-launcher (applicationlauncher.jar) that can be used to execute application-clients on local or remote hosts. This tool is very simple to use but requires the Orion distribution to be available.

Go through the following steps to use the application-launcher:

Open a command shell to the installation directory of your Orion application server.
Issue the command:
java -jar applicationlauncher.jar [provider url] [username] [password]
Listing 16: Running the application-launcher
Replace [provider url] with the target URL (this argument is used to pass in the java.naming.provider.url property).

Replace [username] with the name of the user to connect as (this argument is used to pass in the java.naming.security.principal property).

Replace [password] with the password of the user to connect as (this argument is used to pass in the java.naming.security.credentials property).

The application-client should now be started.

6.4 Out of process

The Orion distribution contains a jar file named orionclient.jar. This jar contains the Orion specific classes that the application-client will need to run out of process.

Go through the following steps to run the application-client out of process:

Put the Client-module at the location of choice.
Put the orionclient.jar in the same location.
Optionally put any other required jar files in the same location.
Optionally add a jndi.properties file to the Client-module.
Run the client by using a command such as:
java -jar [Client-module.jar] [application-specific arguments]
Listing 17: Running the application-client out of process
Replace [Client-module.jar] with the name of the Client-module's jar file.

Replace [application-specific arguments] with any arguments required by the application-client's main class.

The application-client should now be started.