BEA Logo BEA WebLogic Server Release 5.0

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

Writing a WebLogic client application

Note  The weblogic.common.T3Client class will be deprecated in a later WebLogic Server release. Instead, Java clients should use JNDI to access WebLogic Server services. JNDI is preferred because it is a standard J2EE technology and because WebLogic Server clusters rely upon JNDI. If you are developing new WebLogic Server client applications, please refer to the document Writing WebLogic Server Java Client Applications instead of this document.

I. Overview of WebLogic Server architecture
What is the WebLogic Server?
What is a T3User?
What is a T3Client?
Protocols for connecting a T3Client to WebLogic
Common resources and characteristics
Server-side services and facilities
Accessing WebLogic services via JNDI
Accessing WebLogic services via T3Client
The WebLogic services and facilities

II. Services
Getting access to services
Writing the setServices() method

III. Facilities
Workspaces
Naming
Configuration
Administration
Logging
Programmatic shutdown

IV. Other features of the WebLogic environment
Support for HTTP
Tunneling client access over HTTP
Client connect and disconnect accounting
Disconnect timeouts
Doing server-side work when a client disconnects
Asynchronous client notification of disconnect
Setting application-specific properties
Using ParamSets, ParamValues, and ParamTypes in WebLogic
Workspace hooks

V. Change history

The Developers Guides
Using WebLogic ACLs
Using WebLogic's distributed server-side Beans
EJB Design and Development
Using WebLogic Events
Using WebLogic File services
Using WebLogic HTTP Servlets
Using WebLogic JDBC
Using WebLogic JHTML
Using WebLogic JNDI
Using WebLogic RMI
Using WebLogic SSL
Using WebLogic Remote
Using WebLogic Time services
Using WebLogic Workspaces
Using WebLogic ZAC

Other related documents
Installing WebLogic (non-Windows)
Installing WebLogic (Windows)
API Reference Manual
WebLogic Administrators Guide
Database Connectivity in WebLogic
Code examples
Glossary

Overview of WebLogic architecture

WebLogic's architecture is a plug-and-play environment for creating multitier networked applications. All of the Java Enterprise APIs -- including WebLogic RMI, WebLogic EJB, WebLogic JDBC, WebLogic HTTP Servlets, and WebLogic JNDI -- are implemented to work in an integrated way within WebLogic. In addition to its standards-based services, WebLogic offers many facilities for development and deployment, like integrated security (WebLogic SSL and WebLogic ACLs), logging, and a graphical management console (the WebLogic Console).

Although you use different WebLogic services for solving different business problems, all of WebLogic services and facilities share common elements and use common objects. Objects like T3Clients and WebLogic Workspaces are used generally in the same way whether you are writing a database client that uses WebLogic JDBC and WebLogic RMI, or an HTTP servlet.

This document is designed to be used by a developer writing a WebLogic client-side application. It includes information that applies to the general relationship between T3Clients and WebLogic Servers, how that relationship is created and managed, and how the different objects that make up that relationship interact. It complements other Developers Guides that address issues specific to writing applications with:
WebLogic Beans WebLogic EJB WebLogic Events
WebLogic File services WebLogic HTTP Servlets WebLogic JHTML
WebLogic JDBC WebLogic JNDI WebLogic Time services
WebLogic ZAC WebLogic RMI WebLogic Workspaces
WebLogic ACLs WebLogic SSL

With the Administrators Guide document Running the WebLogic Console, you can take a look inside your WebLogic Server while it is running to examine many of the objects that make up the work of the server, including information about a WebLogic Server's clients. For more information on these tools, check the Administrators Guide document Running and maintaining the WebLogic Server.

Top of the page

What is the WebLogic Server?

Unlike highly structured programming environments, WebLogic is a lightweight, very efficient set of pure-Java modules for enabling your Java applications for certain tasks. It sits beneath your application; you can use whatever WebLogic components make sense for your business application. All of your WebLogic applications, no matter what module(s) they use, inherit access to all of the WebLogic Server's facilities, and as these facilities are upgraded and enhanced, all of your WebLogic applications benefit. Services and facilities offered within WebLogic include:

WebLogic services. WebLogic has plug-and-play components that offer several services (implementations of standard Java APIs). Your client can use any or all of these services; you may also use remoted server-side services.

  • WebLogic Beans and Beanbar
  • WebLogic Enterprise JavaBeans
  • WebLogic Events
  • WebLogic File services
  • WebLogic HTTP Servlets and JHTML support
  • WebLogic JDBC
  • WebLogic JNDI
  • WebLogic Remote
  • WebLogic RMI
  • WebLogic Secure, including WebLogic ACLs

T3Client-to-WebLogic Server communications. WebLogic Servers communicate between themselves and with clients via packet-based queues over a transport mechanism our engineers call RichSockets(tm). A RichSocket is a connection between a client and a server over which a variety of services can be obtained. Like rich text, which can express language with more than just characters, a rich socket carries more information about the connection and its connected parties than a regular socket does.

