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

IV. Change history

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

WebLogic Remote architecture

• 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

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.

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

Overview of the WebLogic Remote API

• User-written remote-serverside T3Servlets. WebLogic T3Servlets, stored and executed on the WebLogic Server, are user-written classes that subclass weblogic.remote.common.T3ServletDef.

  We talk more about this in the section Designing a T3Servlet.

• T3Servlet objects. To execute a user-written T3Servlet on a WebLogic Server, a T3Client requests a T3Servlet object from the object factory, weblogic.remote.common.RemoteServicesDef and calls the T3Servlet's execute() method.

  This is discussed in the section on Executing a T3Servlet.

• Parameter objects. Parameters are declared for user-written T3Servlets and set by a T3Client executing the servlet with a weblogic.common.ParamSet, which is made up of one or more weblogic.common.ParamValues.

  There is a discussion of using ParamSets and ParamValues with T3Servlets in the section on Using ParamSets and ParamValues. There is more general information about ParamSets, ParamTypes, and ParamValues in Writing a T3Client application.

Designing a T3Servlet

weblogic.remote.common.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.

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.

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.

III. Implementing with WebLogic Remote

General implementation notes

• Importing packages
• Writing a constructor and setting services
• Connecting and disconnecting the T3Client

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.

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

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

Change history

Release 4.5.1

Although WebLogic Remote is currently still supported, we will be deprecating pre-standards interfaces for use with WebLogic Remote in favor of the standard RMI model. The WebLogic Remote examples are deprecated in this release.

Release 3.0

With WebLogic release 3.0, you should have upgraded your use of WebLogic T3Servlets to the latest release of the 1.1 version of the Java Developers Kit. WebLogic no longer supports 1.0.2 universally; our 1.0.2 support is limited to client-side applets (using only WebLogic JDBC, RMI, Event, and T3Servlet services) that are run in either Microsoft IE 3.0.2 or later or Netscape 3.0 or later browsers. Running the WebLogic Server against the 1.0.2 JVM is no longer supported, and running or compiling your WebLogic applications against 1.0.2 is also no longer supported.

Release 2.5 -- 8/23/97

Added support for access to EventT3 and RemoteT3 services within the WebLogic Server framework from a Visigenic CORBA client. For the CORBA IDL description of these services, please see the file t3client.idl in the distribution directory weblogic/idl/visi/t3client. For installation instructions and tips on using the examples, please read Setting up T3Client CORBA access.

Removed the weblogic.system.classpath property. This property was previously used to determine CLASSPATH for T3Servlets and WebLogic Event classes. It is no longer in use. The WebLogic Server depends on the CLASSPATH set on the host machine.

Release 2.3 -- 12/23/96

In T3Servlets, you should no longer use a constructor for a T3Servlet; rather, you request a T3ServletDef object from a RemoteT3 services factory, which is accessed by the remote() method in the interface weblogic.common.T3ServicesDef. This means that you no longer need to import weblogic.***.t3client or weblogic.***.server; you just import the weblogic.***.common version.

For classes that implement T3ServletDef, you must also write a setServices(T3ServicesDef services) method to provide access to WebLogic Server services for those classes. The T3ServicesDef interface is a set of methods that return access objects to services and facilities within WebLogic.

Please note that weblogic.remote.common.T3ServletDef is an interface, rather than a class.

Changes in methods for T3Servlets:

1. T3Servlet classes should now implement T3ServletDef, rather than extending it.
2. T3Servlet classes should now import weblogic.remote.common.* and weblogic.common.*.
3. T3Servlet classes should now declare the class variable:

     T3ServicesDef services;

   which is a reference to the T3ServicesDef object that will be used to gain access to services in the WebLogic Server.
4. T3Servlet classes no longer need a default constructor.
5. T3Servlet classes should write 3 methods:

     public void setServices(T3ServicesDef services) {
       this.services = services;
     }
   
     public void declareParams(ParamSet ps)
       throws ParamSetException
     {
       . . . call declareParam() for your parameters
     }
   
     public void execute(ParamSet ps) throws Exception {
       . . . whatever you want your T3Servlet to do
     }

   Note that declareParams() now takes a ParamSet as an argument.

Classes that invoke T3Servlets also have some method changes:

1. Classes now import weblogic.common.* and weblogic.remote.common.*.

2. Instead of constructing a T3Servlet, you now request a T3ServletDef object with a factory method, as shown here:

     // Create a T3Client and connect
     T3Client t3 = new T3Client("t3://toyboat.toybox.com:7001");
     t3.connect();
   
     // Manufacture a T3Servlet object for the client
     T3ServletDef ts =
       t3.services.remote()
         .getT3Servlet("tutorial.remote.mail.mailer");
   
     // Execute the T3Servlet remotely with methods from the
     // T3Servlet object's class, where "ps" is a ParamSet
     t3.execute(ps);

   Note that the execute() method is now called with a ParamSet as a parameter, and that the virtual constructor (factory method) for T3Servlet objects no longer takes a ParamSet as a constructor, nor does it take a T3Client object as an argument.

   New classes and methods that will be of interest are:

   • weblogic.common.T3ServicesDef, which is a set of methods that return access objects to services and facilities in the WebLogic Server. Call the remote() method from this interface to get access to remote services.
     • weblogic.remote.common.RemoteServicesDef, a set of factory methods that manufacture objects for remote services
       • weblogic.remote.common.T3ServletDef, the interface for T3Servlet objects

   The factory method in the interface RemoteServicesDef in weblogic.remote.common is used instead of constructors from these classes:

   • weblogic.remote.t3client.T3Servlet
   • weblogic.remote.server.T3Servlet

   Your applications should now import only packages from among weblogic.common.*, and weblogic.remote.*.

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/13/1999