Developing J2EE application client code

Why and when to perform 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:

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.

Steps for this task

  1. 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.

  2. .

    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.

    Remember following when you configure resources used by your client application program:

    • [5.0 only][Version 5.0.1][Version 5.0.2]When configuring resource references, resource environment references, and EJB references in the Application Assembly Tool, the General tab contains a required Name field. This field specifies where the application client run time binds the reference to the real object in the java:comp/env portion of the JNDI namespace. The application client run time always binds these references relative to java:comp/env. For the previous programming example, specify ejb/BasicCalculator in the Name field on the General tab of the Application Assembly Tool, which requires the program to perform a look up of java:comp/env/ejb/BasicCalculator. If the Name field is set to myString, the resulting look up is java:comp/env/myString.
    • [5.0 only][Version 5.0.1][Version 5.0.2]When configuring Resource references in the Application Assembly Tool, the Name field on the General tab is used for:
      • [5.0 only][Version 5.0.1][Version 5.0.2]Binding a reference of that object type into the JNDI namespace.
      • [5.0 only][Version 5.0.1][Version 5.0.2]Retrieving client specific resource configuration information that was configured using the Application Client Resource Configuration Tool(ACRCT) on Windows, or the ACRCT scripting tool on z/OS.
    • [5.0 only][Version 5.0.1][Version 5.0.2]When configuring a resource reference in the Application Assembly Tool, the value in the Name field on the General tab must match the value in the JNDI Name field on the General tab for the resource in the Application Client Resource Configuration Tool.
    • [5.0 only][Version 5.0.1][Version 5.0.2]When configuring URL resources using the Application Client Resource Configuration Tool (ACRCT), the URL provider panel enables you to specify a protocol and a class to handle that protocol. If you want to use the default protocols, such as HTTP, you can leave those fields blank.
    • [5.0 only][Version 5.0.1][Version 5.0.2]When configuring resource references using the Application Assembly Tool, the General tab contains an Authorization field. You can set this field to either Container or Application. If you set the field to Container, then the application client run time uses authorization information configured in the Application Client Resource Configuration tool for the resource. If the field is set to Application, then the application client run time expects the user application to provide authorization information for the resource. The application client run time ignores any authorization information configured with the Application Client Resource Configuration Tool (ACRCT) for that resource.
    • [5.0 only][Version 5.0.1][Version 5.0.2]When configuring resource environment references using the Application Assembly Tool, you must specify the location of the actual object in the server JNDI namespace using the Binding tab. A resource environment reference maps a logical name (the Name field on the General tab) used by the client application to the physical name of an object (the JNDI Name field on the Bindings tab). Not all objects bound into the server JNDI namespace are intended for use by an application client. For example, the WebSphere Application Server client run time does not support the use of Java 2 Connector (J2C) objects on the client. The object needs the ability to be remote, and the client-side implementations must be made available on the application client run-time class path.
    • 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


  3. 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.

  4. Distribute the EAR file.

    The client machines configured to run this client must have access to the .ear file.

    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.

  5. Deploy the application client.

    If you plan to deploy the client on z/OS or OS/390, 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.

  6. Use the WebSphere Administrative console to install the application client on z/OS or OS/390.

What to do next

After completing these steps, launch the application client.

Related concepts
J2EE application client class loading



Searchable topic ID:   tcli_developjava
Last updated: Jun 21, 2007 9:56:50 PM CDT    WebSphere Application Server for z/OS, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.zseries.doc/info/zseries/ae/tcli_developjava.html

Library | Support | Terms of Use | Feedback