CORBA Programming Reference

CORBA Bootstrapping Programming Reference

This topic includes the following sections:

• Why Bootstrapping Is Needed
• Supported Bootstrapping Mechanisms
• BEA Bootstrapping Mechanism
• Bootstrap Object API
• Bootstrap Object Programming Examples
• Interoperable Naming Service Bootstrapping Mechanism

Note: The BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported in Tuxedo 9.x. All BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB text references, associated code samples, etc. should only be used:

• to help implement/run third party Java ORB libraries, and
• for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. BEA Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

 

---

Why Bootstrapping Is Needed

To communicate with BEA Tuxedo objects, a client application must obtain object references. Without an object reference, there can be no communication. To solve this problem, client applications use a bootstrapping mechanism to obtain object references to objects in a BEA Tuxedo domain.

 

---

Supported Bootstrapping Mechanisms

In the Tuxedo 8.0 release and later, two bootstrapping mechanisms are supported:

• BEA Bootstrapping Mechanism

Use this mechanism if you using the BEA client ORB.

• Interoperable Naming Service Bootstrapping Mechanism

Use this mechanism if you using a client ORB from another vendor.

Note: The CORBA C++ client provided with BEA Tuxedo software may use the Interoperable Naming Service bootstrapping mechanism, however, for performance reasons, this is not recommended.

 

---

BEA Bootstrapping Mechanism

The BEA bootstrapping mechanism uses 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 BEA Tuxedo IIOP Listener/Handler. Given this information, the bootstrapping object can generate object references for the key remote objects in the BEA Tuxedo domain. These object references can then be used to access services available in the BEA Tuxedo domain.

How Bootstrap Objects Work

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

• FactoryFinder
• Security
• Interface Repository
• Naming Service
• Notification Service
• Tobj_SimpleEvents Service
• Transaction

Bootstrap objects may represent the first connection to a specific BEA Tuxedo domain depending on the format of the IIOP 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 version 5.1 and BEA Tuxedo release 8.0), the Bootstrap objects represent the first connection. However, if the URL format is used, the connection will not occur until after creation of the Bootstrap object. For more information on address formats and connection times, refer to Tobj_Bootstrap.

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

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

Using the Bootstrap object, you can obtain references to the following objects:

• SecurityCurrent

The SecurityCurrent object is used to establish a security context within a BEA Tuxedo 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 Tuxedo 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 Tuxedo 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 Tuxedo domain. Clients using the Dynamic Invocation Interface (DII) need a reference to the Interface Repository to be able to build CORBA request structures.

• NamingService

A NamingService object is used to obtain a reference to the root namespace. When you use this object, the ORB locates the root of the namespace.

• NotificationService

The NotificationService object is used to obtain a reference to the event channel factory (CosNotifyChannelAdmin::EventChannelFactory) in the CosNotification Service. In the BEA Tuxedo 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 Tuxedo system, the ChannelFactory is used to locate the BEA Simple Events Service channel.

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

The Bootstrap object implies an association or "session" between the client application and the BEA Tuxedo 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 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 Tuxedo domain. After invoking destroy_current(), new instances of the Current objects can be created within the BEA Tuxedo 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 destroy_current() on the "active" Bootstrap object before obtaining new Current objects on another Bootstrap object, which then becomes the active Bootstrap object.

Note: If you want to access objects in multiple domains, either import the object to the local domain or administratively configure your application access multiple domains. For more information on multi-domain configurations configurations, see "Configuring Multiple CORBA Domains" in Using the BEA Tuxedo Domains Component.

Servers and native clients are inside of the BEA Tuxedo 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 using the Bootstrap object, client and server applications must use the Tobj_Bootstrap::resolve_initial_references()method, not the ORB::resolve_initial_references() method.

Types of BEA 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. These clients are provided with the BEA Tuxedo CORBA software. Third-party client ORBs should use the CORBA Interoperable Naming Service.

Table 4-1 BEA Remote Clients Supported 

Client	Description
CORBA C++	CORBA C++ client applications use the BEA Tuxedo C++ environmental objects to access the CORBA objects in a BEA Tuxedo domain, and the BEA Tuxedo Object Request Broker (ORB) to process from CORBA objects. Use the BEA Tuxedo system development commands to build these client applications (see the BEA Tuxedo Command 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 destroy_current() 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 Tuxedo 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 Tuxedo domain that has security enabled other than the domain that provides the valid SecurityCurrent object will fail and return a CORBA::NO_PERMISSION exception.
• Method invocations to any BEA Tuxedo 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 first in terms of the OMG Interface Definition Language (IDL) (for portability), and then in C++. The C++ descriptions add the necessary constructor to build a Bootstrap object for a particular BEA Tuxedo domain.

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 for C++ Clients
FactoryFinder	FactoryFinder object (Tobj::FactoryFinder)
InterfaceRepository	InterfaceRepository object (CORBA::Repository)
NameService	CORBA Naming Service (Tobj::NameService)
NotificationService	EventChannelFactory object (CosNotifyChannelAdmin:: EventChannelFactory)
SecurityCurrent	SecurityCurrent object (SecurityLevel2::Current)
TransactionCurrent	OTS Current object (Tobj::TransactionCurrent)
Tobj_SimpleEventsService	BEA Simple Events ChannelFactory object (Tobj_SimpleEvents:: ChannelFactory)

 

Table 4-3 describes the Tobj module exceptions.

Table 4-3 Tobj Module Exceptions 

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

 

C++ Mapping

Listing 4-1 shows the C++ declarations in the Tobj_bootstrap.h file.

Listing 4-1 Tobj_boostrap.h Declarations

#include <CORBA.h>

class Tobj_Bootstrap {
public:
Tobj_Bootstrap(CORBA::ORB_ptr orb, const char* address);
CORBA::Object_ptr resolve_initial_references(
const char* id);
void register_callback_port(CORBA::Object_ptr objref);
void destroy_current( );
};

Java Mapping

Listing 4-2 shows the Tobj_Bootstrap.java mapping.

Listing 4-2 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;
}

Automation Mapping

Listing 4-3 shows Automation Bootstrap interface mapping.

Listing 4-3 Automation (Dual) Bootstrap Interface Mapping

interface DITobj_Bootstrap : IDispatch
{
     HRESULT Initialize(
               [in] BSTR address);

     HRESULT CreateObject(
              [in] BSTR progid,
               [out, retval] IDispatch** rtrn);

     HRESULT destroy_current();
};

C++ Member Functions

This section describes the C++ member functions supported by the BEA bootstrapping mechanism.