The WebLogic Server listens at a TCP port for incoming connection requests; the port number is set by an entry in the weblogic.properties file (for more information, check Setting WebLogic properties). The connection that is opened between the T3Client and its WebLogic Server is represented by a T3Connection object. A T3Connection can carry all kinds of WebLogic traffic simultaneously; for example, a T3Connection may be hosting WebLogic JDBC traffic, WebLogic RMI traffic, and WebLogic Event traffic at the same time. There is always a one-to-one relationship between a T3Connection and a T3Client; a client cannot have more than one concurrent T3Connection, and a T3Connection cannot service more than one concurrent T3Client. T3Connections, however, are reusable. Once a T3Connection is created, it may be used sequentially by any number of T3Clients.

Within the WebLogic Server, each T3Client has its own send-queue, which dispatches the request to the proper WebLogic Server process; when the request completion is received, it is placed on the client's receive-queue to be returned to the T3Client. Because queues exist within the WebLogic Server, a T3Client may go away, and reconnect and have access to the same T3Client workspace, at which time it will receive whatever is waiting on its receive-queue.

Making the WebLogic Server's communications queue-based increases its efficiency. When the WebLogic Server receives a request for a connection from a T3Client, it creates (or reopens) a Workspace for the client. Workspaces also may be created to include groups of client Workspaces, and the system itself has a Workspace that includes all of the Workspaces in a WebLogic Server.

WebLogic Server facilities. One of the most important characteristics of WebLogic is that its server facilities are accessible to all of the applications that use the WebLogic Server. For a full description of WebLogic's Server facilities, see the companion overview, Writing a server-side application.

Facilities of immediate interest to T3Clients include:

  • Client Workspaces. WebLogic has a set of hierarchically arranged Workspaces that are assigned to clients, groups of clients, and the WebLogic Server itself. A Workspace can contain any arbitrary objects, and Workspaces can be named, saved, and reentered over several sessions. In version 2.5, Workspaces were elevated to first-class objects to make them more powerful.

  • Shared objects. Any application that operates within WebLogic has access to objects of other WebLogic applications through named Workspaces. Objects stored in Workspaces can be shared among clients, groups of clients, and the system.

  • HTTP port-80 access. The WebLogic Server can act as an HTTP server listening on port 80 for serving HTTP servlets. Setting up the WebLogic Server to listen on port 80 means that T3Clients can also communicate with the WebLogic Server across a firewall in standard fashion. This gives all T3Client applications -- using WebLogic Events, WebLogic JDBC, and/or WebLogic Beans, etc -- port 80 access to WebLogic. The WebLogic Server is designed to serve as a fully-featured webserver for an arbitrary files; in addition, it can proxy to another server.

  • Allocation of scarce resources. Factory methods and other internal allocation mechanisms allow very fine control over how resources are shared among resource consumers.
Top of the page

What is a T3User?

weblogic.common.T3User

A T3User represents access to the WebLogic Server -- a username and password. You can use a T3User object in the constructor for a T3Client. You register a username and password for access to WebLogic by adding an entry to the weblogic.properties file. Here is an example that sets the password for "johnmark" to "jmpassword":

weblogic.password.johnmark=jmpassword

The T3User is part of the client's Workspace. You can check the T3User for a client on the T3Client Workspace page of the WebLogic Admin servlets, or by examining the Users information in the Console under "Connected users."

You set up access control for the WebLogic realm with a list of T3Users.

Top of the page

What is a T3Client?

weblogic.common.T3Client
weblogic.common.ProxyAuthenticator

Applications that operate within WebLogic do so in a general way as T3Client applications. Although the distinction between T3Client and WebLogic Server may not always be sharply delineated -- since WebLogic Servers may become T3Clients and vice-versa, depending upon the way the application does its work -- in general, the WebLogic Server mediates between its clients and other resources on the network.

