![]() |
![]() |
![]() |
![]() |
![]() |
• 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.The SecurityCurrent object is used to establish a security context within an Oracle Tuxedo domain. The client can then obtain the PrincipalAuthenticator from the principal_authenticator attribute of the SecurityCurrent object.
•
•
•
•
•
• 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).
•
•
•
•
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.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: 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.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
• 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 Oracle Tuxedo domains, only one set of Current objects is valid. Attempts to obtain other Current objects without destroying the existing Current objects fail.
• Table 4‑2 shows the object reference that is returned for each type ID.
Table 4‑2 Returned Object References FactoryFinder object (Tobj::FactoryFinder) InterfaceRepository object (CORBA::Repository) CORBA Naming Service (Tobj::NameService) (CosNotifyChannelAdmin::
EventChannelFactory) SecurityCurrent object (SecurityLevel2::Current) OTS Current object (Tobj::TransactionCurrent) Oracle Simple Events
ChannelFactory object (Tobj_SimpleEvents::
ChannelFactory)Table 4‑3 describes the Tobj module exceptions.
Table 4‑3 Tobj Module Exceptions 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. Raised if id is TransactionCurrent or SecurityCurrent and another Bootstrap object in the client owns the Current objects. Raised if the register_callback_port method is called more than once.Listing 4‑1 shows the C++ declarations in the Tobj_bootstrap.h file.Listing 4‑1 Tobj_boostrap.h Declarationsclass 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( );
};Listing 4‑2shows the Tobj_Bootstrap.java mapping.Listing 4‑2 Tobj_Bootstrap.java Mappingpublic void register_callback_port(orb.omg.CORBA.Object objref)
throws org.omg.CORBA.SystemException;Listing 4‑3 shows Automation Bootstrap interface mapping.Listing 4‑3 Automation (Dual) Bootstrap Interface MappingA pointer to the ORB object in the client. The Bootstrap object uses the string_to_object method of orb internally.
Note: For remote clients, address specifies the network address of an IIOP Listener/Handler through which client applications gain access to an Oracle Tuxedo domain.“//hostname:port_number”
“//#.#.#.#:port_number”
“corbaloc://hostname:port_number”
“corbalocs://hostname:port_number”In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS). The hostname must be the remote machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the remote machine.
Note: In the second format, the #.#.#.# is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the remote machine.In both the first and second formats, port_number is the TCP port number at which the domain process listens for incoming requests. The port_number should be a number between 0 and 65535.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: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.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.
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. 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:corbalocs://curly:1024,corbaloc://larry:1111,
corbalocs://ctxobj:3434,mthd:3434,corbaloc://force:1111In 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.For a native client, the address parameter in the Tobj_Bootstrap constructor must always be an empty string (not a NULL pointer). The native client connects to the application that is specified in the TUXCONFIG environment variable. The constructor raises CORBA::BAD_PARAM if the address is not empty.When servers need access to the Bootstrap object, they should obtain a reference to it using the TP framework by invoking TP.bootstrap(). Servers should not attempt to create a new instance of the Bootstrap object.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.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.Raised if the register_callback_port method is called more than once.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.
• If the register_callback_port method is not invoked by the joint client/server, the callback port is not registered with the ISH and the server defaults to Asymmetric Outbound IIOP. In this case, you must start the server’s IIOP Listener (ISL) with the -O option. The -O option enables Asymmetric outbound IIOP; otherwise, server-to-client invocations will not be allowed by the ISL/ISH.
• If you are using the OracleWrapper Callbacks API instead of the POA and you want to use bidirectional behavior, you always need to invoke the register_callback_port method, even when you are using a ISH that supports GIOP 1.2.
• If you want to use bidirectional capability for a callback object, you must invoke the register_callback_port method before you pass the callback object reference to the server.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.Raised if id is TransactionCurrent or SecurityCurrent and another Bootstrap object in the client owns the Current objects.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.Raises CORBA::NO_PERMISSION if the Bootstrap object is not the owner of the Current objects.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.HRESULT Initialize(
[in] BSTR host);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.Table 4‑5 describes the exceptions.
Table 4‑5 Initialize Exceptions Unable to communicate with the Oracle Tuxedo domain at the address specified or TOBJADDR is not defined. Table 4‑6 describes the exceptions.
Table 4‑6 CreateObject Exceptions If the progid specifies a transaction or security current and another Bootstrap object in the client owns the current objects. The progid specified is not valid. The requested progid is not one of the valid parameter values specified above. The requested progid is not registered on your system. CoCreate Instance() failed 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‘Connect to the Oracle Tuxedo Domain
oBootstrap.Initialize “//host:port”‘Get the FactoryFinder for the Oracle Tuxedo Domain
Set oBSFactoryFinder = oBootstrap.CreateObject(“Tobj.FactoryFinder”)Table 4‑7 shows the object reference that is returned for each type ID.
Table 4‑7 Returned Object References FactoryFinder object (CORBA::FactoryFinder) InterfaceRepository object (CORBA::Repository) CORBA Naming Service object (CORBA::NameService) (CosNotifyChannelAdmin::EventChannelFactory) POACurrent object (CORBA::POACurrent) PrincipalAuthenticator object (SecurityLevel2::PrincipalAuthenticator) RootPOA object (CORBA::RootPOA) Oracle Simple Events ChannelFactory object (Tobj_SimpleEvents::ChannelFactory)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.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.
• Oracle 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.
• Oracle 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.
Note: The new URL string formats may also be passed to the ORB::string_to_object function.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.Table 4‑8 lists the BNF syntax for each URLs element.
Table 4‑8 BNF Format for URL Elements Table 4‑9 describes each URL element.
Table 4‑9 Descriptions of URL Elements 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. 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.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.
Table 4‑10 BNF Syntax for URL 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. For a description of obj_addr_list, see Table 4‑9. For a description of obj_addr_list, see Table 4‑9. For a description of key_string, see Table 4‑9. For a description of string_name, see Table 4‑9.
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.
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.// utility to get the registrar
static UniversityW::Registrar_ptr get_registrar(
CORBA::ORB_ptr orb
)
{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.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.
1. Use ORB::resolve_initial_references to get a FactoryFinder.
4. From the Control object returned from the create operation, use the get_terminator method to get the transaction terminator interface.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.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