Parameters

4.4.5.1.3 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:

Remote client

For a description of the remote clients supported by Oracle Tuxedo CORBA, see the section Types of Oracle Remote Clients Supported.

For remote clients, address specifies the network address of an IIOP Listener/Handler through which client applications gain access to an Oracle Tuxedo domain.

The address may be specified in either of the following formats:

“//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:

The hostname must begin with a letter character.

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.

You can specify one or more TCP/IP addresses. You specify multiple addresses using a comma-separated list. For example:

//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: (//m1.acme:3050||//m2.acme:3050),//r1.acme:7000 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 Oracle Tuxedo Application Configuration Guide . 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. The following table 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.

For more information on using the corbaloc and corbalocs URL address formats, see Using Security in CORBA Applications.

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:

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

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.

Native client
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.
Server acting as a client
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.

Parent topic: Tobj_Bootstrap