BEA Logo BEA WebLogic Server Release 5.0

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

Using WebLogic's distributed server-side Beans

I. Introduction
Overview of WebLogic Beans
WebLogic Bean architecture

WebLogic Bean API reference
Overview of the WebLogic Bean API

III. Implementating with WebLogic Beans
Converting a JavaBean to a WebLogic Bean
Using the WebLogic Bean API

IV. Change history

Other related documents
Installing WebLogic (non-Windows)
Installing WebLogic (Windows)
Writing a WebLogic client application
Developers Guides
API Reference Manual


Note: The WebLogic Beans API has been deprecated in favor of the standard Enterprise Java Bean model. See BEA WebLogic Server Enterprise JavaBeans.

Overview of WebLogic Beans

A WebLogic Bean is a distributed object model for JavaBean-based component application development. WebLogic Beans are based on the semantics of JavaSoft's JavaBean architecture and are one of the services hosted within WebLogic.

A WebLogic Bean is a symmetric distributed object -- that is, the client-stub and server-skeleton are identical. A WebLogic Bean client has no notion of server location or address. Given a server-side (non-GUI) JavaBean, a WebLogic Bean with equivalent functionality -- but differently partitioned -- can be instantiated. Like JavaBeans, WebLogic Beans can fire events and service method invocations; however, WebLogic Beans can operate as distributed objects across multiple JVMs.

WebLogic Beans allow the delay of application partitioning between client and server until deployment -- "just-in-time-partitioning." WebLogic Beans also provide a simple approach to building and debugging distributed applications.

WebLogic Beans provide the environment for distributed JavaBean behavior that is not handled in the JavaBean specification. The WebLogic environment allows you to control the deployment, runtime behavior, and location of a WebLogic Bean. The multiplexed, bidirectional, asynchronous communications that is the standard communications method between WebLogic Server and T3Client provides efficient, asynchronous message delivery and WebLogic Bean event notification.

Like a JavaBean, a WebLogic Bean has a set of properties it exposes, a set of methods it allows other WebLogic Beans to call, and a set of events that it fires. However, unlike a JavaBean, a WebLogic Bean may operate in a distributed environment as an impl with multiple clients; the impl may exist on the WebLogic Server or in a T3Client; and the impl may migrate to a client, and vice versa.

JavaBeans are distributed with classes, resources, signatures, and manifest contained with a JAR file. WebLogic analyzes a JAR file, determines which classes are JavaBeans, promotes them to WebLogic Beans, and generates a new JAR file that contains the WebLogic Beans. This involves rewriting the manifest, removing signatures, and creating a new JAR file.

Benefits of WebLogic Beans:

  • Solves problems of writing distributed applications, by providing an automated way of partitioning an application operating under well-known semantics (JavaBeans). Produces applets and applications functionally identical to those produced from straight JavaBeans, except that WebLogic Bean applets and applications are differently partitioned. Partitioning of distributed applications is a large factor in application performance, and debugging distributed applications is tedious and error-prone. With WebLogic Beans, distributed objects can be exported from both T3Clients and WebLogic Servers.
  • Provides "hot-pluggable" business logic.
  • Provides load-balancing, through runtime migration of WebLogic Beans. A WebLogic Bean impl may migrate to any of its stubs and vice versa.
  • Extends standard JavaBean event notification to support cross-JVM event service for JavaBeans.
  • Supports asynchronous notification of clients, which is not truly supported by either CORBA or RMI.
  • Provides an agent technology that moves code to data through runtime migration and/or deploy-time configuration.
  • Supports distributed, parallel computations.
  • Makes possible an easy transformation of third-party JavaBeans into distributed WebLogic Beans.
  • Raises the level of development above the transport layer, by depending upon and extending the sophisticated services of WebLogic.


WebLogic Bean architecture

