![]() |
![]() |
Using WebLogic Remote
Overview of WebLogic RemoteWebLogic 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![]()
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 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
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 architectureThere are three functional aspects of a working WebLogic Remote application:
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 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 APIWebLogic Remote API referenceClass 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 APIThere are three groups of classes used in WebLogic Remote.
Designing a T3Servlet
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
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
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.
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.
The steps in writing a T3Servlet are:
Importing packagesAll 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 servicesYou 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 T3ClientAfter 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.
|