There are several constructors for a T3Client object. Each is used within a certain context. A T3Client can be constructed with:

  • The URL of the WebLogic Server, after the pattern:
      scheme://WebLogicURL:port

    Supplying the port number is only necessary if the WebLogic Server is listening on a TCP port other than port 80. Constructing a T3Client with this constructor opens an arbitrary connection to the WebLogic Server with a new, unnamed T3Connection object and logs the T3Client in as a "guest" T3User. A new, unnamed Workspace is created for the client.

    Protocols for connecting a T3Client to WebLogic

    Once a connection is established, the T3Client can use its connection to WebLogic for any kind of traffic -- it can use JDBC, make JNDI lookup requests, bind to RMI objects, execute EJBeans. The protocol of the connection determines not what sort of traffic can pass between the client and the WebLogic Server, but the nature of the connection.

    The scheme sets up the connection via a certain method of access to the WebLogic Server. There are several method (technically, protocols) a T3Client can use to connect to a WebLogic Server:

    t3://
    Sets up a standard T3Client-to-WebLogic Server connection.

    t3s://
    Sets up a secure T3Client-to-WebLogic Server connection via Secure Socket Layer (SSL), one of the features of WebLogic Secure. For more about using SSL with the WebLogic Server, see the Developers Guide, Using WebLogic SSL.

    If your WebLogic client is behind a proxy server firewall, you may need to set up an SSL proxy. You can configure the t3s protocol for proxying by setting values for the two system properties, ssl.proxyHost and ssl.proxyPort. Use these system properties in the command to run the WebLogic client, for example,

     $ java -Dssl.proxyHost=host -Dssl.proxyPort=port MyClient

    With release 3.1, the weblogic.properties file supports adding Java system properties to your properties file, as shown here:

    java.system.property.ssl.proxyHost=www.myserver.com
    java.system.property.ssl.proxyPort=8346

    http://
    Sets up a Java-to-Java connection via HTTP tunneling, one of the features of WebLogic's built in HTTP webserver. Note that you must supply a port number when using http://, even if the port is port 80. For client connections that must traverse firewalls, where HTTP via port 80 is the only available method of entry, you can tunnel T3Client-to-WebLogic Server connections.

    HTTP tunneling can also be used to communicate with a WebLogic Server via a proxy, if the proxy has DNS access to the WebLogic Server.

    Tunneling slows performance, since each message must be encoded and decoded. Consequently, HTTP tunneling should only be used when there is no other means of access available for a client. Note: In order to use HTTP tunneling, you must have Basic Authentication turned off. Turn off Basic Authentication in the WebLogic Server by setting the property weblogic.httpd.requireAuthentication to false.

    If your client is behind a proxy server firewall, you may need to set up an HTTP proxy. Configure the http protocol for proxying by setting values for the two system properties, http.proxyHost and http.proxyPort. Use these system properties when you run the WebLogic client, for example,

     $ java -Dhttp.proxyHost=host -Dhttp.proxyPort=port MyClient

    With release 3.1, the weblogic.properties file supports adding Java system properties to your properties file, as shown here:

    java.system.property.http.proxyHost=www.myserver.com
    java.system.property.http.proxyPort=8080

    If the proxy server requires authentication, you will need to provide an implementation of the weblogic.common.ProxyAuthenticator interface, introduced with release 3.1.4. When a proxy server requests authentication, methods in your ProxyAuthenticator implementation class are called to obtain a login name and password for the proxy server.

    https://
    Sets up secure HTTP tunneling. Because of the double overhead of tunneling and SSL, this method of connecting will probably not be satisfactory unless security and transfirewall access are so important that you are willing to accept its speed limitations. The HTTPS protocol is available only for applets, since it depends on the SSL support in the browser.

    You can also set up an HTTPS proxy, which you may need to do if your WebLogic client is behind a proxy server firewall. Do this by setting a value for the two system properties, https.proxyHost and https.proxyPort. You can set these on the command line when you run your Java client with a command such as,

     $ java -Dhttps.proxyHost=host -Dhttps.proxyPort=port MyClient

    If the proxy server requires authentication, you will need to provide an implementation of the weblogic.common.ProxyAuthenticator interface, introduced with release 3.1.4. When a proxy server requests authentication, methods in your ProxyAuthenticator implementation class are called to obtain a login name and password for the proxy server.

    With release 3.1, the weblogic.properties file supports adding Java system properties to your properties file, as shown here:

    java.system.property.https.proxyHost=www.myserver.com
    java.system.property.https.proxyPort=4635

    You can control the keep-alive period for both HTTP and HTTPS clients to tune your client application's performance. Because HTTP/HTTPS is a stateless protocol, the connection is customarily kept open only as long as there is traffic over it. Keep-alive keeps a server session open for a period of non-continuous work. Increasing the keep-alive can decrease the frequency with which your client application has to reopen an HTTP connection; but keep-alive also ties up potential connections to WebLogic, so you should tune your application. Set the WebLogic property weblogic.httpd.https.keepAliveSecs of weblogic.httpd.http.keepAliveSecs in the weblogic.properties file to configure keep-alive. The default keep-alive interval is 15; the minimum is 5, and the maximum is 200 seconds.

    bean://
    Supports WebLogic Bean communications for T3Bean messages. For more info on BeanT3, check out the Developers Guide, Using WebLogic distributed server-side Beans.

    rmi://
    Supports RMI communications within WebLogic. For more info, see the Developers Guide, Using WebLogic RMI.

  • The URL of the WebLogic Server and a T3User object. This opens an arbitrary connection to the WebLogic Server, logs in the client with the supplied T3User username and password, and then creates a new, unnamed workspace for the client.

  • The URL of a WebLogic Server and the ID or name of an existing Workspace. This opens a connection to the WebLogic Server and gives the T3Client access to an existing Workspace. (If a Workspace by that name or ID doesn't exist on the WebLogic Server, the String supplied as an argument is assumed to be the name for a new Workspace that is created.)

  • The URL of a WebLogic Server, the name or ID of an existing Workspace, and a T3User object. This opens a connection to the WebLogic Server and gives the client access to an existing Workspace. (If a Workspace by that name or ID doesn't exist on the WebLogic Server, the String supplied as an argument is assumed to be the name for a new Workspace that is created.) The T3Client gains access to the WebLogic Server with the username and password of the supplied T3User object.

Top of the page

Common resources and characteristics

What a T3Client can do in its application is limited only by the developer's imagination. There are, however, many common resources and characteristics that are shared by all T3Client applications. Following are some short descriptions and examples.

For more help, check the code examples of simple applications of these concepts in examples/t3client, examples/event, and examples/servlets, all of which are included with the distribution.

Top of the page

Server-side services and facilities

The WebLogic Server provides a number of services and facilities that make up the distributed client/server development environment. Client access to WebLogic's services can be controlled, determining:

  • which clients have permission to use specific services
  • how often a client may use a service
  • how many clients at one time may use certain services

Accessing WebLogic services via JNDI

A WebLogic client obtains a resource by invoking a factory method for a particular service from a remote interface called T3SerficesDef which is the gateway to WebLogic's server-side services. The client gets a reference to the T3Services remote interface from the WebLogic JNDI tree. JNDI is a remote shared directory that provides a well-known location for distributed applications to store and retrieve distributed objects.

In many of the examples, we encapsulate the JNDI lookup of the T3Services stub in a method that we assume is implemented on the client. Here is the definition of the getT3Services() method. It uses JNDI to look up the remote stub to the T3Services factory on the WebLogic Server at the URL given.

private static T3ServicesDef getT3Services(String wlUrl) 
       throws javax.naming.NamingException
  {
    T3ServicesDef t3s;
    Hashtable env = new Hashtable();
    env.put(Context.PROVIDER_URL, wlUrl);
    env.put(Context.INITIAL_CONTEXT_FACTORY,
            weblogic.jndi.WLInitialContextFactory.class.getName());
    Context ctx = new InitialContext(env);
    t3s = (T3ServicesDef) ctx.lookup("weblogic.common.T3Services");
    ctx.close();
    return(t3s);
  }

The public APIs for the currently available services are accessible from the weblogic.common.T3ServicesDef interface, which has methods for all of WebLogic's services and facilities.

Accessing WebLogic services via T3Client

Previously, WebLogic clients have made connections to the server using a proprietary API called T3Client. However, it is recommended that new applciations avoid using the T3Client connection and should be implemented using J2EE standards that are supported by WebLogic.

Some of WebLogic's older proprietary APIs can only be access via a T3Client connection. If your application is WebLogic specific, and uses a T3Client connection, you may gain access to factory methods for services and facilities through the T3Client.services object. The code for accessing a service follows this pattern:

  T3Client t3 = new T3Client("t3://localhost:7001");
  FacilityObject fao =
    t3.services.[facility]().[getFacilityObject]()

Where facility is one of the factory access methods in the interface T3ServicesDef and getFacilityObject is a method defined in the ServicesDef interface for each facility or service. See the appropriate facility or service API or developer guide for more details on its functionality.

The WebLogic services and facilities

Administrative facility:
AdminServicesDef
String licenses = t3.services.admin().licenses();

WebLogic Bean service:
T3BeanServicesDef

Configuration facility:
ConfigServicesDef
String property =
  t3.services.config().getProperty("weblogic.system.home");

WebLogic Event service:
EventServicesDef

WebLogic File service:
IOServicesDef

WebLogic JDBC service:
JdbcServicesDef

WebLogic JNDI service:
WLInitialContextFactory

Logging facility:
LogServicesDef
t3.services.log().error("Error message");

WebLogic Workspaces:
WorkspaceDef and
WorkspaceServicesDef
WorkspaceDef ws = t3.services.workspace().getWorkspace();

Many objects for services and facilities inside WebLogic are defined by interfaces. An interface is simply a contract between the object's user and the object's creator that guarantees that an object will have certain aspects. The Java interface provides a powerful conceptual model that WebLogic leverages in its WebLogic architecture. Using interfaces to define services and factory methods, for example, means that the developer does not need to know a priori whether the object that instantiates a class will be executed on the WebLogic Server or in a T3Client. You can write classes that may be executed at runtime anywhere in the WebLogic Server environment, by a WebLogic Server or a T3Client.

Access to services is detailed in the following section on Services, and each individual service has its own Developer Guide. There are more details about facilities in the following section on Facilities.

Top of the page

Services

weblogic.common.T3ServicesDef
weblogic.beans.common.T3BeanServicesDef
weblogic.event.common.EventServicesDef
weblogic.io.common.IOServicesDef
weblogic.jdbc.common.JdbcServicesDef
weblogic.remote.common.RemoteServicesDef

One of the fundamental aspects of the WebLogic Server is the way in which it handles requests from T3Clients for access to services and facilities. Any WebLogic Server user (whether a T3Client or another WebLogic Server) can request access to a specific service or facility through factory methods, which manufacture objects that represent WebLogic Server services and facilities. The WebLogic Server manages its resources through internal classes that specify how objects are manufactured, requested, and allocated within its environment.

Top of the page

Getting access to services

A T3Client uses object factory methods for the various services and facilities through its class variable "services," a reference to the interface T3ServicesDef, which defines the WebLogic services and facilities to which a T3Client has access.

The weblogic.common.T3ServicesDef interface contains a set of methods for getting access to the various object factories. For example, a T3Client "t3" accesses the factory methods for WebLogic Event objects by calling the event() method from this interface, as in this example:

  t3.services.event() . . . (plus a getXXX() method)

Rather than calling a constructor to create a WebLogic Server resource, a T3Client requests an object via its services factory method. For example, rather than constructing an EventRegistration, a T3Client asks for an EventRegistration object from the EventServicesDef, which is an interface that defines an event factory. The factory manufactures objects for WebLogic Events, one of WebLogic's services.

For example, here is how you use the EventServicesDef factory in the process of registering interest in an event. Create the T3Client, request an EventRegistrationDef object with the T3ServicesDef.events() method, and call its register() method:

  // Create a T3Client and connect
  T3Client t3 = new T3Client("t3://localhost:7001");
  t3.connect();

  // Create ParamSets for evaluate and action
  ParamSet evRegParams = new ParamSet();
  evRegParams.setParams("SYMBOL",       interestingStockName);
  evRegParams.setParams("TRIGGERVALUE", interestingPrice);

  ParamSet acRegParams = new ParamSet();
  acRegParams.setParams("SMTPhost",     myEmailHost);
  acRegParams.setParams("Addressee",    myEmailAddress);

  // Manufacture an EventRegistration object for the topic
  EventRegistrationDef er = t3.services.events()
    .getEventRegistration("STOCKS",
           new Evaluate("examples.event.stocks.EvaluateStocks",
	                evRegParams),
           new Action  ("examples.event.stocks.MailStockInfo",
	                acRegParams));

  // Register with methods from the object's class
  int regid = er.register();

Here is another example that demonstrates how you use the IOServicesDef factory to manufacture a T3FileOutputStream object for writing to a file on the WebLogic Server.

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

  T3FileOutputStream t3os =
    t3.services.io().getFileOutputStream("myfilename");

Top of the page

Writing the setServices() method

Some user-written classes that implement a T3Client-related service interface -- for example the WebLogic Event ActionDef and EvaluteDef interfaces -- must write a setServices() method, which takes as a parameter a T3ServicesDef object. This object provides the implementing class access to services in the WebLogic Server, without requiring the T3Client object itself. The setServices() method allows the definition of who provides an object for access to services to be set as necessary, before any of its interface methods are invoked which may need access to those services.

If you are writing a T3Client application that uses the WebLogic Event services, you will be writing a setServices() method for the following interfaces:

weblogic.event.actions.ActionDef
weblogic.event.evaluators.EvaluateDef

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

  // Set the services object
  T3ServicesDef services;

  public void setServices(T3ServicesDef services) {
    this.services = services;
  }

Top of the page

Facilities

weblogic.common.AdminServicesDef
weblogic.common.ConfigServicesDef
weblogic.common.LogServicesDef
weblogic.common.WorkspaceServicesDef and weblogic.workspace.common.WorkspaceDef

WebLogic also provides access to a set of facilities. You also use factory methods to gain access to WebLogic facilities, in a fashion similar to that for services. Once again, services are accessed through a reference to weblogic.common.T3ServicesDef, which defines the WebLogic services and facilities to which a T3Client has access.

The current set of facilities -- Workspaces, Administration, Configuration, and Logging -- are described in the following section.

Top of the page

Workspaces

weblogic.common.WorkspaceServicesDef
weblogic.workspace.common.WorkspaceDef

Workspaces, one of WebLogic's features, are hierarchically arranged storage areas in the WebLogic Server in which arbitrary objects can be stored. T3Clients can create named workspaces and return back to the same workspace again and again.

In release 2.5, Workspaces were elevated to first-class object status to provide the developer with extended features. For example, you can now create a new Workspace, attach to an existing Workspace, or open a Workspace -- attach to one if one exists, or create a new one. A Workspace can be operated on at specific points in its lifecycle with WorkspaceMonitors.

The discussion of Workspaces has been moved to a separate document, Using the T3Client Workspace. If you are converting your old Workspace usage to the latest version, check the section on Converting from the old model to the new.

Top of the page

Naming

WebLogic offers naming and directory services through its implementation of the JavaSoft Java Naming and Directory Interface (JNDI). Naming gives you a way to locate and use objects that are not local to your client within a model that can support security and other cluster-related functionality.

For more information about WebLogic JNDI, check the Developers Guide, Using WebLogic JNDI.

Note that WebLogic does not support the use of JNDI in applets that do not provide complete JDK 1.1 compliance.

Top of the page

Configuration

weblogic.common.ConfigServicesDef

Configuration information is available to T3Client applications through a factory method that returns a configuration parameter from the current weblogic.properties file. For a T3Client, usage is:

  // Create a T3Client and connect
  T3Client t3 = new T3Client("t3://localhost:7001");
  t3.connect();

  // Ask the value of some property
  String serverHome     =
     t3.services.config().getProperty("weblogic.system.home");
  String consoleEnabled =
     t3.services.config().getProperty("weblogic.system.enableConsole");

  System.out.println("System home: "        + serverHome);
  System.out.println("Console is enabled: " + consoleEnabled);
Top of the page

Administration

weblogic.common.AdminServicesDef

Several administrative functions are available to T3Clients through factory methods. Some of the methods require administrative password access to the WebLogic Server. For a T3Client, usage is:

  // Create a T3Client and connect
  T3Client t3 = new T3Client("t3://localhost:7001");
  t3.connect();

  // Get license and version information for the WebLogic Server
  String license = 
	t3c.services.admin().licenses();
  String version = 
	t3c.services.admin().version();

  // Display the results
  System.out.println("License info " + license);
  System.out.println("Version info " + version);
Top of the page

Logging

weblogic.common.LogServicesDef

You can write log messages -- info, warning, security, debug, or error messages -- to the WebLogic Server's log file (the default file is in myserver/weblogic.log) through factory methods. For a T3Client, usage is:

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

    // Log a message in the WebLogic Server weblogic.log file
    String logmsg = "This message logged at " + new java.util.Date();
    t3.services.log().info(logmsg);

Use the appropriate method in the LogServicesDef interface to log an info(), warning(), error(), security(), or debug() message. One method signature for error() allows passing a stack trace or the error itself (as a Throwable) with the logged message.

Top of the page

Programmatic shutdown

You can shutdown the WebLogic Server programmatically from a T3Client application with one of the method calls in the AdminServicesDef.

Top of the page

Other WebLogic Server features

The WebLogic Server offers other convenient features that are commonly available to all client applications that are described here.

Top of the page

Support for HTTP

The WebLogic Server is a fully-functional HTTP server. Browser clients can serve files of various MIME types, including HTML pages and applets, and the WebLogic Server can log HTTP statistics in common log format, in the weblogic.log, and as generated events. For more information on setting up and using the WebLogic Server for HTTP, read the WebLogic Administrators Guide, Setting up WebLogic as an HTTP server.

Top of the page

Tunneling client access over HTTP

weblogic.common.T3Client

Tunneling allows access for clients to the WebLogic Server when it is behind a firewall, or whose T3Clients must access the WebLogic Server via a proxy behind a firewall. For client connections that must traverse firewalls--where HTTP via port 80 is the only available method of entry--you can tunnel T3Client-to-WebLogic Server connections. HTTP tunneling can also be used to communicate with a WebLogic Server via a proxy, if the proxy has DNS access to the WebLogic Server.

Tunneling will slow performance, since each message must be encoded and decoded; consequently, HTTP tunneling should only be used when there is no other means of access available for a client.

If your WebLogic client is behind a proxy server firewall, you may need to set up a proxy if you are using http, https, t3s. Configure either of these protocols for proxying by setting values for the two system properties, protocol.proxyHost and protocol.proxyPort. Use these system properties as -D options for the java command. For example, here are examples on how you would set up proxying for http, https, and t3s:

 $ java -Dhttp.proxyHost=host -Dhttp.proxyPort=port MyClient
 $ java -Dhttps.proxyHost=host -Dhttps.proxyPort=port MyClient
 $ java -Dssl.proxyHost=host -Dssl.proxyPort=port MyClient

With release 3.1, the weblogic.properties file supports adding Java system properties to your properties file, as shown here:

java.system.property.ssl.proxyHost=www.myserver.com
java.system.property.ssl.proxyPort=8080

Making a client request to the WebLogic Server tunneled over HTTP

All you must do to connect via tunneling is create your T3Client with a URL after the pattern http://host_name:port, as shown in this example:

  T3Client t3t = new T3Client("http://localhost:80");

The port number is required in the URL, even if it is port 80.

You must set up WebLogic properly for tunneling. See the WebLogic Administrators Guide, Setting up WebLogic as an HTTP server.

Top of the page

Client connect and disconnect accounting

When a client connects or disconnects, an event message is submitted to the WebLogic Server. You can register your application for interest in those events. The events submitted are:

  • WEBLOGIC.ACCOUNTING.CONNECT, when a client connects
  • WEBLOGIC.ACCOUNTING.DISCONNECT, when a client disconnects
On a connect event, the event message is submitted with a set of parameters:
  • USER_NAME. T3User username.
  • WORKSPACE_ID. The system ID of the workspace.
  • HOST_NAME. T3Client hostname.
  • HOST_ADDRESS. T3Client IP address.
  • CONNECTION_ID. Connection ID.
  • CONNECTION_START_DATE. Start time and date.

On a disconnect event, the event message is submitted to the WEBLOGIC.ACCOUNTING.DISCONNECT event with the same parameters, including CONNECTION_END_DATE, with the time and date of the disconnect event.

Top of the page

Disconnect timeouts

weblogic.common.T3Client

A T3Client can set three kinds of timeouts that determines how the WebLogic Server handles a T3Client's resources once the client is disconnected. A timeout specifies how long the WebLogic Server should wait to clean up (destroy) a T3Client's resources, including its workspace, after a specific kind of disconnect occurs. Types of disconnects and their timeouts are:

  • Hard disconnect. A hard disconnect occurs when the socket supporting the T3Client's connection goes away. The default hard disconnect timeout is "immediately."

  • Soft disconnect. A soft disconnect occurs when the T3Client calls its disconnect() method. The default soft disconnect timeout is "immediately." Setting the soft disconnect timeout to T3Client.DISCONNECT_TIMEOUT_NEVER effectively prevents the WebLogic Server from ever cleaning up a T3Client's resources, which extends the lifetime of the T3Client and all of its associated resources for the lifetime of the WebLogic Server.

  • Idle disconnect. An idle disconnect occurs when the WebLogic Server notices that the T3Client has become inactive. The default idle disconnect timeout is "never," which means that the WebLogic Server will never, by default, destroy the resources of an inactive T3Client.

You control timeouts with the getXXXDisconnectTimeoutMins() and setXXXDisconnectTimeoutMins() methods in the T3Client class.

If you attempt to operate on a T3Client after it has been disconnected, the T3Client will throw a T3Exception, "[T3Client not connected]".

Top of the page

Doing server-side work when a client disconnects

When a client disconnects for any reason, the client's default Workspace, or its client context, is destroyed, along with all of the workspace contents, unless its soft disconnect timeout has been set to make the workspace persistent. You can carry out both client-side and server-side tasks at disconnect. (For more information on client-side cleanup, see the next section on asynchronous disconnects.)

You can execute a monitor whenever a Workspace object is destroyed, and using this mechanism, you can carry out a set of cleanup operations when your client disconnects.

To accomplish this, assign a "DestroyMonitor" to a particular Workspace key, and then add a value under that key. When the value is destroyed, your monitor will be called. A monitor can perform any arbitrary work.

This destroy monitor example sends an event when a workspace value is destroyed.

public class DestructionMonitor implements DestroyMonitor {
  private T3ServicesDef services;
  private String topic;

  public void monitorInit(ParamSet params,
                          boolean isMaster) throws ParamSetException {
    topic = params.getParam("topic").asString();
  }

  public void setServices(T3ServicesDef services) {
    this.services = services;
  }

  public void preDestroy(Destroyable target, ParamSet callbackData) {}

  public void postDestroy(Destroyable target,
                          ParamSet callbackData,
			  Exception e) {
    if (e == null) {
      ParamSet ps = new ParamSet();
      try { 
        if (target instanceof WorkspaceValue) {
          ps.setParam("key", ((WorkspaceValue) target).getKey());
        }
        EventMessageDef em = 
           services.events().getEventMessage(topic, ps);
        em.submit();
      }
      catch (ParamSetException pse) {}
      catch (EventGenerationException ege) {}
    }
  }
}

Then you will install the destroy monitor in the client Workspace by creating the Monitor and adding it to your client's Workspace when the client is instantiated. Here is an example:

  String key = "detroyKey";
  ParamSet ps = new ParamSet();
  ps.setParam("topic", "MYTOPIC.DESTROY");
  Monitor monitor = new Monitor("mycode.DestroyMonitor", ps);

  WorkspaceDef workspace = t3c.services.workspace().getWorkspace();

  workspace.addMonitor(key, monitor);
  workspace.store(key, "DummyValue");

Top of the page

Asynchronous client notification of disconnect

weblogic.common.T3Client
weblogic.common.DisconnectListener
weblogic.common.DisconnectEvent

WebLogic supports the notion that a T3Client should be able to receive notification of and act upon its own demise -- its disconnect from the WebLogic Server. T3Clients can listen for disconnect events that are the result of a soft or idle disconnect timeout.

You can set up tasks to be executed after a disconnect event occurs, and then you can add the T3Client as a listener for its disconnect event. When a client disconnects or is disconnected from the WebLogic Server, all objects (that is, T3Clients) registered as disconnect listeners will be notified asynchronously. If you try to operate on a disconnected client, the client will throw a T3Exception, "T3Client not connected."

You write code that specifies a set of post-disconnect tasks by implementing the interface weblogic.common.DisconnectListener, which contains a constructor and a single method, disconnectOccurred. The constructor for this class takes a single argument -- an Object -- that is the T3Client itself. Here is a simple example of a class that implements this interface to print out the reason for the disconnect:

class cleanUp implements DisconnectListener {

 public cleanUp(Object source) {
   super(source);
 }

 public void disconnectOccurred(DisconnectEvent de) {
   System.out.println("Disconnect reason: " + de.getReason());
 }
}

In your T3Client application, all you must do to initiate your cleanup class is register your T3Client as listening for "cleanUp" -- the class you wrote. Your T3Client is added to objects listening for a disconnect event with the method T3Client.addDisconnectListener(). For example, here is a snippet of code that illustrates this:

  T3Client t3 = new T3Client(t3://localhost:7001);
  t3.addDisconnectListener(new cleanUp(this));

Note that the addDisconnectListener() method takes a single argument -- a class that implements the interface weblogic.common.DisconnectListener -- and the constructor for that class takes as its argument the T3Client object itself ("this").

There is a simple example of how this works in the examples shipped with the distribution, in examples/t3client/timeout.java. The accompanying class timeoutCallBack.java is the implementation of DisconnectListener used as the argument to the T3Client.addDisconnectListener method.

Top of the page

Setting application-specific properties

The weblogic.properties file is only accessible by WebLogic; that is, you can't add application-specific properties to the weblogic.properties file and expect that they will be read at startup time. However, you can set properties for your own application by creating a separate properties file. This file can be created and used in two ways:

  • Put your application-specific properties file in the same directory as your weblogic.properties file. You can then use the following code to access the properties:
    
     Properties props = null;
     String propertiesName = "myapp.properties";
    
     T3ServicesDef services = 
        T3Services.getT3Services();
     String location = 
        services.config().getProperty("weblogic.system.home") +
        java.io.File.separator + propertiesName;
     props = 
        props.load(new DataInputStream(new FileInputStream(location)));
    

  • Put your application-specific properties file in your WebLogic Server classpath . You must specify this on the command line when you start WebLogic Server using the weblogic.class.path property. (If you are using Microsoft Jview, set this on the command line with the /cp option, or include it in your CLASSPATH environment variable.) For more information, see Setting classpath.

    You can then use the following code to access the properties:

     Properties props = null;
     String propertiesName = "myapp.properties";
     InputStream in = 
        this.getClass().getResourceAsStream(propertiesName);
     props = props.load(in);

Top of the page

Using ParamSets, ParamValue, and ParamTypes in WebLogic

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

Several WebLogic APIs use parameters for customization, refining choices, passing initialization arguments, and passing parameters for execution. For such tasks, WebLogic uses a single, common object called a ParamSet, made up of ParamValues.

A parameter is a name=value pair, like SMTPhost="smtp.best.com". The name of a parameter is its keyname, and all ParamSet contents are accessible by keyname. For each keyname in a ParamSet, you set a corresponding ParamValue.

The setParam() methods in the ParamSet class have a rich set of scalars that allow you to set the data type of the ParamValue for each ParamSet key. An additional utility class, ParamTypes, has a rich set of scalars that allow you to declare a particular data type for each ParamValue.

A ParamSet may be made up of a vector of ParamSets, and a keyname can be associated with a vector of ParamValues. There are additional methods, like getParam(String, int) and the setParam(String, int, type) methods, that allow you to get and set the ParamSet keys and ParamValues associated with a vector.

The ParamValue class has methods for determining a ParamValue's data type and casting one data type as another. A ParamValue has a data type; if a ParamValue is created without specifying the data type, its data type is set to ParamTypes.UNKNOWN.

Constants for possible data types are contained in weblogic.common.ParamTypes.

Conversions among the various datatypes are handled automatically in a "Java" way, i.e., the conversion can be accomplished either of these ways:

  • With a cast. For example, for float to int, you might use:
      float f = 1.2;
      int i = (int) f;
  • By using some java.* method for the conversion. For example, you might use:
      boolean b = Boolean.booleanValue("t");

Illegal conversions (for example, int to boolean) throw a ParamSetException.

A ParamValue may be made up of a vector of ParamValues. The ParamValues that make up a vector of ParamValues are accessible by index. Use the elementAt() method to return the ParamValue at the nth position of a vector of ParamValues.

Use the getParam() method to get the ParamValue in a ParamSet that matches a particular keyname. You can also use the getNames() method to get all the keynames in a ParamSet. The toString(), print(), dump(), and display() methods offer a variety of display options for viewing the contents of a ParamSet.

Setting up a ParamSets may be as simple as setting a few parameters to values based on command-line arguments, as is illustrated in this example:

  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]);

Although constructing a ParamSet of name/value pairs is a simple operation, there is an underlying complexity in the ParamSet and ParamValue classes that allow you to set up very complex relationships of ParamSets and ParamValues if necessary. For example, a ParamSet may be a vector of ParamSets. Here is an example of how you might declare and construct a vector of ParamSets:

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

The user 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);
  }

