BEA Logo BEA WebLogic Server Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

Using WebLogic Remote

I. Introduction
Overview of WebLogic Remote
WebLogic Remote architecture

II. The API
WebLogic Remote API reference
Overview of the WebLogic Remote API
Designing a T3Servlet
Executing a T3Servlet
Setting parameters for T3Servlets

III. Implementing with WebLogic Remote

Other related documents
Installing WebLogic (non-Windows)
Installing WebLogic (Windows)
Developers Guides
API Reference Manual
Using WebLogic HTTP Servlets
Glossary


Note: WebLogic Remote has been deprecated and will be removed in a future version. You should use our Enterprise JavaBean implementation instead.

I. Introduction

Overview of WebLogic Remote

WebLogic Remote services offer the simplest distributed object services, T3Servlets, that operate within WebLogic. A WebLogic Remote T3Servlet is a very simple concept -- remote procedure calls -- translated into 100% Java, to allow you to offload client processing to the WebLogic Server. For example, if you have routine procedures that are compute-intensive or privacy-sensitive -- processing that you do not really want to do in the client application -- you can write a T3Servlet, set its parameters in the client, and then execute it, with return values returned to the client.

WebLogic Remote has access to all of the WebLogic facilities (like logging, instrumentation, and Workspaces), and like other WebLogic component-based services, are an integrated part of WebLogic. The APIs for all of WebLogic's services and facilities share many common aspects that make building a complex networked application easier; your application may use several services, all of which can share access to objects and client resources. WebLogic Remote offers another design choice, along with WebLogic RMI and WebLogic Beans, for building distributed applications in WebLogic.

This document covers aspects specific to writing applications with the WebLogic T3Servlet API. You should also read the Developers Guide that covers all the services and facilities within the WebLogic framework, Writing a WebLogic client application.

What are T3Servlets?

WebLogic Remote allows you to write Java classes that are stored on a WebLogic Server and can be invoked remotely by a T3Client -- a very simple, very useful form of remote procedure calls (RPC) for Java. With a T3Servlet, you can offload any task from your T3Client to a WebLogic Server.

In generic terms, a class that can be invoked and executed remotely is called a servlet. Another way of phrasing what servlets do is "server-side Java."

The most common definition of a "servlet" is a server-side process that is invoked by an HTTP client. WebLogic also supports the JavaSoft standard HTTP-to-Java servlets with its built-in webserver. WebLogic HTTP Servlets operate in an HTTP-to-Java relationship, in which a browser client invokes a Java class on the server by entering a URL. An HTTP server interprets this request and executes a class file that is in its Java CLASSPATH. We call the generic HTTP-to-Java servlet that conforms to the Java Servlet API "HTTP Servlets." You can read more about writing HTTP servlets in the Developers Guide, Using WebLogic HTTP Servlets.

T3Servlets, however, are server-side Java that operates in a Java-to-Java relationship. The primary difference between HTTP Servlets and T3Servlets is that a Java Servlet API servlet communicates with the WebLogic Server via HTTP, while a T3Servlet communicates via Java. You do not need a browser to invoke a T3Servlet; you can embed a T3Servlet in any kind of client Java program, to allow you to distribute processing for routine tasks off the client. Java-to-Java communications between T3Clients and WebLogic Servers can be through an application or applet.

T3Servlets are Java classes that may have input and output parameters (after the database stored procedures model) that a T3Client sets before invoking the T3Servlet remotely, and then examines to get the results after the T3Servlet has been executed. T3Servlets are loaded dynamically from the WebLogic Server's CLASSPATH, and consequently you can recompile T3Servlet class files and see your changes without restarting the WebLogic Server.

You can use a T3Servlet for any task that you want to be executed remotely. Most commonly, you will write a T3Servlet for a routine task that is likely to be executed over and over again by T3Clients, or for privacy-sensitive or compute-intensive operations that will be more efficiently executed somewhere in the network other than in the client.

This document has information on writing T3Servlets.

Top of the page

WebLogic Remote architecture

There are three functional aspects of a working WebLogic Remote application:
  • A WebLogic Server
  • A T3Client
  • A user-written class (implements T3ServletDef) that is stored and runs on the WebLogic Server when called by a T3Client
A user-written T3Servlet class implements weblogic.remote.common.T3ServletDef. Such user-written classes are stored and executed on the WebLogic Server. You execute such a user-written class by constructing a T3Servlet object as a T3Client and calling its execute() method, which contains user-written code that actually does the work of the servlet.

