This topic provides the steps required to develop J2EE application
client code.
About this task
A
J2EE
application client program operates similarly to a standard J2EE program
in that it runs its own ASCII Java virtual machine code and is invoked at
its main method. This JVM run-time environment is part of the client container,
which provides the following services for the application client:
- Security
- Communications protocol support (for RMI/IIOP, HTTP, and so on)
- Naming support
The Java Virtual Machine application client program differs from
a standard Java program because it uses the Java Naming and Directory Interface
(JNDI) namespace to access resources. In a standard Java program, the resource
information is coded in the program.
Storing the resource information
separately from the client application program makes the client application
program portable and more flexible.
- Write the client application program. Write the J2EE
application client program on any development machine. At this stage, you
do not require access to the WebSphere Application Server.
Rules: If
you are writing a client application program that will run on z/OS, the following
rules apply:
- Client programs may start their own transactions but cannot join in or
start transactions in the WebSphere Application Server for z/OS run-time.
- Application client code must contain a main method.
- All input and output files for the application client must be in ASCII,
because the client run-time runs in an ASCII JVM.
Using the javax.naming.InitialContext class, the client
application program uses the look-up operation to access the Java Naming and
Directory Interface (JNDI) namespace. The InitialContext class provides
the lookup method to locate resources.
The following example
illustrates how a client application program uses the InitialContext class:
import javax.naming.*
public class myAppClient
{
public static void main(String argv[])
{
InitialContext initCtx = new InitialContext();
Object homeObject = initCtx.lookup("java:comp/env/ejb/BasicCalculator");
BasicCalculatorHome bcHome = (BasicCalculatorHome)
javax.rmi.PortableRemoteObject.narrow(homeObject, BasicCalculatorHome.class);
BasicCalculatorHome bc = bcHome.create(); ...
}
}
In this example, the program looks up an enterprise bean called BasicCalculator.
The BasicCalculator EJB reference is located in the client JNDI namespace
at java:comp/env/ejb/BasicCalculator . Since the actual Enterprise
Java Bean run on the server, the application client run time returns a reference
to the BasicCalculator home interface. If the client application
program lookup was for a resource reference or an environment entry, then
the look up function returns an instance of the configured type as defined
by the client application deployment descriptor. For example, if the program
lookup was a JDBC data source, the lookup would return an instance of javax.sql.DataSource.
Although you can edit deployment descriptor files, do not use the administrative
console to modify them.
- Assemble the application client using an assembly tool.
The JNDI namespace knows
what to return on a lookup because of the information assembled by the assembly
tool.
Assemble the J2EE application client on any development machine
with the assembly tool installed.
When you assemble your application
client, provide the application client run time with the required information
to initialize the execution environment for your client application program.
Refer to documentation for the assembly tool for implementation details.
Remember
following when you configure resources used by your client application program:
- Resource environment references are different than resource references.
Resource environment references allow your application client to use a logical
name to look-up a resource bound into the server JNDI namespace. A resource
reference allows your application to use a logical name to look up a local
J2EE resource. The J2EE specification does not specify a particular implementation
of a resource. The following table contains supported resource types and identifies
the resources to which the WebSphere Application Server provides a client
implementation.
Resource Type |
Client Configuration Notes |
Client implementation provided by WebSphere
Application Server |
javax.sql.DataSource |
Supports specification of any data source
implementation class |
No |
java.net.URL |
Supports specification of custom protocol
handlers |
Provided by Java Runtime Environment files |
javax.mail.Session |
Supports custom protocol configuration |
Yes - POP3, SMTP, IMAP |
javax.jms.QueueConnectionFactory, javax.jms.TopicConnectionFactory,
javax.jms.Queue, javax.jms.Topic |
Supports configuration of WebSphere embedded
messaging, IBM MQ Series and other JMS providers |
Yes - WebSphere embedded messaging |
- Assemble the Enterprise Archive (EAR) file.
The application
is contained in an enterprise archive or .ear file. The .ear file
is composed of:
- Enterprise bean, application client, and user-defined modules or .jar files
- Web applications or .war files
- Metadata describing the applications or application .xml files
You must assemble the .ear file on the server machine.
- Distribute the EAR file.
The client machines configured
to run this client must have access to the .ear file.
If all
the machines in your environment share the same image and platform, run the
Application Client Resource Configuration Tool (ACRCT) on one machine to configure
the external resources, and then distribute the configured .ear file
to the other machines.
If your environment is set up with a variety
of client installations and platforms, run the ACRCT for each unique configuration.
You
can either distribute the .ear files to the correct client machines,
or make them available on a network drive.
Distributing the .ear files
is the responsibility of the system and network administrator.
- Deploy the application
client.
- Configure the
application client resources.
If the client application
defines the local resources, run the ACRCT (clientConfig command)
on the local machine to reconfigure the .ear file. Use the ACRCT
to change the configuration. For example, the .ear file can contain
a DB2 resource, configured as C:\DB2. If, however, you installed
DB2 in the D:\Program Files\DB2 directory, use the ACRCT to create
a local version of the .ear file.
- Deploy the application client.
If
you plan to deploy the client on z/OS, you have two options for running the
Application Client Resource Configuration Tool (ACRCT):
Both of these options produce equivalent output; only the tool interfaces
are different. The ACRCT on Windows presents a graphical user interface, whereas
the ACRCT for z/OS uses a scripting interface.
- Use the WebSphere Administrative console to install
the application client on z/OS.