There are some efficiency considerations when using ParamSets and the objects that they qualify. For example, when using ParamSets with EventMessages, it is neither required nor desirable to create a new EventMessage and its associated ParamSet each time you want to submit an event for a particular topic.

This code snippet, which creates a new ParamSet and EventMessage for each submission, will generate 100 ParamSets, about 300 ParamValues (since two ParamValues are added automatically by EventMessage.submit()), 100 events, and will make 100 ParamValue lookups in the ParamSet:

  for (int i = 0; i < 100; i++) {
    ps = new ParamSet();
    EventMessageDef em = t3.services.events()
                           .getEventMessage(topic, ps);
    ps.setParam("number", i);
    em.submit();
  }
It is more efficient to create a ParamSet and an EventMessage as instance variables in the class, and then modify them and resubmit them as necessary. This example will generate 1 ParamSet, 3 ParamValues, 1 Event, and will make 100 ParamValue lookups in the ParamSet:
  ps = new ParamSet();
  EventMessageDef em = t3.services.events()
                         .getEventMessage(topic, ps);

  for (int i = 0; i < 100; i++) {
    ps.setParam("number", i);
    String status = em.submit();
  }
The most efficient approach is to make a reference to the underlying ParamValue and set it repeatedly. This example shows how you can use this approach to prevent multiple ParamValue lookups for the counter "number":
  ps = new ParamSet();
  ParamValue num = ps.getParam("number");
  EventMessageDef em = t3.services.events()
                         .getEventMessage(topic, ps);

  for (int i = 0; i < 100; i++) {
    num.set(i);
    String status = em.submit();
  }