There are three subsystems contained within WebLogic's distributed Bean environment:

  • The WebLogic Bean server framework. A WebLogic Bean operates within WebLogic; it takes advantage of the WebLogic Server's efficient communications and resource management, that makes available all of the other integrated WebLogic Server services and facilities to every WebLogic application.
  • WebLogic Bean code generator. Given a JavaBean, the WebLogic Bean generator generates a WebLogic Bean (which we also call a "T3Bean"), which is an extension to a JavaBean and which uses Bean introspection to create calls to the framework's transport layer. A WebLogic Bean's transport layer depends upon WebLogic's WebLogic Events for message delivery and event notification. A WebLogic Bean exports the same contract as its source JavaBean and transparently replaces its parent JavaBean in an application. WebLogic Beans follow the JavaBean specification completely, so a WebLogic Bean can be used directly within a strictly compliant JavaBean builder tool.
  • WebLogic Bean API. The WebLogic Bean API describes the operations that can be performed on a generated WebLogic Bean. The API is described further in the next section.


WebLogic Bean API Reference Guide

Package weblogic.beans.common
Package weblogic.beans.reflector

Class java.lang.Object
  Class weblogic.beans.common.ClientEnumeration
   (implements java.util.Enumeration,
  Class weblogic.beans.reflector.Reference
  Class weblogic.beans.reflector.Reflector
  Interface weblogic.beans.common.RegistrationDef
  Class java.beans.SimpleBeanInfo
   (implements java.beans.BeanInfo)
      Class weblogic.beans.reflector.ReflectorBeanInfo
  Interface weblogic.beans.common.T3Bean
  Class weblogic.beans.common.T3BeanMsg
   (implements weblogic.common.internal.WLSerializable)
  Interface weblogic.beans.common.T3BeanServicesDef
  Interface weblogic.beans.common.T3BeanTransportDef
  Class java.lang.Throwable (implements
    Class java.lang.Exception
       Class weblogic.beans.common.AlreadyImplementedException
       Class weblogic.beans.common.NotImplementedException
       Class weblogic.beans.common.UnbindException


Overview of the WebLogic Bean API


After you generate a WebLogic Bean from a serverside JavaBean, you operate on the WebLogic Bean with methods from the weblogic.beans.common package. The object itself is called a T3Bean.

The methods in the interface weblogic.beans.common.T3Bean provide ways to bind and unbind impls of WebLogic Beans. A WebLogic Bean must always have one (and only one) impl, and may have one or more clients (stubs). The WebLogic Bean impl must be bound to a name; the name is used by clients to find the impl and use it. You use the bind() methods in the T3Bean interface to create clients of an impl, which may exist on the WebLogic Server, or on a T3Client. When you bind a WebLogic Bean (T3Bean), you use the arg impl=true/false/try as part of the URL, to specify whether you explicitly want to create a T3Bean impl (true), or not to create a T3Bean impl but to create a client (false). Either of these will cause an Exception if you try to create a client without an impl, or if you try to create an impl when one already exists bound to that name. Using the arg try creates an impl if there is none, otherwise creates a client.

The interface weblogic.beans.common.T3BeanServicesDef gives T3Clients access to WebLogic Bean services within the WebLogic Server Framework. Methods in this interface allow you to find clients and implementations, and to migrate the implementation to a new destination; this enables runtime partitioning of the application.

You will also be interested in methods in the class weblogic.beans.common.ClientEnumeration. A ClientEnumeration is the collection of clients for any particular T3Bean impl. With methods in this class, you can enumerate through the clients of an impl.

The three exceptions in this package, weblogic.beans.common.NotImplementedException, and weblogic.beans.common.UnbindException and weblogic.beans.common.AlreadyImplementedException handle exceptions for WebLogic Beans, specifically when you attempt to become a client of a WebLogic Bean that has no impl, to unbind an impl while there are still clients, or to become an impl when one already exists.


Implementing with WebLogic Beans

This section details step-by-step instructions for making a WebLogic Bean, given a serverside, non-GUI JavaBean.
Converting a JavaBean to a WebLogic Bean
Step 1. Check your JavaBean
Step 2. Compile
Step 3. Install the class files
Step 4. Start the WebLogic Server and the WebLogic Bean
Using the WebLogic Bean API

Converting a JavaBean to a WebLogic Bean

Step 1. Check your JavaBean

Before converting a JavaBean to a WebLogic Bean, you will need to make sure that your JavaBean is suitable for conversion. Here are the guidelines:
  • Your JavaBean must be a serverside, non-GUI Bean. If you think about the Bean in client/server terms, your JavaBean must be the backend portion of your application.
  • Your JavaBean properties must be design-time properties. That is, your JavaBean can't have properties that are set at runtime.
  • All of the Objects used by your JavaBean, such as Events, Exceptions, returns or arguments for methods, must be serializable, either with or with weblogic.common.WLSerializable.
  • Your Bean must have a BeanInfo class that properly designates methods, properties, and events, without overlap.


Step 2. Compile

  1. First, compile the JavaBean and its BeanInfo.

Here is an example command that compiles a JavaBean and its associated BeanInfo classes. Note that we use the -d option to direct the generated class files into the WebLogic classes. You should direct your class files into the directory that is appropriate for your application, and the directory should of course be in your CLASSPATH.

  $ javac -d /weblogic/classes
  1. Second, run the WebLogic Bean code generator on the resulting JavaBean class files.

You call the WebLogic Bean compiler with the command java weblogic.beanc, plus the full package name of the JavaBean. We also recommend that you explicitly supply your CLASSPATH with the -classpath flag, and the destination directory for the compiled files with the -d flag. Here is an example. We have broken it over more than one line for readability and space. The command should be entered on a single line.

 $ java weblogic.beanc 
      -d /weblogic/classes
      -classpath /java/java117/lib/;/weblogic/classes

You can use the same options with the WebLogic Bean code generator as you use with WebLogic RMI. For example, you can set the -keepgenerated or -verbose options.


Step 3. Install the class files

You will have at least these files compiled as a result of the javac command:

  • BeanName.class
  • BeanNameBeanInfo.class
There may be other classes that make up the JavaBean. All these class files should also be compiled.

The WebLogic Bean compiler generates three new class files, as shown here:

  • T3BeanName.class
  • T3BeanNameMsg.class
  • T3BeanNameBeanInfo.class
and usually at least one T3BeanName$T3BeanNameListener.class.

All of the original JavaBean classes as well as the generated WebLogic Bean classes must be installed on both the WebLogic Server and the host for the T3Client to run the application. (If you elect to run the Bean as an applet, the necessary classes will be downloaded over the wire.)

Install these classes in the proper package-directory hierarchy in the WebLogic Server's CLASSPATH.


Step 4. Start the WebLogic Server and the WebLogic Bean

There are two ways to start a WebLogic Bean. One is by running T3BeanName from the command line. The other is by registering T3BeanName as a startup class in the WebLogic Server's file, so that the class is started automatically with the WebLogic Server.

Running the WebLogic Bean from the command line

  1. Start the WebLogic Server.
  1. Start T3BeanName with the URL of the WebLogic Server and the name you to which you want to bind this particular instance. Each of your clients/stubs will need to use this name to find the impl.

For example, here is a command (it should all go on one command-line) to start a T3BeanName class on a WebLogic Server listening on port 7001, from the WebLogic Server's NT host:

 $ java T3BeanName
    t3://localhost:7001 MyBean

Running the WebLogic Bean as a WebLogic Server startup class

You can also register the WebLogic Bean class as a startup class in the file, so that an impl of the WebLogic Bean is automatically started with the WebLogic Server. If you want to use this method, follow these steps:
  1. Register the WebLogic Bean as a startup class in the WebLogic Server's file.
# weblogic.system.startupClass.ExampleBean=T3BeanName
# weblogic.system.startupArgs.ExampleBean=name=MyBean
Here we register the full package name of the WebLogic Bean as a startup class, and supply a single startup argument, a name, which corresponds to the name by which the impl will be registered in the WebLogic Server
  1. Start the WebLogic Server.

If you have enableConsole set to true, you will see a notice that the WebLogic Bean was loaded, something like this:

Thu Jun 30 13:20:48 PDT 1999:<I> <Config>
[weblogic.system.startupArgs 0=[ExampleBean=name=MyBean ]
2=[ExampleBean=name=MyBean ]]


Using the WebLogic Bean API

Includes methods for binding to and unbinding from an implementation of the WebLogic Bean (T3Bean)
Defines what WebLogic Bean-related services are available to a T3Client through its services reference. These include methods to find the implementation and its clients, and to migrate the implementation.

Classes in the weblogic.beans.common package allow you to operate on the WebLogic Bean at runtime. One of the most powerful features of WebLogic Beans is its ability to move the implementation of a WebLogic Bean around at runtime, which allows your application on-demand partitioning. You may begin with a distributed WebLogic Bean running in a T3Client, and then move it to another client or to the WebLogic Server as demands on the application change.

These tutorial examples show how to use the WebLogic Bean API.


Simple WebLogic Bean management

Here we use a simple WebLogic Bean that does nothing more than ping the WebLogic Server to show several WebLogic Bean management tasks like creating a WebLogic Bean, binding and unbinding it, getting client addresses of a WebLogic Bean's clients', finding a WebLogic Bean, and migrating the implementation of a WebLogic Bean.

First, we connect a T3Client to the WebLogic Server, and then create a new WebLogic Bean -- "T3Ping" -- and bind it to the name "Ping." The T3Ping bean should have been loaded as a startup class in the WebLogic Server; this bean becomes a client of the implementation running on the WebLogic Server by setting the "impl" argument in the URL to "false".

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

  T3Ping t3b = new T3Ping();

Then we ping the WebLogic Server a few times, just for fun.

  for (int i = 0; i < 10; i++) {;

Here is the interesting work. First, we'll illustrate how to get the original implementation address, and then we show how to enumerate through the list of "Ping"'s clients to find this client's address. We use the T3Client's services reference to access WebLogic Bean-related services in the WebLogic Server, in this case the findImplementation() and findClients() methods.

  Address implAddress ="Ping");

  Enumeration e ="Ping");
  Address clientAddress = (Address) e.nextElement();

Now we move the implementation from its original location on the WebLogic Server, where it began its life as a startup class, to the copy that this T3Client is running. Just for fun, we'll exercise the ping a few times again from the implementation after we migrate it to the client."Ping", clientAddress);
  for (int i = 0; i < 10; i++) {;

Here we move the implementation from the client back to the WebLogic Server."Ping", implAddress);

And finally, we unbind this WebLogic Bean client and disconnect the T3Client.



Using a WebLogic Bean Reference

You can create a reference to a WebLogic Bean remotely, and then invoke on that reference, without ever calling the WebLogic Bean compiler on an object. WebLogic Bean uses reflection in this process. It's handy for creating serverside WebLogic Beans on the fly from a T3Client.

In this code snippet, we first create a T3Client and connect to the WebLogic Server.

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

First we bind this T3Client to a the reflection object in the WebLogic Server. The final boolean signifies that this is a client of the reflection object.

  T3Reflector reflector = new T3Reflector();
  reflector.bind(t3, "myserverReflector", false);

Now we create a reference to the WebLogic Bean so that we can operate on it, with a Reference object. You need to supply certain aspects of the object, like it is name, its class, parameter types, and parameters. The class name has to match the full package name of a WebLogic Bean that resides on the WebLogic Server.

  Reference test = reflector.create
    ("ReflectorTest", "weblogic.beans.jdbc.T3SQL",
     new String[] {}, new Object[] {} );

Then we can invoke a WebLogic Bean method on the bean, by using the invoke() method from the Reflector class, as shown here. The array of strings describes the types of parameters that the bind() method takes, and the array of objects are the matching values for those parameters. The bind() method invoked here is void bind(String name, boolean implementation); since there is a void return, we pass a null as the final argument to this method:

  reflector.invoke(test, "bind",
      new String[] {"java.lang.String", "boolean"},
      new Object[] {"ReflectorTest", new Boolean(true)},
Once you have bound the WebLogic Bean, you can create a client of it, as shown here:
  T3SQL sql = new T3SQL();
  sql.bind(t3, "ReflectorTest", false);

Then you operate on the WebLogic Bean as usual. For example, here we execute a select statement on the T3SQL WebLogic Bean, and then unbind the client when finished:

  sql.executeSQL("select * from emp");

After we no longer need the implementation, we unbind it as well, by invoking on the Reflector object. The unbind() method takes no arguments and has a void return:

  reflector.invoke(test, "unbind",
    new String[] {},
    new Object[] {},

Finally, we unbind the reflector and disconnect the T3Client from the WebLogic Server:



Change history

Release 4.5.1
Deprecated ChatServer example.

Release 3.0
No changes.

Release 2.5 -- 8/23/97


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 8/30/1999