User-written T3Servlets declare parameters with the declareParam() methods in the T3ServletDef class. (The WebLogic Server executes the declaration of parameters when the T3Servlet is instantiated.)

The user-written T3Servlet must also include a setServices() method. This method does nothing more than set a class variable "services" to the T3ServicesDef interface that is passed in as its argument. Simply put, a T3ServicesDef interface is the way a user gains access to services inside the WebLogic Server. Using the T3ServicesDef interface means that you do not need to decide when you write your program where it will be executed, or by whom; that task is decided at runtime, by the context in which the execution occurs. There is more information on the services concept and how it is used in the Developers Guide, Writing a T3Client application.

Here is the canonical example of writing the setServices(T3ServicesDef services) method:

  // Access to services
  T3ServicesDef services;
  // Sets access to services
  public void setServices(T3ServicesDef services) {
    this.services = services;
  }

On the client side, the T3Servlet object is not constructed, but is rather requested from the RemoteServicesDef object factory. (For more information on object factories, see the Developers Guide, Writing a T3Client application.) The getT3Servlet() method takes as its argument the full package name of the user-written T3Servlet class on the WebLogic Server.

After the client requests a T3Servlet object from the RemoteServicesDef object factory, the client calls the execute() method of the T3Servlet object, with a ParamSet as an argument, to run the user-written class on the WebLogic Server. The ParamSet object sets the parameters declared in the user-written class.

Top of the page

II. The API

WebLogic Remote API reference

Class java.lang.Object
    Class weblogic.common.ParamSet
     (implements weblogic.common.WLSerializable,
                 java.lang.Cloneable)
    Class weblogic.common.ParamTypes
    Class weblogic.common.ParamValue
     (implements weblogic.common.WLSerializable,
                 java.lang.Cloneable)
    Interface weblogic.remote.common.RemoteServicesDef
    Class weblogic.common.T3Client
     (implements weblogic.common.internal.T3ChannelCallback,
                 weblogic.common.T3ServicesFinderDef,
		 weblogic.common.DisconnectListener)
    Interface weblogic.common.T3ServicesDef
     (implements weblogic.remote.common.T3ServletDef)
    Interface weblogic.remote.common.T3ServletDef
    Class java.lang.Throwable
     (implements java.io.Serializable)
      Class java.lang.Error
        Class weblogic.common.AssertionError
      Class java.lang.Exception
        Class weblogic.common.ParamSetException
        Class weblogic.common.T3Exception
        Class weblogic.remote.common.T3ServletException

Top of the page

Overview of the WebLogic Remote API

There are three groups of classes used in WebLogic Remote.

Top of the page

Designing a T3Servlet

weblogic.remote.common.T3ServletDef
To write a remote-server-side class, you implement T3ServletDef.

The execute() method in this class contains the actual work of your remote-server-side class. The execute() methods takes a ParamSet object as an argument. Use the parameters that were declared to set instance variables for this method. The WebLogic Server executes the declareParams() method on your behalf each time a T3Servlet is instantiated.

