Java Bootstrap Object Programming Reference

 

This topic includes the following sections:

• How Bootstrap Objects Work

• Types of Remote Clients Supported

• Capabilities and Limitations

• Bootstrap Object API. This section describes:

  • Tobj Module

  • Java Mapping

• Programming Examples. The following examples are provided:

  • Getting a SecurityCurrent Object

  • Getting a UserTransaction Object

 

---

Why Bootstrap Objects Are Needed

The Problem: To communicate with BEA WebLogic Enterprise objects, a client application must obtain object references. The client application uses the Bootstrap object to obtain initial object references to six key objects in a BEA WebLogic Enterprise domain:

• FactoryFinder-used to locate factory objects

• SecurityCurrent-used to log on to the system

• TransactionCurrent-used to manage transactions

• InterfaceRepository-used to obtain information about available interfaces

• NotificationService-used to locate Notification Service channel factory objects

• Tobj_SimpleEventsService-used to locate BEA Simple Events Service channel factory objects

However, this poses a problem: How does the client application access the Bootstrap object?

The solution: Bootstrap objects are local programming objects, not remote CORBA objects, in both the client and the server. When Bootstrap objects are created, their constructor requires the network address of a BEA WebLogic Enterprise IIOP Server Listener/Handler. Given this information, the Bootstrap object can generate object references for the above-mentioned remote objects in the BEA WebLogic Enterprise domain. These object references can then be used to access services available in the BEA WebLogic Enterprise domain.

 

---

How Bootstrap Objects Work

Bootstrap objects are created by a client or a server application that must access object references to the following objects:

• SecurityCurrent

• TransactionCurrent

• FactoryFinder

• InterfaceRepository

• NotificationService

• Tobj_SimpleEventsService

Bootstrap objects may represent the first connection to a specific BEA WebLogic Enterprise domain depending on the format of the IIOP Server Listener/Handler address. If the Null scheme Universal Resource Locator (URL) format is used (the only address format supported in releases of BEA WebLogic Enterprise prior to V5.1), the Bootstrap objects represent the first connection. However, if the URL format is used, the connection will not occur until after Bootstrap object creation. For more information on address formats and connection times, refer to the description of Tobj_Bootstrap in the Java API Reference, which is included in the Javadoc online documentation.

For a BEA WebLogic Enterprise remote client, the Bootstrap object is created with the host and the port for the BEA WebLogic Enterprise IIOP Server Listener/Handler. However, for BEA WebLogic Enterprise native client and server applications, there is no need to specify a host and port because they execute in a specific BEA WebLogic Enterprise domain. The IIOP Server Listener/Handler host and the port ID are included in the BEA WebLogic Enterprise domain configuration information.

After they are created, Bootstrap objects satisfy requests for object references for objects in a particular BEA WebLogic Enterprise domain. Different Bootstrap objects allow the application to use multiple domains.

Using the Bootstrap object, you can obtain six different references, as follows:

• SecurityCurrent

  The SecurityCurrent object is used to establish a security context within a BEA WebLogic Enterprise domain. The client can then obtain the PrincipalAuthenticator from the principal_authenticator attribute of the SecurityCurrent object.

• TransactionCurrent

  The TransactionCurrent object is used to participate in a BEA WebLogic Enterprise transaction. The basic operations are as follows:

  • Begin

    Begin a transaction. Future operations take place within the scope of this transaction.

  • Commit

    End the transaction. All operations on this client application have completed successfully.

  • Roll back

    Abort the transaction. Tell all other participants to roll back.

  • Suspend

    Suspend participation in the current transaction. This operation returns an object that identifies the transaction and allows the client application to resume the transaction later.

  • Resume

    Resume participation in the specified transaction.

