5 Developing a Java EE Application Client

A Java EE application client runs on a client machine and can provide a richer user interface than can be provided by a markup language. Application clients directly access enterprise beans running in the business tier, and may, as appropriate, communicate via HTTP with servlets running in the Web tier. An application client is typically downloaded from the server, but can be installed on a client machine.

The following sections provide information on developing Java EE clients:

Overview of the Java EE Application Client

Although a Java EE application client (thin client) is a Java application, it differs from a stand-alone Java application client because it is a Java EE component, hence it offers the advantages of portability to other Java EE-compliant servers, and can access Java EE services.

Oracle provides the following application client JAR files:

  • A standard client JAR (wlclient.jar) that provides Java EE functionality. See How to Develop a Thin Client.

  • A JMS client JAR (wljmsclient.jar), which when deployed with the wlclient.jar, provides Java EE and WebLogic JMS functionality. See Chapter 6, "WebLogic JMS Thin Client."

  • A JMS SAF client JAR (wlsafclient.jar), which when deployed with the wljmsclient.jar and wlclient.jar enables stand-alone JMS clients to reliably send messages to server-side JMS destinations, even when a destination is temporarily unreachable. Sent messages are stored locally on the client and are forwarded to the destination when it becomes available. See Chapter 7, "Reliably Sending Messages Using the JMS SAF Client."

These application client JAR files reside in the WL_HOME/server/lib subdirectory of the WebLogic Server installation directory.

The thin client uses the RMI-IIOP protocol stack and leverages features of J2SE. It also requires the support of the JDK ORB. The basics of making RMI requests are handled by the JDK, which makes possible a significantly smaller client. Client-side development is performed using standard Java EE APIs, rather than WebLogic Server APIs.

The development process for a thin client application is the same as it is for other Java EE applications. The client can leverage standard Java EE artifacts such as InitialContext, UserTransaction, and EJBs. The WebLogic Server thin client supports these values in the protocol portion of the URL—IIOP, IIOPS, HTTP, HTTPS, T3, and T3S—each of which can be selected by using a different URL in InitialContext. Regardless of the URL, IIOP is used. URLs with T3 or T3S use IIOP and IIOPS respectively. HTTP is tunnelled IIOP, HTTPS is IIOP tunnelled over HTTPS.

Server-side components are deployed in the usual fashion. Client stubs can be generated at either deployment time or run time.To generate stubs when deploying, run appc with the -iiop and -basicClientJar options to produce a client jar suitable for use with the thin client. Otherwise, WebLogic Server generates stubs on demand at run time and serves them to the client. Downloading of stubs by the client requires that a suitable security manager be installed. The thin client provides a default light-weight security manager. For rigorous security requirements, a different security manager can be installed with the command line options -Djava.security.manager, -Djava.security.policy==policyfile. Applets use a different security manager which already allows the downloading of stubs.

When deploying a Java EE application client, the wlclient.jar file must be installed on the client's file system and a reference to the wlclient.jar file included on the client's CLASSPATH.

Limitations

The following limitations apply to the Java EE thin client:

  • It does not provide the JDBC or JMX functionality of the wlfullclient.jar file.

  • The WebLogic Server CMP 2.x extension that allows users to return a java.sql.ResultSet to a client is not supported

  • It is only supported by the JDK ORB.

How to Develop a Thin Client