The last code snippet will generate 1 ParamSet, 3 ParamValues, 1 Event, and will make 1 ParamValue lookup in the ParamSet.

Events and ParamSets are serially reusable, but they are not threadsafe, that is, you can reuse them but not concurrently in multiple threads. To make the same code snippet multithread safe, for example, we would wrap the Event submission in a synchronized block:

  ps = new ParamSet();
  ParamValue num = ps.getParam("number");
  EventMessageDef em = t3.services.events()
                         .getEventMessage(topic, ps);

  for (int i = 0; i < 100; i++) {
    synchronized (em) {
      num.set(i);
      em.submit();
    }
  }
Note that although you must create the new ParamSet before you request the new EventMessage (since the ParamSet object is used in the getEventMessage() method), it is not necessary to call the ParamSet.setValue() method until the instant before the Event.submit() method is called (or register() method in the case of Evaluate and Action constructors). It is only when submit() or register() is called that the ParamSet is actually examined.

Top of the page

Workspace hooks

Workspace hooks were deprecated in Release 3.0. Instead, WebLogic now supports Workspace Monitors, a more flexible, more powerful model that is detailed in the Using WebLogic Workspaces Developers Guide.

Top of the page

Change history

Release 3.0 -- 1/29/98

Added WebLogic Time services.

Release 2.5 -- 8/23/97

Moved workspace functionality from the T3Client class and the weblogic.common.WorkspaceServicesDef to the weblogic.workspace.common.WorkspaceDef. Also moved the documentation for workspaces into its own document, Using WebLogic Workspaces.

 

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 04/20/1999