9 Using The Application Client Container

This chapter provides instructions for using the Oracle application client container as well as basic requirements for developing application clients. The chapter includes the following topics:

Container Overview
Requirements
Developing Application Clients
Starting Application Clients

Users must be familiar with JNDI and RMI when developing application clients and using the application client container. These topics are discussed in their respective chapters within this guide.

Application Client Container Tasks

This chapter discusses the following tasks:

Creating a Main Class
Accessing Resources Using JNDI
Setting JNDI Properties
Using a Deployment Descriptor
Packaging a Client
Implementing a Custom Security Handler
Starting Application Clients

Additional Documentation

The How-To documents on the OC4J site provide additional information about OC4J features, including an EJB example. The example includes an application client that demonstrates the application client container's features.

http://www.oracle.com/technology/tech/java/oc4j/index.html

Container Overview

The application client container is a light-weight J2EE container that, unlike a Web or EJB container, runs on a client computer. The application client container is used to host application components called application clients. Application clients are similar to standalone Java2 SE applications; except, application clients depend on the application client container to provide access to the resources and facilities on a remote J2EE server. From a practical standpoint, the application client container allows developers to create robust standalone Java applications that also have access to J2EE resources such as data sources or EJBs. Figure 9-1 show a conceptual view of the application client container, application client, and remote J2EE resources.

Figure 9-1 Application Client Container Conceptual View

Shows a contextual view of the application client container

The Oracle application client container includes implementations of JNDI and RMI. At run-time, the container uses JNDI to create an initial context factory and RMI to get remote resources that are required by the client.

JNDI Support

The application client container supports the use of JNDI to lookup resources that are hosted on a remote Oracle Application Server. This includes the use of annotations to have resources automatically injected into the application client main class, and the use of the JNDI API to create JNDI lookups. If you are new to JNDI, see Chapter 2 for detailed instructions on using JNDI.

RMI Support

All invocations to remote resources are done through RMI. The application client container supports the use of ORMI, RMI/IIOP, and ORMI tunneling. In addition, ORMI connections through OPMN is also supported. If you are new to RMI see Chapter 6 for detailed instructions on using RMI.

Security Support

Lastly, the application client container supports the use of custom security callback handlers. Custom security callback handlers are used to provide custom ways of getting user credentials.

Requirements

The application container has the following run-time requirements:

JRE 1.4.X or 1.5.X.

The use of annotations for resource injection is only supported when using JRE 1.5. If JRE 1.4 is used, annotation parsing is skipped. Resource Injection (a J2EE 1.5 feature) is only supported in JRE 1.4 when using deployment descriptor tags for resource injection.
OC4J Client-Side Distribution

The OC4J client-side distribution contains all the libraries that are required to run the application client container. The distribution can be obtained from the OC4J download page:

http://www.oracle.com/technology/software/products/ias/htdocs/utilsoft.html

Extract the libraries to a location on your computer. This location is referred to as J2EE_HOME throughout this documentation. During development and testing, it may be more convenient to set J2EE_HOME to the Oracle Application Server's /j2ee/home directory. This location also contains the required libraries.

Developing Application Clients

This section provides basic instructions for developing application clients that are targeted for the application client container. In general, application clients follow the standard constructs of J2SE applications. However, application clients also leverage the J2EE facilities that are provided by the container.

Creating a Main Class

Application clients have a class that is considered the main class. The main class is the entry point for the application client at startup time. This class must have a static main method. The main method is the first method that is invoked after the container is initialized. A simple application client might use:

public class Foo {
   public static void main(String[] args) {
...
   }
}

The application client container uses the application client JAR's Manifest.mf file at startup to find an application client's main class. A class is designated as the main class by defining the Main-Class attribute in the Manifest.mf file. For example:

Main-Class: com.mycompany.MyMainClass

See "Packaging a Client" for instructions on creating an application client JAR.

Accessing Resources Using JNDI

The application client container provides an application client with access to a JNDI service for accessing remote resources. Therefore, getting resources (such as EJBs or data sources) from an application client follows the same JNDI programming model used by other J2EE components. The following sections provide a brief overview of using JNDI. If you are new to JNDI, see Chapter 2 for detailed instructions on using JNDI.

Note:

For a complete example of using JNDI to look up EJB resources from an application client, see "Looking Up Objects from J2EE Application Clients" in Chapter 2. In addition, see "Getting a Connection From a DataSource" in Chapter 5 for information on connecting to a database using data sources that are available in the JNDI naming context.

Using Annotations

The application client's main class can use Java language annotations to request the injection of resources from the naming context, or to declare entries that are needed in the naming context. Annotations are processed as part of the container's initialization procedure. After the container starts and the application client is invoked, annotations can no longer be processed.

The methods and fields in the main class that are annotated must be static. This convention is different than typical J2EE resources where methods and fields requesting injection must not be static. The reason for this difference is that the container does not create an instance of the application client. The application client container loads the main class specified in the application client JAR's manifest, and then invokes the static main method on that class. After this step, the application client runs as would any J2SE application.

The following example demonstrates using the @EJB annotation to get a reference to a remote EJB resource called HelloWorld.

import javax.ejb.EJB;

