CORBA Programming Reference

 

---

DestroyCurrent

Synopsis

Logs out of the BEA 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

Visual Basic Client Example: Using the Bootstrap Object

Listing 4-5 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 BEA Tuxedo Domain
oBootstrap.Initialize  "//host:port"

`Get the FactoryFinder for the BEA 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
• INS Object References
• INS Command-line Options
• INS Object URL Schemes
• Getting a FactoryFinder Object Reference Using INS
• Getting a PrincipalAuthenticator Object Reference Using INS
• Getting a TransactionFactory Object Reference Using INS

Introduction

As of release 8.0, the BEA 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 BEA Tuxedo server-side ORB to get object references to initial objects such as FactoryFinder and to PrincipalAuthenticator to the BEA Tuxedo environment. This support along with client support for interoperable initial object references enables clients to use the INS bootstrapping mechanism instead of the BEA bootstrapping mechanism.

Note: The CORBA C++ client provided with BEA 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.

 

INS Command-line Options

As of release 8.0, BEA 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 a BEA Tuxedo CORBA IIOP client is talking to a BEA 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:

• BEA Tuxedo CORBA IIOP clients that want to use the INS initial reference mechanism must now call ORB::resolve_initial_references function, instead of the Tobj_Bootstrap::resolve_initial_references function. For a syntactical description of ORB::resolve_initial_references, see "CORBA::ORB::resolve_initial_references" on page 14-79.

Note: The Tobj_Bootstrap API is still supported and its behavior has not changed.

• BEA Tuxedo CORBA IIOP clients using the INS initial reference mechanism should use the ORB::list_initial_services function instead of the Tobj_Bootstrap::list_initial_services function. For a syntactical description of ORB::list_initial_services, see "CORBA::ORB::list_initial_services" on page 14-75.

INS Object URL Schemes

As of release 8.0, BEA Tuxedo CORBA supports an additional Uniform Resource Locator (URL) format to be used for the specification of the location for access to a BEA 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 BEA 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:

• DNS-style host name or IP address and port
• The version of the IIOP protocol to be used (optional)
• An object key (optional)

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-9 describes each URL element.

 

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, BEA 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.

 

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:

Construct a corbaloc URL of the form corbaloc::<corbaloc_obj> from the corbaname URL.
Convert the corbaloc URL to a naming context object reference by calling CORBA::ORB::string_to_object to obtain a CosNaming::NamingContext object.
Convert <string_name> to a CosNaming::Name.
Invoke the resolve operation on the CosNaming::NamingContext, passing the CosNaming::Name constructed.
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-7 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, BEA 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-8 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:

Use ORB::resolve_initial_references to get a FactoryFinder.
Use the FactoryFinder to get a TransactionFactory.
Use the create operation on TransactionFactory to begin a transaction.
From the Control object returned from the create operation, use the get_terminator method to get the transaction terminator interface.
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 BEA 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 a BEA Tuxedo CORBA server and use stubs generated from standard OMG IDL to act on the instances returned.

Restrictions

For the BEA 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.

 

Contact BEA |  Feedback |  Privacy  |