• FactoryFinder

  The FactoryFinder object is used to obtain a factory. In the BEA WebLogic Enterprise system, factories are used to create application objects. The FactoryFinder provides the following different methods to find factories:

  • Get a list of all available factories that match a factory object reference (find_factories).

  • Get the factory that matches a name component consisting of id and kind (find_one_factory).

  • Get the first available factory of a specific kind (find_one_factory_by_id).

  • Get a list of all available factories of a specific kind (find_factories_by_id).

  • Get a list of all registered factories (list_factories).

• InterfaceRepository

  The Interface Repository contains the interface descriptions of the CORBA objects that are implemented within the BEA WebLogic Enterprise domain. Clients using the Dynamic Invocation Interface (DII) need a reference to the Interface Repository to be able to build CORBA request structures. The ActiveX Client is a special case of this. Internally, the implementation of the COM/IIOP Bridge uses DII, so it must get the reference to the Interface Repository, although this is transparent to the desktop client.

• NotificationService

  The NotificationService object is used to obtain a reference to the event channel factory (CosNotifyChannelAdmin::EventChannelFactory) in the CosNotification Service. In the BEA WebLogic Enterprise system, the EventChannelFactory is used to locate the Notification Service channel.

• Tobj_SimpleEventsService

  The Tobj_SimpleEventsService object is used to obtain a reference to the event channel factory (Tobj_SimpleEvents::ChannelFactory) in the BEA Simple Events Service. In the BEA WebLogic Enterprise system, the ChannelFactory is used to locate the BEA Simple Events Service channel.

The FactoryFinder and InterfaceRepository objects are not implemented in the environmental objects library. However, they are specific to a BEA WebLogic Enterprise domain and are thus conceptually similar to the SecurityCurrent and TransactionCurrent objects in use.

You can also invoke the following method on the Bootstrap object to return information needed by the client application:

• getUserTransaction

  This method returns the current transactional context object to the client application.

The Bootstrap object implies an association or "session" between the client application and the BEA WebLogic Enterprise domain. Within the context of this association, the Bootstrap object imposes a containment relationship with the other Current objects (or contained objects); that is, the SecurityCurrent and TransactionCurrent. Current objects are valid only for this domain and only while the Bootstrap object exists.

