Skip Headers
Oracle® Fusion Middleware Programming Stand-alone Clients for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24378-05
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

5 Developing a Thin Client

This chapter describes how to develop and use a WebLogic thin client:

Overview of the Thin Client

Although a 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:

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 Java SE. 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 thin 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 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
    

Protocol Compatibility

For information on interoperability between this WebLogic Server release and previous WebLogic Server releases, see "WebLogic Server Compatibility" in Understanding Oracle WebLogic Server.