To develop a thin client:

  1. Define your remote object's public methods in an interface that extends java.rmi.Remote.

    This remote interface may not require much code. All you need are the method signatures for methods you want to implement in remote classes. For example:

    public interface Pinger extends java.rmi.Remote {
    public void ping() throws java.rmi.RemoteException;
    public void pingRemote() throws java.rmi.RemoteException;
    
  2. Implement the interface in a class named interfaceNameImpl and bind it into the JNDI tree to be made available to clients.

    This class should implement the remote interface that you wrote, which means that you implement the method signatures that are contained in the interface. All the code generation that will take place is dependent on this class file. Typically, you configure your implementation class as a WebLogic startup class and include a main method that binds the object into the JNDI tree. Here is an excerpt from the implementation class developed from the previous Ping example:

    public static void main(String args[]) throws Exception {
      if (args.length > 0)
      remoteDomain = args[0];
      Pinger obj = new PingImpl();
      Context initialNamingContext = new InitialContext();
      initialNamingContext.rebind(NAME,obj);
      System.out.println("PingImpl created and bound to "+ NAME);
    }
    
  3. Compile the remote interface and implementation class with a java compiler. Developing these classes in an RMI-IIOP application is no different from doing so in normal RMI. For more information on developing RMI objects, see Programming RMI for Oracle WebLogic Server.

  4. Run the WebLogic RMI or EJB compiler against the implementation class to generate the necessary IIOP stub. If you plan on downloading stubs, it is not necessary to run rmic.

    $ java weblogic.rmic -iiop nameOfImplementationClass
    

    To generate stubs when deploying, run appc with the -iiop and -clientJar options to produce a client JAR suitable for use with the thin client. Otherwise, WebLogic Server will generate stubs on demand at run time and serve them to the client.

    A stub is the client-side proxy for a remote object that forwards each WebLogic RMI call to its matching server-side skeleton, which in turn forwards the call to the actual remote object implementation.

  5. Make sure that the files you have created—the remote interface, the class that implements it, and the stub—are in the CLASSPATH of WebLogic Server.

  6. Obtain an initial context.

    RMI clients access remote objects by creating an initial context and performing a lookup (see next step) on the object. The object is then cast to the appropriate type.

    In obtaining an initial context, you must use weblogic.jndi.WLInitialContextFactory when defining your JNDI context factory. Use this class when setting the value for the Context.INITIAL_CONTEXT_FACTORY property that you supply as a parameter to new InitialContext().

    Modify the client code to perform the lookup in conjunction with the javax.rmi.PortableRemoteObject.narrow() method.

    RMI over IIOP RMI clients differ from regular RMI clients in that IIOP is defined as the protocol when obtaining an initial context. Because of this, lookups and casts must be performed in conjunction with the javax.rmi.PortableRemoteObject.narrow() method. For example, an RMI client creates an initial context, performs a lookup on the EJBean home, obtains a reference to an EJBean, and calls methods on the EJBean.

    You must use the javax.rmi.PortableRemoteObject.narrow() method in any situation where you would normally cast an object to a specific class type. A CORBA client may return an object that does not implement your remote interface; the narrow method is provided by your ORB to convert the object so that it implements your remote interface. For example, the client code responsible for looking up the EJBean home and casting the result to the Home object must be modified to use the javax.rmi.PortableRemoteObject.narrow() as shown below:

    Example 5-1 Performing a lookup:

    .
    .
    .
    /**
     * RMI/IIOP clients should use this narrow function
     */
    private Object narrow(Object ref, Class c) {
      return PortableRemoteObject.narrow(ref, c);
    }
    /**
     * Lookup the EJBs home in the JNDI tree
     */
    private TraderHome lookupHome()
      throws NamingException
    {
      // Lookup the beans home using JNDI
      Context ctx = getInitialContext();
      try {
    Object home = ctx.lookup(JNDI_NAME);
    return (TraderHome) narrow(home, TraderHome.class);
    } catch (NamingException ne) {
    log("The client was unable to lookup the EJBHome.  Please
    make sure ");
    log("that you have deployed the ejb with the JNDI name 
    "+JNDI_NAME+" on the WebLogic server at "+url);
    throw ne;
      }
    }
    /**
     * Using a Properties object will work on JDK130
     * and higher clients
     */
    private Context getInitialContext() throws NamingException {
      try {
    // Get an InitialContext
    Properties h = new Properties();
    h.put(Context.INITIAL_CONTEXT_FACTORY,
    "weblogic.jndi.WLInitialContextFactory");
    h.put(Context.PROVIDER_URL, url);
    return new InitialContext(h);
      } catch (NamingException ne) {
    log("We were unable to get a connection to the WebLogic
    server at "+url);
    log("Please make sure that the server is running.");
    throw ne;
      }
    }
    .
    .
    .
    

    The url defines the protocol, hostname, and listen port for the WebLogic Server instance and is passed in as a command-line argument.

    public static void main(String[] args) throws Exception {
      log("\nBeginning statelessSession.Client...\n");
      String url = "iiop://localhost:7001";
    
  7. Connect the client to the server over IIOP by running the client with a command such as:

    $ java -Djava.security.manager -Djava.security.policy=java.policy    examples.iiop.ejb.stateless.rmiclient.Client iiop://localhost:7001
    

Using Java EE Client Application Modules

Java EE specifies a standard for including client application code (a client module) in an EAR file. This allows the client side of an application to be packaged along with the other modules that make up the application.

The client module is declared in the META-INF/application.xml file of the EAR using a <java> tag. See "Enterprise Application Deployment Descriptor Elements" in Developing Applications for Oracle WebLogic Server.

Note:

The <java> tag is often confused to be a declaration of Java code that can be used by the server-side modules. This is not its purpose, it is used to declare client-side code that runs outside of the server-side container.

A client module is basically a JAR file containing a special deployment descriptor named META-INF/application-client.xml. This client JAR file also contains a Main-Class entry in its META-INF/MANIFEST.MF file to specify the entry point for the program. For more information on the application-client.xml file, see Appendix A, "Client Application Deployment Descriptor Elements."

Extracting a Client Application

WebLogic Server includes two utilities that facilitate the use of client modules. They are:

  • weblogic.ClientDeployer—Extracts the client module from the EAR and prepares it for execution.

  • weblogic.j2eeclient.Main—Executes the client code.

You use the weblogic.ClientDeployer utility to extract the client-side JAR file from a Java EE EAR file, creating a deployable JAR file. Execute the weblogic.ClientDeployer class on the Java command line using the following syntax:

java weblogic.ClientDeployer ear-file client1 [client2 client3 ...]

The ear-file argument is a Java archive file with an .ear extension or an expanded directory that contains one or more client application JAR files.

The client arguments specify the clients you want to extract. For each client you name, the weblogic.ClientDeployer utility searches for a JAR file within the EAR file that has the specified name containing the .jar extension.

For example, consider the following command:

java weblogic.ClientDeployer app.ear myclient

This command extracts myclient.jar from app.ear. As it extracts, the weblogic.ClientDeployer utility performs two other operations.

  • It ensures that the JAR file includes a META-INF/application-client.xml file. If it does not, an exception is thrown.

  • It reads from a file named myclient.runtime.xml and creates a weblogic-application-client.xml file in the extracted JAR file. This is used by the weblogic.j2eeclient.Main utility to initialize the client application's component environment (java:comp/env). For information on the format of the runtime.xml file, see Client Application Deployment Descriptor Elements.

Note:

You create the <client>.runtime.xml descriptor for the client program to define bindings for entries in the module's META-INF/application-client.xml deployment descriptor.

Executing a Client Application

Once the client-side JAR file is extracted from the EAR file, use the weblogic.j2eeclient.Main utility to bootstrap the client-side application and point it to a WebLogic Server instance using the following command:

java weblogic.j2eeclient.Main clientjar URL [application args]

For example:

java weblogic.j2eeclient.Main myclient.jar t3://localhost:7001

The weblogic.j2eeclient.Main utility creates a component environment that is accessible from java:comp/env in the client code.

If a resource mentioned by the application-client.xml descriptor is one of the following types, the weblogic.j2eeclient.Main class attempts to bind it from the global JNDI tree on the server to java:comp/env using the information specified earlier in the myclient.runtime.xml file.

  • ejb-ref

  • javax.jms.QueueConnectionFactory

  • javax.jms.TopicConnectionFactory

  • javax.mail.Session

  • javax.sql.DataSource

The user transaction is bound into java:comp/UserTransaction.

The <res-auth> tag in the application.xml deployment descriptor is currently ignored and should be entered as application. Oracle does not currently support form-based authentication.

The rest of the client environment is bound from the weblogic-application-client.xml file created by the weblogic.ClientDeployer utility.

The weblogic.j2eeclient.Main class emits error messages for missing or incomplete bindings.

Once the environment is initialized, the weblogic.j2eeclient.Main utility searches the JAR manifest of the client JAR for a Main-Class entry. The main method on this class is invoked to start the client program. Any arguments passed to the weblogic.j2eeclient.Main utility after the URL argument is passed on to the client application.

The client JVM must be able to locate the Java classes you create for your application and any Java classes your application depends upon, including WebLogic Server classes. You stage a client application by copying all of the required files on the client into a directory and bundling the directory in a JAR file. The top level of the client application directory can have a batch file or script to start the application. Create a classes/ subdirectory to hold Java classes and JAR files, and add them to the client Class-Path in the startup script.

You may also want to package a Java Runtime Environment (JRE) with a Java client application.

Note:

The use of the Class-Path manifest entries in client module JARs is not portable, as it has not yet been addressed by the Java EE standard.

Protocol Compatibility

For information on interoperability between WebLogic Server 11g Release 1 (10.3.1) and previous WebLogic Server releases, see "WebLogic Server Compatibility" in Information Roadmap for Oracle WebLogic Server .