Note: Resolving the SecurityCurrent when using the new URL address format (corbaloc://hostname:port_number) is a local operation; that is, no connection is made by the client to the IIOP Server Listener/Handler.

In addition, a client can have only one instance of each of the Current objects at any time. If a Current object already exists, an attempt to create another Current object does not fail. Instead, another reference to the already existing object is handed out; that is, a client application may have more than one reference to the single instance of the Current object.

To create a new instance of a Current object, the application must first invoke the destroy_current method on the Bootstrap object. This invalidates all of the Current objects, but does not destroy the session with the BEA WebLogic Enterprise domain. After invoking the destroy_current method, new instances of the Current objects can be created within the BEA WebLogic Enterprise domain using the existing Bootstrap object.

To obtain Current objects for another domain, a different Bootstrap object must be constructed. Although it is possible to have multiple Bootstrap objects at one time, only one Bootstrap object may be "active;" that is, have Current objects associated with it. Thus, an application must first invoke the destroy_current method on the "active" Bootstrap object before obtaining new Current objects on another Bootstrap object, which then becomes the active Bootstrap object.

Servers and native clients are inside of the BEA WebLogic Enterprise domain; therefore, no "session" is established. However, the same containment relationships are enforced. Servers and native clients access the domain they are currently in by specifying an empty string, rather than //host:port.

Note: When you compile client and server applications, specify the -DTOBJADDR option to specify a host and port to be used at run time, which allows for more flexibility and portability in client and server application code. For more information, see Creating CORBA Client Applications and Creating CORBA Java Server Applications.

Note: Client and server applications must use the com.beasys.Tobj_Bootstrap.resolve_initial_references method, not the org.omg.CORBA.ORB.resolve_initial_references method.

 

---

Types of Remote Clients Supported

Table 4-1 shows the types of remote clients that can use the Bootstrap object to access the other environmental objects, such as FactoryFinder, SecurityCurrent, TransactionCurrent, and InterfaceRepository.

Table 4-1 Remote Clients Supported

Client	Description
CORBA C++	CORBA C++ client applications use the BEA WebLogic Enterprise C++ environmental objects to access the CORBA objects in a BEA WebLogic Enterprise domain, and the BEA WebLogic Enterprise Object Request Broker (ORB) to process from CORBA objects. Use the BEA WebLogic Enterprise system development commands to build these client applications (see Commands, System Processes, and MIB Reference).
CORBA Java	CORBA Java client applications use the Java environmental objects to access CORBA objects in a BEA WebLogic Enterprise domain. However, these client applications use an ORB product other than the BEA WebLogic Enterprise ORB to process requests from CORBA objects. These client applications are built using the ORB product's Java development tools. The Java core system of the BEA WebLogic Enterprise software supports interoperability with client platforms using of the following: The Java IDL ORB provided with the Java Development Kit 1.2 from Sun Microsystems, Inc. For complete details about Java application and applet support, see the Release Notes.
ActiveX	Use the BEA WebLogic Enterprise Automation environmental objects to access CORBA objects in a BEA WebLogic Enterprise domain, and the ActiveX Client to process requests from CORBA objects. Use the Application Builder to create bindings for CORBA objects so that they can be accessed from ActiveX client applications, which are built using a development tool such as Microsoft Visual Basic, Delphi, or PowerBuilder.

This container describes how to use the Bootstrap object with Java client applications. For reference information about how to use the Bootstrap object in C++ and ActiveX client applications, see the CORBA C++ Programming Reference.

 

---

Capabilities and Limitations

Bootstrap objects have the following capabilities and limitations:

• Multiple Bootstrap objects can coexist in a client application, although only one Bootstrap object can own the Current objects (Transaction and Security) at one time. Client applications must invoke the destroy_current method on the Bootstrap object associated with one domain before obtaining the Current objects on another domain. Although it is possible to have multiple Bootstrap objects that establish connections to different BEA WebLogic Enterprise domains, only one set of Current objects is valid. Attempts to obtain other Current objects without destroying the existing Current objects fail.

• Method invocations to any BEA WebLogic Enterprise domain other than the domain that provides the valid SecurityCurrent object fail and return an org.omg.CORBA.NO_PERMISSION exception.

• Method invocations to any BEA WebLogic Enterprise domain other than the domain that provides the valid TransactionCurrent object do not execute within the scope of a transaction.

• The transaction and security objects returned by the Bootstrap objects are BEA implementations of the Current objects. If other ("native") Current objects are present in the environment, they are ignored.

 

---

Bootstrap Object API

The Bootstrap object application programming interface (API) is described in the Java API Reference in the Javadoc online documentation. The sections that follow describe:

• The object references returned by the Bootstrap object

• The Java mapping for the Bootstrap object

Tobj Module

Table 4-2 shows the object reference that is returned for each type ID.

Table 4-2 Returned Object References

ID	Returned Object Reference
FactoryFinder	FactoryFinder object (com.beasys.Tobj.FactoryFinder)
InterfaceRepository	InterfaceRepository object (org.omg.CORBA.Repository)
SecurityCurrent	SecurityCurrent object (org.omg.SecurityLevel2.Current)
TransactionCurrent	OTS Current object (com.beasys.Tobj.TransactionCurrent)
NotificationService	EventChannelFactory object (CosNotifyChannelAdmin.EventChannelFactory)
Tobj_SimpleEventsService	BEA Simple Events ChannelFactory object (Tobj_SimpleEvents.ChannelFactory)

Table 4-3 describes the Tobj module exceptions.

Table 4-3 Tobj Module Exceptions

Exception	Description
com.beasys.Tobj. InvalidName	Raised if id is not one of the names specified in Table 4-2. On the server, the resolve_initial_references method also raises com.beasys.Tobj.InvalidName when SecurityCurrent is passed.
com.beasys.Tobj. InvalidDomain	On the server application, raised if the BEA WebLogic Enterprise server environment is not booted.
org.omg.CORBA. NO_PERMISSION	Raised if id is TransactionCurrent or SecurityCurrent and another Bootstrap object in the client owns the Current objects.
org.omg.CORBA. BAD_PARAM	Raised for the register_callback_port method if the object is null or if the hostname contained in the object does not match the connection.
org.omg.CORBA. IMP_LIMIT	Raised if the register_callback_port method is invoked more than once.

Java Mapping

Listing 4-1 shows the Tobj_Bootstrap.java mapping.

Listing 4-1 Tobj_Bootstrap.java Mapping

---

package com.beasys;

public class Tobj_Bootstrap {
       public Tobj_Bootstrap(org.omg.CORBA.ORB orb,
                               String address_str)
              throws org.omg.CORBA.SystemException;
public class Tobj_Bootstrap {
      public Tobj_Bootstrap(org.omg.CORBA.ORB orb, 
                               String address_str,
                               java.applet.Applet applet)
              throws org.omg.CORBA.SystemException;

public void register_callback_port(orb.omg.CORBA.Object objref)
               throws org.omg.CORBA.SystemException;

public org.omg.CORBA.Object
                    resolve_initial_references(String id)
              throws Tobj.InvalidName,
                      org.omg.CORBA.SystemException;
public void destroy_current()
              throws org.omg.CORBA.SystemException;
}

---

 

---

Programming Examples

This section provides the following Java client programming examples that use Bootstrap objects.

• Getting a SecurityCurrent Object

• Getting a UserTransaction Object

Getting a SecurityCurrent Object

Listing 4-2 shows how to program a Java client to get a SecurityCurrent object.

Listing 4-2 Programming a Java Client to Get a SecurityCurrent Object

---

import java.util.*;
import org.omg.CORBA.*;
import com.beasys.*;
class client {
      public static void main(String[] args)
      {
               Properties prop = null; 
               Tobj.PrincipalAuthenticator auth = null; 
               String host_port = "//COLORMAGIC:10000"; 
               // Set host and port. 
               if (args.length == 1) host_port = args[0];
               try {
                    // Initialize ORB
                    ORB orb = ORB.init(args, prop);
                    // Create Bootstrap object
                    Tobj_Bootstrap bs=new  Tobj_Bootstrap(orb,host_port);

                    // Get security current
                    org.omg.CORBA.Object ocur =
                          bs.resolve_initial_references("SecurityCurrent");
                    SecurityLevel2.Current cur = 
                          SecurityLevel2.CurrentHelper.narrow(ocur);
              }
              catch (Tobj.InvalidName e) {
                 System.out.println("Invalid name: "+e);
                 System.exit(1);
              }
              catch (Tobj.InvalidDomain e) {
                      System.out.println("Invalid domain address: "+host_port +" "+e);
                 System.exit(1);
              }
              catch (SystemException e) {
                 System.out.println("Exception getting security current: "+e);
                 e.printStackTrace();
                 System.exit(1);
              }
        }
}

---

Getting a UserTransaction Object

Listing 4-3 shows using the Bootstrap object to get the UserTransaction object, which may then be used to begin and terminate transactions and get information about transactions.

Listing 4-3 Programming a Java Client to Get a UserTransaction Object

---

Properties prop = null; 
Tobj.PrincipalAuthenticator auth = null; 
String host_port = "//COLORMAGIC:10000"; 
// Set host and port. 
if (args.length == 1) host_port = args[0];
try {
// Initialize ORB
   orb = ORB.init(args, prop);

// Create Bootstrap Object
   bs = new Tobj_Bootstrap(orb, host_port);

javax.transaction.UserTransaction ucur = bs.getUserTransaction();

ucur.begin();
/* Make transactional calls from client to server */
   ucur.commit();

---