public class HelloWorldClient {
   @EJB
      private static HelloWorld helloWorld;
      public  static void main(String[] args) {
         // Use the HellOWorld bean.
         ...

Note:

Different application components support different annotation tags. See the individual application component guides (such as the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide) for instructions on using annotations within those components.

Using the JNDI API

Application client classes can make use of the JNDI API to look up resources in the naming context. Unlike annotations, the JNDI lookups can also be processed after the container is initialized. The following example demonstrates using the JNDI API to get the same HelloWorld EJB resource as in the preceding example.

import javax.naming.Context;
import javax.naming.InitialContext;

public class HelloWorldClient {
   public static void main(String[] args) {
   try {
      HelloWorld helloWorld = (HelloWorld) new InitialContext()          .lookup("java:comp/env/ejb/HelloWorld");
      // Use the HelloWorld bean.
      ...

Using a Deployment Descriptor

Application clients can make use of the application client deployment descriptor to declare entries in the naming context and to request injection of the entries. The following examples demonstrates declaring the HelloWorld EJB in the client's deployment descriptor as well as requesting resource injection.

<application-client>   <ejb-ref>      <ejb-ref-name>com.myCompany.HelloWorldClient/helloWorld</ejb-ref-name>
      <remote>com.myCompany.HelloWorld</remote>
      <injection-target>
         <injection-target-class>
            com.myCompany.HelloWorldClient
         </injection-target-class>
         <injection-target-name>helloWorld</injection-target-name>      </injection-target>   </ejb-ref></application-client>

In the example, the HelloWorld bean is being injected for the helloWorld instance in the HelloWorldClient class.

See "Using a Deployment Descriptor" for additional instructions on using the application client's deployment descriptor.

Setting JNDI Properties

JNDI properties are set in the jndi.properties file. The file is required by the container at run-time. The container uses the file to create an initial JNDI context and to define RMI connection settings to access remote resources. This file must be located in the root of the application client JAR.

The following example demonstrates the properties required when accessing an EJB that is hosted in a standalone OC4J server:

java.naming.factory.initial=oracle.j2ee.naming.    ApplicationClientInitialContextFactory
java.naming.provider.url=ormi://<host>:23791/my_ejb>
java.naming.security.principal=scott
java.naming.security.credentials=tiger

The initial factory is always ApplicationClientInitialContextFactory. I n addition, if the resource is located on an Oracle Application Server that uses OPMN, use the opmn:ormi protocol as part of the naming provider URL. For example:

java.naming.provider.url=opmn:ormi://<host>:6003:home/my_ejb

For additional information on using ORMI to connect to remote resources, see "Remote Object Lookup Using RMI/ORMI" . For additional information on using JNDI, see Chapter 2, "Using JNDI".

Using a Deployment Descriptor

The application-client.xml file is the standard J2EE deployment descriptor for an application client and must be located in the META-INF/ directory in the application client JAR. The file is used to define environment entries and references to resources that are required by the application client. However, the file is not required if the client code uses only annotations to perform resource injection.

Note:

Resource references can be defined in an application-client.xml file as well as by use of annotations. In such cases, the deployment descriptor overrides the annotations.

The application-client.xml file uses standard J2EE reference elements (such as env-entry, ejb-ref, resource-ref, and so on.). For more information on the deployment descriptor, see the application client container chapter in the J2EE specification. The chapter provides a complete example of the application-client.xml file and a list of the available elements.

Packaging a Client

Application clients are packaged as a JAR file. The archive can be created with the Java jar utility or by using a similar compression format (such as zip) and changing the extension to .jar.

The contents of the archive file are organized in a standard structure as follows:

/
/jndi.properties
/META-INF
/META-INF/Manifest.mf
/META-INF/application-client.xml

Implementing a Custom Security Handler

The application client container must authenticate with the remote server when creating an initial JNDI context and invoking remote methods. The container uses a default callback handler that uses the username, password, and provider URL that is defined in the JNDI properties file. See "Setting JNDI Properties" for instructions on setting these properties.

An application client can implement a JAAS callback handler to provide custom functionality such as displaying a login screen to get the required credentials. In such scenarios, the container instantiates the callback handler at startup and ignores the settings that are defined in the JNDI properties file. If the callback handler fails, the container defaults back to the JNDI properties file.

To implement a custom security handler:

Create a handler class that implements the javax.security.auth.callback.CallbackHandler interface and has a no arguments constructor.
Add the callback handler to the application client JAR file, or ensure that the handler is found on the CLASSPATH at runtime.

Add a reference to the handler class to the application-client.xml file. For example:

<application-client>
   <callback-handler>
      com.myCompany.MyCallbackHandler
   </callback-handler>
</application-client>

Starting Application Clients

The application client container is responsible for invoking a client at startup. During the startup procedure, the container first creates a JNDI context and then connects to any defined remote servers to get the J2EE resources requested by the client. A client is only started after the container has completed initialization.

Note:

Before starting a client, make sure the requested resources are deployed on the remote server and that the server is started. If the container cannot find the resources on the remote server, the container fails to initialize and the client does not start.

The application client container startup class (oracle.oc4j.appclient.AppClientContainer) is set as the main class of the oc4jclient.jar. To start an application client using the JAR, enter the following command from a command line:

java -jar J2EE_HOME\oc4jclient.jar <aplication_client_jar> <arguments>

The full path to the application client JAR file must be supplied. In addition, any client arguments that are supplied on the command line are passed to the client's main() method at startup and not processed by the container.

The default behavior of the oc4jclient.jar file is to start the container using the CLASSPATH that is defined in its Manifest.mf file. However, if additional libraries or directories are required at startup, use the application client container startup class and the Java -cp option. For example:

java -cp J2EE_HOME\oc4jclient.jar;foo.jar oracle.oc4j.appclient.AppClientContainer <aplication_client_jar> <arguments>

Note:

As with any Java library, application client libraries can include a Class-Path entry in their manifest. This allows external JARs to be added to the application client's classpath and provides fine-grained classpath configuration. However, the JARs will only be available to the application client and not the application client container.