CORBA Programming Reference

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

CORBA Bootstrapping Programming Reference

This topic includes the following sections:

Note: The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported in Tuxedo 9.x. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, etc. should only be used:
Note: Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

 


Why Bootstrapping Is Needed

To communicate with Oracle 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 an Oracle Tuxedo domain.

 


Supported Bootstrapping Mechanisms

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

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

 


Oracle Bootstrapping Mechanism

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

Bootstrap objects may represent the first connection to a specific Oracle 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 Oracle WebLogic Enterprise prior to version 5.1 and Oracle 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 an Oracle Tuxedo CORBA remote client, Bootstrap objects are created with the host and the port for the Oracle Tuxedo IIOP Listener/Handler. However, for Oracle Tuxedo native client and server applications, there is no need to specify a host and port because they execute in a specific Oracle Tuxedo domain. The IIOP Listener/Handler host and the port ID are included in the Oracle Tuxedo domain configuration information.

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

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

The FactoryFinder and Interface Repository objects are not implemented in the environmental objects library. However, they are specific to an Oracle 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 Oracle 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 Oracle Tuxedo domain. After invoking destroy_current(), new instances of the Current objects can be created within the Oracle 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 Oracle Tuxedo Domains Component.

Servers and native clients are inside of the Oracle 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 Oracle 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 Oracle Tuxedo CORBA software. Third-party client ORBs should use the CORBA Interoperable Naming Service.

Table 4-1 Oracle Remote Clients Supported 
Client
Description
CORBA C++
CORBA C++ client applications use the Oracle Tuxedo C++ environmental objects to access the CORBA objects in an Oracle Tuxedo domain, and the Oracle Tuxedo Object Request Broker (ORB) to process from CORBA objects. Use the Oracle Tuxedo system development commands to build these client applications (see the Oracle Tuxedo Command Reference).

Capabilities and Limitations

Bootstrap objects have the following capabilities and limitations:

 


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 Oracle 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
Oracle 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 Oracle 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-2shows 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 Oracle bootstrapping mechanism.

 


Tobj_Bootstrap

Synopsis

The Bootstrap object constructor.

C++ Mapping

Tobj_Bootstrap(CORBA::ORB_ptr orb, const char* address);
throws Tobj::BAD_PARAM
org.omg.CORBA.SystemException;

Parameters

orb

A pointer to the ORB object in the client. The Bootstrap object uses the string_to_object method of orb internally.

address

The address of the Oracle Tuxedo domain IIOP Listener/Handler.
Note: Multiple Tobj_Bootstraps going to the same domain is not supported.
The address is specified differently depending on the type of client and the level of security required. There can be three types of clients, as follows:
//m1.acme:3050 //m1.acme:3050,//m2.acme:3050,//m3.acme:3051

If you specify multiple addresses, the Oracle Tuxedo software tries the addresses in order, left to right, until a connection is established. If a syntax error is detected in any of the addresses as it is being tried, a BAD_PARAM exception is returned to the caller immediately and the Oracle Tuxedo software aborts the attempt to make a connection. For example, if the first address in the comma-separated list shown above were //m1.3050, a syntax error would be detected and the attempt to make a connection would be aborted. If the Oracle Tuxedo software encounters the end of the address list before it tries an address that is valid, that is, a connection cannot be made to any of the addresses listed, the INVALID_DOMAIN exception is returned to the caller. If an exception other than INVALID_DOMAIN is raised, it is returned to the caller immediately.

Oracle Tuxedo also supports random address selection. To use random address selection, you can specify any member of an address list as a grouping of pipe-separated (|) network addresses enclosed in parentheses. For example:

(//m1.acme:3050|//m2.acme:3050),//m1.acme:7000

When you use this format, the Oracle Tuxedo system randomly selects one of the addresses enclosed in parentheses, either //m1.acme:3050 or //m2.acme:3050. If an exception other than INVALID_DOMAIN is raised, it is returned to the caller immediately. If a connection cannot be made to the address selected, the next element that follows the addresses enclosed in parentheses is attempted. If the end of the string is encountered before a connection can be made, the INVALID_DOMAIN exception is thrown to the caller.

Note: If you specify an address list in the following format:
Note: (//m1.acme:3050||//m2.acme:3050),//r1.acme:7000
Note: the NULL address in the pipe-separated list is considered invalid. If the Oracle Tuxedo software randomly selects the invalid address, the BAD_PARAM exception is returned to the caller and the Oracle Tuxedo software aborts the connection attempt.

The address string can be specified either in the TOBJADDR environment variable or in the address parameter of the Tobj_Bootstrap constructor.

For information about the TOBJADDR environment variable, see the section Managing Remote Client Applications in the Setting Up an Oracle Tuxedo Application. However, the address specified in Tobj_Bootstrap always take precedence over the TOBJADDR environment variable. To use the TOBJADDR environment variable to specify an address string, you must specify an empty string in the Tobj_Bootstrap address parameter.

Note: For C++ applications, TOBJADDR is an environment variable; for Java applications, it is a property; for Java applets, it is an HTML parameter.

The third and fourth formats are called Uniform Resource Locator (URL) address formats and were introduced in the Oracle WebLogic Enterprise version 5.1 release. As with the NULL scheme URL address format (//hostname:port_number), you use the URL address formats to specify the location of the IIOP Listener/Handler. However, when the corbaloc URL address format is used, the client application’s initial connection to the IIOP Listener/Handler is deferred until authentication of the principal’s, or client’s, identity or the first user initiated operation. Using the corbalocs URL address format has the same effect on the deferred connection time as corbaloc, but, additionally, the client application makes its initial connection to the ISL/ISH using the Secure Sockets Layer (SSL) protocol. Table 4-4 highlights the differences between the two URL address formats.

Table 4-4 Differences Between corbaloc and corbalocs URL Address Formats 
URL Address Formats
Differences in Mode of Operation
corbaloc
Invocations to the IIOP Listener/Handler are unprotected. Configuring the IIOP Listener/Handler for the SSL protocol is optional.

Note: A principal can secure the bootstrapping process by using the SecurityLevel2::Current::authenticate() operation to specify that certificate-based authentication is to be used.

corbalocs
Invocations to the IIOP Listener/Handler are protected and the IIOP Listener/Handler or the server ORB must be configured to enable the use of the SSL protocol.

These URL address formats are a subset of the definition of object URLs adopted by the OMG as part of the Interoperable Naming Service submission. The Oracle Tuxedo software also extends the URL format described in the OMG Interoperable Naming Service submission to support a secure form that is modeled after the URL for secure HTTP, as well as to support the randomize functionality that was added in the Oracle WebLogic Enterprise version 4.2.

The corbaloc and corbalocs URL schemes provide locations that are easily manipulated in both TCP/IP and DNS centric environments. These URL schemes contain a DNS-style hostname or IP address and a port_number. The following are some examples of the URL formats:

corbaloc://curly:1024,larry:1022,joe:1999
corbalocs://host1:1024,{host2:1022|host3:1999}
As an enhancement to the URL syntax described in the OMG Interoperable Naming Service submission, the Oracle WebLogic Enterprise version 5.1 software extended the syntax to support a list of multiple URLs, each with a different scheme. The following are some examples of the extension:
corbalocs://curly:1024,corbaloc://larry:1111,
corbalocs://ctxobj:3434,mthd:3434,corbaloc://force:1111

In the above example, if the parser reaches the URL corbaloc://force:1111, it resets its internal state as if it had never attempted secure connections and then begins attempting unprotected connections.

Caution: Do not mix the use of NULL scheme URL addresses (//hostname:port_number) with corbaloc and corbalocs URL addresses.
Note: The Bootstrap object supplied for use with the Netscape embedded Java ORB and JavaSoft JDK ORB does not support corbaloc and corbalocs URLs.
Note: For more information on using the corbaloc and corbalocs URL address formats, see Using Security in CORBA Applications.
Note: The network address that is specified in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the server application's UBBCONFIG file, both the address as well as the capitalization. If the addresses do not match, the invocation to the Bootstrap constructor will fail with the following seemingly unrelated error message:

ERROR: Unofficial connection from client at
<tcp/ip address>/<port-number>

For example, if the network address is specified (using the NULL URL address format) as //TRIXIE:3500 in the ISL command-line option string in the server application's UBBCONFIG file, specifying either //192.12.4.6:3500 or //trixie:3500 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail. On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows systems, see the host system's network settings in the Control Panel to determine the correct capitalization.
Note: The error in the previous note is deferred when the URL address format is used, that is, the error does not occur at the time of Bootstrap object construction because the connection to the ISL/ISH is deferred until later.

applet (Applies to Java method only)

This is a pointer to the client applet. If the client applet does not explicitly pass the ISH host and port to the Bootstrap constructor, you can pass this argument, which causes the Bootstrap object to search for the TOBJADDR definition in the HTML file for the applet.

Exception

BAD_PARAM

Raised if the object is nil or if the host contained in the object does not match the connection or the host address (//hostname:port_number) is not in a valid format.

Description

A C++ member function (or Java method) that creates Bootstrap objects.

Return Values

A pointer to a newly created Bootstrap object.

 


Tobj_Bootstrap::register_callback_port

Synopsis

Registers the joint client/server’s listening port in IIOP Handler (ISH).

C++ Mapping

void register_callback_port(CORBA::Object_ptr objref);

Parameter

objref

The object reference created by the joint client/server.

Exceptions

BAD_PARAM

Raised if the object is nil or if the host contained in the object does not match the connection.

IMP_LIMIT

Raised if the register_callback_port method is called more than once.

Description

This C++ member function (or Java method) is called to notify the ISH of a listening port in the joint client/server. This method should only be used for joint client/server ORBs that do not support GIOP 1.2 bidirectional capabilities (that is GIOP 1.0 and 1.1 client ORBs). For GIOP 1.0 and 1.1, the ISH supports only one listening port per joint client/server; therefore, the register_callback_port method should only be called once per connected joint client/server.

Usage Notes

The following information must be given consideration when using this method:

Return Values

None.

 


Tobj_Bootstrap::resolve_initial_references

Synopsis

Acquires CORBA object references.

C++ Mapping

CORBA::Object_ptr resolve_initial_references(
const char* id);
throws Tobj::InvalidName,
org.omg.CORBA.SystemException;

Parameter

id

This parameter must be one of the following:

“FactoryFinder”
“InterfaceRepository”
“NameService”
“NotificationService”
“SecurityCurrent”
“TransactionCurrent”
“Tobj_SimpleEventsService”

Exceptions

InvalidName

Raised if id is not one of the names specified above. On the server, resolve_initial_references also raises Tobj::InvalidName when SecurityCurrent is passed.

CORBA::NO_PERMISSION

Raised if id is TransactionCurrent or SecurityCurrent and another Bootstrap object in the client owns the Current objects.

Description

This C++ member function (or Java method) acquires CORBA object references for the FactoryFinder, SecurityCurrent, TransactionCurrent, NotificationService, Tobj_SimpleEventsService, and InterfaceRepository objects. For the specific object reference, invoke the _narrow function. For example, for FactoryFinder, invoke Tobj::FactoryFinder::_narrow.

Return Values

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

 


Tobj_Bootstrap::destroy_current()

Synopsis

Destroys the Current objects for the domain represented by the Bootstrap object.

C++ Mapping

void destroy_current();

Exception

Raises CORBA::NO_PERMISSION if the Bootstrap object is not the owner of the Current objects.

Description

This C++ member function invalidates the Current objects for the domain represented by the Bootstrap object. After invoking the destroy_current() method, the Current objects are marked as invalid. Any subsequent attempt to use the old Current objects will throw the exception CORBA::BAD_INV_ORDER. Good programming practice is to release all Current objects before invoking destroy_current().

Note: The destroy_current() method must be invoked on the Bootstrap object for the domain that currently owns the two Current objects (Transaction and Security). This also results in an implicit invocation to logoff for security and implicitly rolls back any transaction that was begun by the client.

The application must invoke destroy_current() before invoking resolve_initial_references for TransactionCurrent or SecurityCurrent on another domain; otherwise, resolve_initial_references raises CORBA::NO_PERMISSION.

Return Values

None.

Java Methods

The Java Oracle bootstrapping API supports the following methods:

Automation Methods

This section describes the Automation methods supported by the Oracle bootstrapping mechanism.

 


Initialize

Synopsis

Initializes the Bootstrap object into an Oracle Tuxedo domain.

MIDL Mapping

HRESULT Initialize(
[in] BSTR host);

Automation Mapping

Sub Initialize(address As String)

Parameter

address

The host name and port of the Oracle Tuxedo domain IIOP Listener/Handler. One or more TCP/IP addresses can be specified. Multiple addresses are specified using a comma-separated list, as in the C++ mappings. If no address is specified, the value of the TOBJADDR environmental variable is used.
Note: The network address that is specified in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the application's UBBCONFIG file, both the format of the address as well as the capitalization. If the addresses do not match, the invocation to the Bootstrap constructor will fail with the following seemingly unrelated error message:

ERROR: Unofficial connection from client at
<tcp/ip address>/<port-number>

For example, if the network address is specified as //TRIXIE:3500 in the ISL command-line option string, specifying either //192.12.4.6:3500 or //trixie:3500 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail. On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows systems, see the host system's network settings in the Control Panel to determine the correct capitalization.

Return Values

None.

Exceptions

Table 4-5 describes the exceptions.

Table 4-5 Initialize Exceptions
HRESULT
Description
Meaning
ITF_E_NO_PERMISSION_YES
Bootstrap already initialized
The Bootstrap object has already been initialized. To connect to a new Oracle Tuxedo domain, you must create a new Bootstrap object.
E_INVALIDARG
Invalid address parameter
The address supplied is not valid.
E_OUTOFMEMOY
Memory allocation failed
The required memory could not be allocated.
E_FAIL
Invalid domain
Unable to communicate with the Oracle Tuxedo domain at the address specified or TOBJADDR is not defined.
<SYSTEM ERROR>
Unable to obtain initial object
Unable to initialize the Bootstrap object. The system error causing the failure is returned in the "Number" member of the error object.

 


CreateObject

Synopsis

Creates an instance of a Current environmental object.

MIDL Mapping

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

Automation Mapping

Function CreateObject(progid As String) As Object	

Parameter

progid

The progid of the environmental object to create. Valid progids are:

Tobj.FactoryFinder
Tobj.SecurityCurrent
Tobj.TransactionCurrent

Return Value

A reference to the interface pointer of the created environmental object.

Exceptions

Table 4-6 describes the exceptions.

Table 4-6 CreateObject Exceptions 
Exception
Description
Meaning
ITF_E_NO_PERMISSION_YES
Bootstrap object must be initialized
The Bootstrap object has not been initialized.
ITF_E_NO_PERMISSION_NO
No permission
If the progid specifies a transaction or security current and another Bootstrap object in the client owns the current objects.
E_INVALIDARG
Invalid progid parameter
The progid specified is not valid.
E_INVALIDARG
Invalid name
The requested progid is not one of the valid parameter values specified above.
E_INVALIDARG
Unknown object
The requested progid is not registered on your system.
<SYSTEM ERROR>
CoCreate Instance() failed
The Bootstrap object could not create an instance of the requested object. The system error is returned in the "Number" member of the error object.

 


DestroyCurrent

Synopsis

Logs out of the Oracle Tuxedo domain and invalidates the TransactionCurrent and SecurityCurrent objects.

MIDL Mapping

HRESULT destroy_current();

Automation Mapping

Sub destroy_current()

Parameters

None.

Return Value

None.

Exceptions

None.

 


Bootstrap Object Programming Examples

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

Visual Basic Client Example: Using the Bootstrap Object

Listing 4-4 shows how to program a Visual Basic client to use the Bootstrap object.

Listing 4-4 Programming a Client in Visual Basic
‘Declare the Bootstrap object
Public oBootstrap As DITobj_Bootstrap
‘Declare the FactoryFinder object
Public oBsFactoryFinder As DITobj_FactoryFinder
‘Declare factory for Registrar object
Public oRegistrarFactory As DIUniversityB_RegistrarFactory
‘Declare actual Registrar object
Public oRegistrarFactory As DIUniversityB_RegistrarFactory
.... 
‘Create the Bootstrap object
Set oBootstrap = CreateObject(“Tobj.Bootstrap”)
‘Connect to the Oracle Tuxedo Domain
oBootstrap.Initialize “//host:port”
‘Get the FactoryFinder for the Oracle Tuxedo Domain
Set oBSFactoryFinder = oBootstrap.CreateObject(“Tobj.FactoryFinder”)
‘Get a factory for the Registrar object 
‘using the FactoryFinder method find_one_factory_by_id
Set oRegistrarFactory = oBSFactoryFinder.find_one_factory_by_id(“RegistrarFactoryID”)
'Create a Registrar object
Set oRegistrar = oRegistrarFactory.find_registrar(exc)

 


Interoperable Naming Service Bootstrapping Mechanism

This topic includes the following topics:

Introduction

As of release 8.0, the Oracle Tuxedo ORB supports the CORBA Naming Service bootstrapping mechanism (referred to in this document as the Interoperable Naming Service), as specified in Chapters 4 and 13 of the CORBA Specification revision 2.4.2.

This support enables ORBs that implement the Interoperable Naming Service (INS) bootstrapping mechanism to query the Oracle Tuxedo server-side ORB to get object references to initial objects such as FactoryFinder and to PrincipalAuthenticator to the Oracle Tuxedo environment. This support along with client support for interoperable initial object references enables clients to use the INS bootstrapping mechanism instead of the Oracle bootstrapping mechanism.

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

INS Object References

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

Table 4-7 Returned Object References 
ID
Returned Object Reference
FactoryFinder
FactoryFinder object (CORBA::FactoryFinder)
InterfaceRepository
InterfaceRepository object (CORBA::Repository)
NameService
CORBA Naming Service object (CORBA::NameService)
NotificationService
EventChannelFactory object
(CosNotifyChannelAdmin::EventChannelFactory)
POACurrent
POACurrent object (CORBA::POACurrent)
PrincipalAuthenticator
PrincipalAuthenticator object (SecurityLevel2::PrincipalAuthenticator)
RootPOA
RootPOA object (CORBA::RootPOA)
Tobj_SimpleEventsService
Oracle Simple Events ChannelFactory object (Tobj_SimpleEvents::ChannelFactory)

INS Command-line Options

As of release 8.0, Oracle Tuxedo CORBA supports the -ORBInitRef and -ORBDefaultInitRef command-line options. For a complete description of these options, see “ORB Initialization Member Function” on page 14-85.

The following example assumes an Oracle Tuxedo CORBA IIOP client is talking to an Oracle Tuxedo CORBA IIOP server environment:

client_app – ORBid BEA_IIOP – ORBInitRef
FactoryFinder=corbaloc::myhost:2468/FactoryFinder

Given this example, a call to ORB::resolve_initial_references for the FactoryFinder will result in an interoperable initial reference request being sent to the ISL/ISH on myhost at port 2468. Note that the case of myhost must exactly match the case of the host specified for the ISL/ISH in the tuxconfig file.

INS Initialization Operations

To use the INS bootstrapping mechanism, applications programmers must observe the following requirements:

INS Object URL Schemes

As of release 8.0, Oracle Tuxedo CORBA supports an additional Uniform Resource Locator (URL) format to be used for the specification of the location for access to an Oracle Tuxedo CORBA server environment and from where to retrieve references to initial object. The new URL format both follows and extends the definition of object URLs adopted by the OMG as part of the INS specification. The URL format described in the INS specification has also been extended to support a secure form modeled after the URL for secure HTTP, as well as the ability to support the randomize functionality initially provided in Oracle WebLogic Enterprise version 5.1.

The CORBA 2.4.2 specification requires that three object URL schemes must be supported by a compliant ORB. These schemes are defined as IOR, corbaloc, and corbaname.

Note: The new URL string formats may also be passed to the ORB::string_to_object function.

IOR URL Scheme

The IOR scheme takes the form of a string that is formatted as IOR:hex_octets. The scheme name is IOR and the text after the ‘:’ is defined in the CORBA specification. The IOR URL scheme is robust and insulates the client from the encapsulated transport information and object key used to reference the object.

corbaloc URL Scheme

It is difficult for humans to exchange IORs through nonelectronic means because of their lengths and the text encoding of binary information. The corbaloc and corbalocs URL schemes provide stringified object references in a format that is familiar to people and similar to the popular URL schemes of FTP and HTTP. The URL schemes defined for corbaloc and corbalocs are easily manipulated in both TCP/IP and DNS centric environments. The corbaloc and corbalocs URL contains:

By default, corbaloc URLs denote objects that can be contacted over IIOP, while corbalocs URLs denote objects that can be contacted using IIOP over SSL.

Table 4-8 lists the BNF syntax for each URLs element.

Table 4-8 BNF Format for URL Elements 
URL Element
BNF Format
<corbaloc>
= “corbaloc::”<obj_addr_list>[“/”<key_string>]
[,<corbaloc>|<corbalocs>]
<corbalocs>

= “corbalocs::”<obj_addr_list>[“/”<key_string>]
[,<corbaloc>|<corbalocs>]

<obj_addr_list>
= [<obj_addr> “,”]* <obj_addr>
<obj_addr>
= <iiop_prot_addr> | <future_prot_addr>
<iiop_prot_addr
= <iiop_id><iiop_addr>
<iiop_id>
= “//” | <iiop_prot_token>”:”
<iiop_prot_token>
= “iiop”
<iiop_addr>
= [<version> <host> [“:” <port>]]
<host>
= DNS-style Host Name | ip_address
<version>
= <major> “.” <minor> “@” | empty_string
<port>
= number
<major>
= number
<minor>
= number
<key_string>
= <string> | empty_string

Table 4-9 describes each URL element.

Table 4-9 Descriptions of URL Elements
URL Element
Description
obj_addr_list
A comma-separated list of protocol ID, version, and address information. This list is used in an implementation-defined manner to address the object. An object may be contacted by any of the addresses and protocols. If a failure occurs using the element, the next element in the comma-separated list will be used.
obj_addr
A protocol identifier, version tag, and a protocol specific address. The right-brace “{“, left-brace “}”, vertical bar “|”, slash “/”, and comma “,” characters are specifically prohibited in this component of the URL.
iiop_prot_addr
An IIOP protocol identifier, version tag, and address containing a DNS-style host name or IP address.
iiop_id
Tokens recognized to indicate an IIOP protocol corbaloc.
iiop_prot_token
An IIOP protocol token, “iiop”.
iiop_addr
A single address element.
host
A DNS-style host name or IP address. If not present, the local host is assumed.
version
A major and minor version number, separated by “.” and followed by “@”. If the version is absent, 1.0 is assumed.
ip_address
A numeric IP address (dotted decimal notation).
port
The port number an IIOP Listener/Handler or an initialization agent is listening on. The default is 9999.
key_string
A stringified object key that is not NULL-terminated. The key_string uses the escape conventions described in RFC 2396 to map away from octet values that cannot directly be part of a URL. US-ASCII alphanumeric characters are not escaped. Characters outside this range are escaped, except for the following:
“;” | “/” | “:” | “?” | “@” | “&” | “=” | “+” | “$” |
”,” | “-“ | “_” | “.” | “!” | “~” | “*” | “” | “(“ | “)”
The key_string corresponds to the octet sequence in the object_key member of a GIOP Request or LocateRequest header as defined in the CORBA specification.
string_name
A stringified name with URL escapes as defined in the Internet Engineering Task Force (IETF) RFC 2396. These escape rules insure that URLs can be transferred via a variety of transports without undergoing changes. US-ASCII alphanumeric characters are not escaped. Characters outside this range are escaped, except for the following:
“;” | “/” | “:” | “?” | “@” | “&” | “=” | “+” | “$” |
”,” | “-“ | “_” | “.” | “!” | “~” | “*” | “” | “(“ | “)”

The following are some examples of using the new URL format:

corbaloc::555xyz.com:1024,555backup.com:1022,555last.com:1999
corbalocs::555xyz.com:1024,{555backup.com:1022|555last.com:1999}
corbaloc::1.2@555xyz.com:1111
corbalocs::1.1@24.128.122.32:1011,1.0@24.128.122.34

As an enhancement to the URL syntax described in the INS submission, Oracle Tuxedo 8.0 or later has extended the syntax to support a list of multiple URLs, each with a different scheme. The following are some examples of the extension:

corbalocs::555xyz.com:1024,corbaloc::1.2@555xyz.com:1111
corbalocs::ctxobj:3434,mthd:3434,corbaloc::force:1111

In the above example, if the parser reaches the URL corbaloc::force.com:1111, it will reset its internal state as if it had never attempted secure connections and then begins attempting unprotected connections.

corbaname URL Scheme

The corbaname URL scheme extends the capabilities of the corbaloc scheme to allow URLs to denote entries in a Naming Service. Resolving corbaname URLs does not require a Naming Service implementation in the ORB core. An example of a corbaname URL is:

corbaname:555objs.com#a/string/path/to/obj

This URL specifies that at host 555objs.com, an object of type NamingContext (with an object key of NamingService) can be found, or alternatively, that an agent running at that location will return a reference to a NamingContext. The stringified name a/string/path/to/obj is then used as the argument to the resolve operation on that NamingContext.

A corbaname URL is similar to a corbaloc URL except that a corbaname URL also contains a stringified name that identifies a binding in a naming context. The # character denotes the start of the stringified name.

The BNF syntax for the URL is listed in Table 4-10.

Table 4-10 BNF Syntax for URL
URL Element
Format
Description
<corbaname>
= “corbaname:”<corbaloc_obj>[
“#”<string_name>]
corbaloc_obj is a portion of a corbaname URL that identifies the naming context. The syntax is identical to its use in a corbaloc URL.
<corbaloc_obj>
<obj_addr_list>[“/”<key_string>]
For a description of obj_addr_list, see Table 4-9.
<obj_addr_list>
As defined in a corbaloc URL
For a description of obj_addr_list, see Table 4-9.
<key_string>
As defined in a corbaloc URL
For a description of key_string, see Table 4-9.
<string_name>
Stringified Name | empty string
For a description of string_name, see Table 4-9.

Resolution of a corbaname URL is implemented as a simple extension to corbaloc URL processing. To illustrate the implementation, we will use the following corbaname URL:

corbaname:<corbaloc_obj>[“#”<string_name>]

The resolution process is as follows:

  1. Construct a corbaloc URL of the form corbaloc::<corbaloc_obj> from the corbaname URL.
  2. Convert the corbaloc URL to a naming context object reference by calling CORBA::ORB::string_to_object to obtain a CosNaming::NamingContext object.
  3. Convert <string_name> to a CosNaming::Name.
  4. Invoke the resolve operation on the CosNaming::NamingContext, passing the CosNaming::Name constructed.
  5. The object reference returned from CosNaming::NamingContext::resolve should be returned to the caller.

By following this resolution process, you eliminate the possibility of returning an object reference for a naming context that does not exist in the Naming Service. One side effect of this approach is that it requires that stubs for the Naming Service be part of the ORB core or that there be an internal mechanism for sending the request for the resolve operation. Because of the complexity, it is recommended that stubs for the Naming Service be embedded within the ORB core.

Getting a FactoryFinder Object Reference Using INS

Listing 4-6 shows an example of how a client application, using INS, gets an object reference to the FactoryFinder object. For a complete code example, see the client application in the University Sample.

Listing 4-5 Code Example for Getting the FactoryFinder Object
// utility to get the registrar
static UniversityW::Registrar_ptr get_registrar(
CORBA::ORB_ptr orb
)
{
    // Get the factory finder from the ORB:
CORBA::Object_var v_fact_finder_oref =
orb->resolve_initial_references("FactoryFinder");
    // Narrow the factory finder :
Tobj::FactoryFinder_var v_fact_finder_ref =
Tobj::FactoryFinder::_narrow(v_fact_finder_oref.in());
    // Use the factory finder to find the
// university's registrar factory :
CORBA::Object_var v_reg_fact_oref =
v_fact_finder_ref->find_one_factory_by_id(
UniversityW::_tc_RegistrarFactory->id()
);
    // Narrow the registrar factory :
UniversityW::RegistrarFactory_var v_reg_fact_ref =
UniversityW::RegistrarFactory::_narrow(
v_reg_fact_oref.in()
);
    // Return the university's registrar :
return v_reg_fact_ref->find_registrar();
}

Getting a PrincipalAuthenticator Object Reference Using INS

Listing 4-6 shows an example of how a client application, using INS, gets an object reference to the PrincipalAuthenticator object. For a complete code example, see the client application in the University Sample.

Listing 4-6 Code Example for Getting the PrincipalAuthenticator Object
// utility to log on to the security system
static SecurityLevel2::PrincipalAuthenticator_ptr logon(
CORBA::ORB_ptr orb,
const char* program_name,
UniversityW::StudentId stu_id
)
{
    // Get a Principal Authenticator directly from the ORB:
CORBA::Object_var v_pa_obj =
orb->resolve_initial_references("PrincipalAuthenticator");
    // Narrow the Principal Authenticator :
SecurityLevel2::PrincipalAuthenticator_var v_pa =
SecurityLevel2::PrincipalAuthenticator::_narrow(
v_pa_obj.in());

Getting a TransactionFactory Object Reference Using INS

As of release 8.0, Oracle Tuxedo CORBA supports the use of the CORBA Transaction Service Interface for beginning transactions. Using the ORB::resolve_initial_references(“FactoryFinder”) function, a client gets an object reference to a FactoryFinder. The client then uses the FactoryFinder to get a reference to a TransactionFactory, that it in turn uses to create (begin) a transaction.

Listing 4-7 shows an example of how a client application, using INS, gets an object reference to the TransactionFactory object. For a complete code example, see the client application in the University Sample.

Listing 4-7 Code Example for a Client Application That Uses INS
// Get the factory finder from the ORB:
CORBA::Object_var v_fact_finder_oref =
orb->resolve_initial_references("FactoryFinder");
// Narrow the factory finder :
Tobj::FactoryFinder_var v_fact_finder_ref =
Tobj::FactoryFinder::_narrow(v_fact_finder_oref.in());
// Get the TransactionFactory from the FactoryFinder
CORBA::Object_var v_txn_fac_oref =
v_fact_finder_ref->find_one_factory_by_id(
"IDL:omg.org/CosTransactions/TransactionFactory:1.0");
// Narrow the TransactionFactory object reference
CosTransactions::TransactionFactory_var v_txn_fac_ref =
CosTransactions::TransactionFactory::_narrow(
v_txn_fac_oref.in());

The sequence of events using the INS bootstrapping mechanism is as follows:

  1. Use ORB::resolve_initial_references to get a FactoryFinder.
  2. Use the FactoryFinder to get a TransactionFactory.
  3. Use the create operation on TransactionFactory to begin a transaction.
  4. From the Control object returned from the create operation, use the get_terminator method to get the transaction terminator interface.
  5. Use the commit or rollback operation on the terminator to end or abort the transaction.

The TransactionFactory returns objects that adhere to the standard CORBA Transaction Service interfaces instead of the Oracle delegated interfaces. This means that a third party ORB can use their ORB’s resolve_initial_references function to get a reference to a TransactionFactory from an Oracle Tuxedo CORBA server and use stubs generated from standard OMG IDL to act on the instances returned.

Restrictions

For the Oracle Tuxedo 8.0 release or later, the actions of the TransactionFactory and the client’s Current are not coordinated. This means that clients should use one mechanism or the other to control and get status about transactions, not both. Also, only the interfaces and operations listed in Table 4-11 are supported. The other operations, as described in the OMG IDL, return the CORBA::NO_IMPLEMENT exception.

Table 4-11 Supported INS Interfaces and Operations 
Interface
Supported Operations
TransactionFactory
create
Control
get_terminator
get_coordinator
Terminator
commit
rollback
Coordinator
get_status
rollback_only
get_transaction_name


  Back to Top       Previous  Next