BEA WebLogic Enterprise 4.2    Developer Center     

        HOME   |   SITE MAP   |   SEARCH   |   CONTACT   |   GLOSSARY  |   PDF FILES |   WHAT'S NEW 
 
        JAVA REFERENCE    |   TABLE OF CONTENTS   |   PREVIOUS TOPIC   |   NEXT TOPIC  

Bootstrap Object


This chapter contains the following topics:

To communicate with WebLogic Enterprise objects, a client application must obtain object references. The client application uses the Bootstrap object to obtain initial object references to four key objects in a WebLogic Enterprise domain: the FactoryFinder (which is used to locate factory objects), SecurityCurrent (which is used to log on to the system), TransactionCurrent (which is used to manage transactions), and the Interface Repository (which is used to obtain information about available interfaces). However, this poses a problem: How does the client application access the Bootstrap object?

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 WebLogic Enterprise IIOP Server Listener/Handler. Given this information, the Bootstrap object can generate object references for the above-mentioned remote objects in the WebLogic Enterprise domain. These object references can then be used to access services available in the 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:

In addition, you can use the Bootstrap object to return information needed by the client application; for example, information needed to initialize the client ORB.

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

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

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

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

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

The Bootstrap object implies an association or "session" between the client application and the 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.

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 will not destroy the session with the WebLogic Enterprise domain. After invoking the destroy_current method, new instances of the Current objects can be created within the 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 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 by specifying //host:port. (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 Client Applications and Creating Java Server Applications.) 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

Remote Client Description

CORBA C++

CORBA C++ client applications use the WebLogic Enterprise C++ environmental objects to access the CORBA objects in a WebLogic Enterprise domain, and the WebLogic Enterprise Object Request Broker (ORB) to process from CORBA objects. Use the WebLogic Enterprise system development commands to build these client applications (see Chapter 10, "Java Development and Administration Commands").

CORBA Java

CORBA Java client applications use the Java environmental objects to access CORBA objects in a WebLogic Enterprise domain. However, these client applications use an ORB product other than the 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 WebLogic Enterprise software supports interoperability with client platforms using either of the following:

ActiveX

Use the WebLogic Enterprise Automation environmental objects to access CORBA objects in a 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. ActiveX client applications are built using a development tool such as Visual Basic, Delphi, or PowerBuilder.

This chapter 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 C++ Programming Reference.

Capabilities and Limitations

Bootstrap objects have the following capabilities and limitations:

Bootstrap Object API

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

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)

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 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 host 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)
throws org.omg.CORBA.SystemException;
public class Tobj_Bootstrap {
public Tobj_Bootstrap(org.omg.CORBA.ORB orb, String address,
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 Java client programming examples that use Bootstrap objects.

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)
{
Bool is_native=true;
Properties = prop;
Tobj.PrincipalAuthenticator auth = null;
if (args.length != 1)
is_native=false

if (is_native) {
/* Native Client */
prop = Tobj_Bootstrap.getNativeProperties();
host_port = "";
} else {
/* Remote Client */
prop = Tobj_Bootstrap.getRemoteProperties();
// Set host and port.
host_port = "//COLORMAGIC:10000";
}
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

The following code example 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
if (is_native){
/* Native Client */
prop = Tobj_Bootstrap.getNativeProperties();
host_port = null;
} else {
/* Remote Client */
prop = Tobj_Bootstrap.getRemoteProperties();
// Set host and port.
host_port = "//COLORMAGIC:10000";
}

// 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();


Copyright © 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: July 01, 1999.