For example, in this user-written class, we declare a set of parameters that will be used to send email when the T3Servlet is executed (that is, when the execute() method is called. The client that calls the execute() method will be responsible for supplying values for the parameters declared in this method.

 public void declareParams(ParamSet ps) 
   throws ParamSetException 
 {
   ps.declareParam("smtphost", ParamTypes.STRING, 
                   "SMTP server address");
   ps.declareParam("from",     ParamTypes.STRING, "Sender email");
   ps.declareParam("to",       ParamTypes.STRING, "Recipient email");
   ps.declareParam("subject",  ParamTypes.STRING, "Subject");
   ps.declareParam("body",     ParamTypes.STRING, "Body text");
 }

 public void execute(ParamSet ps) 
   throws Exception
 {
   try {
     String smtphost = ps.getParam("smtphost").asString();
     String from     = ps.getParam("from").asString();
     String to       = ps.getParam("to").asString();
     String subject  = ps.getParam("subject").asString();
     String body     = ps.getParam("body").asString();
     . . . etc.

The declareParam() method shown in the example above takes three arguments: the keyname of a ParamSet, a constant that denotes a data type from weblogic.common.ParamTypes, and the ParamSet descriptor. (more information about parameters)

The execute() method may also set one or more parameters that the T3Client can retrieve with the getParam() method. Use parameters to return information to the user about the success or failure of an operation or the return values of a procedure. For example, we might also declare and set a parameter for "status", as shown here:

  public void declareParams(ParamSet ps) 
    throws ParamSetException 
  {
    ps.declareParam("smtphost", ParamTypes.STRING, 
                    "SMTP server address");
      . . . declare various parameters for email . . .
    ps.declareParam("status",   ParamTypes.STRING, "Status");
  }

  public void execute(ParamSet ps) 
    throws ParamSetException
  {
    try {
      . . . send the email message . . .
    ps.setParam("status",   "Success! Message sent.");
  }
  catch (Exception e) {
    ps.setParam("status",   "Sorry! Send failed: " + e);
  }

The execute() method is where the work of the T3Servlet is carried out by the WebLogic Server. For example, in the class shown above, the execute() class creates an email message and sends it, according to the information set in the parameters. Note that each time you call the execute() method, a new copy of the object is created on the WebLogic Server.

After you write and compile the class, you store it in the proper package directory in the CLASSPATH of the host of the WebLogic Server.

Top of the section

Executing a T3Servlet

weblogic.remote.common.RemoteServicesDef

Once you have compiled your user-written class and placed it on the WebLogic Server, a T3Client requests a T3Servlet object from the RemoteServicesDef object factory and then executes the class remotely. A T3Client accesses object factories for the various services through its class variable "services," a reference to the interface T3ServicesDef, which defines services to which the T3Client has access. In this case, the client is interested in the RemoteServices, available through the interface RemoteServicesDef, which has a method called getT3Servlet() that requests a T3Servlet object from the factory.

The getT3Servlet() method takes a single argument, which is the full package name of the user-written class on the WebLogic Server. (That T3Servlet implements weblogic.remote.common.T3ServletDef.)

The class name of the remote-server-side procedure to be executed must be the full package name, and the class file must exist on the remote server in a directory structure that matches the package name. For example, if the package name is "examples.remote.mail.Mailer", the class file "Mailer" must exist on the server in classes/examples/remote/mail/, where the directory classes is in the CLASSPATH set for the remote server host machine.

After calling the getT3Servlet() method, the client calls the execute() method of the T3Servlet. Each time you call the execute() method, a new copy of the object is created on the WebLogic Server.

The ParamSet object used in the execute() method should have set all of the parameters that were declared in the class file to be executed on the WebLogic Server. For example, if the following parameters are declared in the remote-server-side class file in the ParamSet "ps":

  ps.declareParam("smtphost", ParamTypes.STRING, 
                              "SMTP server address");
  ps.declareParam("from",     ParamTypes.STRING, "Sender email");
  ps.declareParam("to",       ParamTypes.STRING, "Recipient email");
  ps.declareParam("subject",  ParamTypes.STRING, "Subject");
  ps.declareParam("body",     ParamTypes.STRING, "Body text");

then the ParamSet object passed to the T3Servlet constructor would be built like this:

  ParamSet ps = new ParamSet();
  ps.setParam("smtphost", "smtp.best.com");
  ps.setParam("from",     "errors@myhost.com");
  ps.setParam("to",       "recipient@yourhost.com");
  ps.setParam("subject",  "Your recent request");
  ps.setParam("body",     messagebody);

If the user-written remote class sets a parameter like "status," you can get the same parameter to check the status of the remotely executed procedure.

For more information on setting parameters, see the discussion on parameters that follows.

The T3Client object itself should always be disposed of with the disconnect() method in a finally block.

Top of the section

Setting parameters for T3Servlets

weblogic.common.ParamSet
weblogic.common.ParamTypes
weblogic.common.ParamValues

User-written T3Servlets declare parameters that a T3Client executing the servlet must set, and may set parameters that a T3Client can get for returning status, exceptions, etc. The WebLogic Server calls the declareParams() method on your behalf each time a T3Servlet is invoked. Parameters are handled in WebLogic T3Servlets by ParamSets, which contain ParamValues. (Check Writing a T3Client application for more information on ParamSets.)

The declareParam() methods in the T3ServletDef class take the ParamSet keyname as the first argument and a ParamTypes constant as the second argument. Use the scalars in ParamTypes to declare the data type of the ParamValue for each ParamSet key. The declareParam() method also takes an additional String argument that sets the ParamSet descriptor, which can be used as a display string in a GUI.

Here is how you might set up a ParamSet. This code snippet from a main() takes user-input from the command line as 5 ParamValues. This is how the client that executes a T3Servlet supplies parameters that it will use.

  ParamSet ps = new ParamSet();
  ps.setParam("smtphost", argv[1]);
  ps.setParam("from",     argv[2]);
  ps.setParam("to",       argv[3]);
  ps.setParam("subject",  argv[4]);
  ps.setParam("body",     argv[5]);

The param names for the values that the user supplies have been declared as parameters by the remote server-side user-written class that will use the information. Here is a code snippet from the T3Servlet itself that declares the names and types of the parameters it will use to execute:

  ps.declareParam("smtphost", ParamTypes.STRING, 
                               "SMTP server address");
  ps.declareParam("from",     ParamTypes.STRING, "Sender email");
  ps.declareParam("to",       ParamTypes.STRING, "Recipient email");
  ps.declareParam("subject",  ParamTypes.STRING, "Subject");
  ps.declareParam("body",     ParamTypes.STRING, "Body text");

A ParamSet may also be a vector of ParamSets. For example, in this user-written class called "squarearray," we declare a vector of parameters like this:

  this.declareParam("value1", ParamTypes.VECTOR)

The client sets the "value1" parameter to an array of integers. Then in the execute() method of the user-written class, we determine how many times to calculate based on the length of the vector passed to the execute() method by the T3Client. The parameters for the execute() method are actually set over and over again inside a loop where the calculation takes place, as in this example:

    int len = ps.getParam("value1").size();
    for (int i = 0; i < len; i++) {
      int val = ps.getParam("value1", i).asInt();
      ps.setParam("value1", i, val*val);
      ps.setParam("status", i, "examples.remote.calcs.squarearray " +
                               "computes square of " + val +
			       " = " + val*val);
    }

For WebLogic T3Servlets operations, ParamSets offer a very efficient way of passing information between the WebLogic Server and the T3Client: the remote server-side class can declare parameters for information it wants from the T3Client user in order to complete an operation, and the class may also declare parameters for information that it will make available to the T3Client after the operation completes.

Top of the page

III. Implementing with WebLogic Remote

General implementation notes

The uses of WebLogic T3Servlets are limited only by the programmer's imagination. Writing a T3Servlet or a servlet requires implementing an interface, and invoking a T3Servlet takes just a few lines of code; you invoke a servlet from the browser.

General implementation notes

The steps in writing a T3Servlet are:

  1. Implement weblogic.remote.common.T3ServletDef.
  2. Import the appropriate packages and classes.
  3. Write the setServices() method. This gives the executing party access to the appropriate set of WebLogic services, whether on the client or on the server.
  4. Write the declareParams() method. The parameters you declare must be set by the invoking T3Client, and will supply the T3Servlet with information necessary to execute the T3Servlet and return any results. The WebLogic Server itself calls the declareParams() method as part of its initialization of the T3Servlet.
  5. Write the execute() method. You do the work of the T3Servlet here.
  6. Put the compiled class file in the appropriate place in the WebLogic Server's CLASSPATH.
The steps in invoking a T3Servlet from any T3Client application are:
  1. Create a T3Client and connect to the WebLogic Server.
  2. Create a weblogic.common.ParamSet and set parameters declared by the T3Servlet.
  3. Request the T3Servlet object, using the classname of the T3Servlet class as an argument.
  4. Call the execute() method of the T3Servlet.
  5. If necessary, examine the OUT parameters.

Importing packages

All WebLogic Remote applications import the weblogic.common.* package, which contains the classes for ParamSet and ParamValue as well as the T3Client-related classes.

When you write the class that will be invoked, you must also import the weblogic.remote.common.* package, which contains the weblogic.remote.common.T3ServletDef interface that you will implement.

Writing a constructor and setting services

You do not need to write a constructor; but if you do write a constructor, you must also provide a default constructor (one that takes no arguments). In addition, your constructor should throw a ParamSetException.

In the class you write that implements T3ServletDef, you must write three methods: setServices(), declareParams(), and execute(). There is more on each of those methods below.

Connecting and disconnecting the T3Client

After you write the T3Servlet, you will write a few lines of code in your T3Client application to set parameters and then invoke the execute() method of the T3Servlet.

As is true with any T3Client application, the first step in invoking a T3Servlet is to create the T3Client. A T3Client is always constructed with (minimally) the URL of the WebLogic Server, as in this example:

  T3Client t3 = new T3Client("t3://localhost:7001");
    t3.connect();
  }

You use the T3Client to request a T3Servlet object from the RemoteServices factory (weblogic.remote.common.RemoteServicesDef), with the getT3Servlet() method. Here is an example:

  T3ServletDef t3serv =
    t3.services.remote().getT3Servlet(classname);

When you have finished with the T3Client, you should disconnect, usually done in a finally block, as in this example:

  finally {
    try (t3.disconnect();
    }
    catch (Exception e) {
      . . . act on any Exceptions . . . 
    }
  }

 

Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.
Last updated 01/18/2000