com.beasys
Class Tobj_Bootstrap

java.lang.Object
  |
  +--com.beasys.Tobj_Bootstrap
public class Tobj_Bootstrap
extends java.lang.Object

Tobj_Bootstrap is the only class visible to the user.

Constructor Summary
Tobj_Bootstrap(org.omg.CORBA.ORB orb, java.lang.String address_str)
          This class creates the Bootstrap object for applications.
Tobj_Bootstrap(org.omg.CORBA.ORB orb, java.lang.String address_str, java.applet.Applet applet)
          This class creates the Bootstrap object for applets.
 
Method Summary
 void destroy_current()
          Destroys the Current objects for the domain represented by the Bootstrap object.
static java.util.Properties getNativeProperties()
           
static java.util.Properties getRemoteProperties()
           
 UserTransaction getUserTransaction()
          Acquires a reference to a UserTransaction object, which may then be used to begin and terminate transactions, and get information about transactions.
 void register_callback_port(org.omg.CORBA.Object objref)
          Registers the joint client/server listening port in the IIOP Handler (ISH).
 org.omg.CORBA.Object resolve_initial_references(java.lang.String id)
          Acquires CORBA object references for the FactoryFinder, SecurityCurrent, TransactionCurrent, NotificationService, Tobj_SimpleEventsService, and InterfaceRepository objects.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Tobj_Bootstrap

public Tobj_Bootstrap(org.omg.CORBA.ORB orb,
                      java.lang.String address_str)
               throws org.omg.CORBA.SystemException,
                      InvalidDomain
This class creates the Bootstrap object for applications. The constructor throws the org.omg.CORBA.BAD_PARAM exception if orb is null or if address is not in a valid format.
Parameters:
orb - A pointer to the ORB object in the client. The Bootstrap object uses the string_to_object method of orb internally.

address_str - The address of the BEA Tuxedo domain IIOP Listener/Handler. The address is specified differently, depending on the type of client. There can be three types of clients, as follows:

  • Remote Client

    For a description of the remote clients supported by BEA Tuxedo CORBA applications, see the Release Notes.

    For remote clients, the address specifies the network address of an IIOP Listener/Handler through which CORBA client applications gain access to a BEA 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 all of the above 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.

    One or more TCP/IP addresses can be specified. Multiple addresses are specified 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 BEA 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 BEA 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 BEA 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.

    BEA Tuxedo also supports random address selection. To used 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 Tuxedo application 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 BEA Tuxedo software randomly selects the invalid address, the BAD_PARAM exception is returned to the caller and the BEA Tuxedo software aborts the connection attempt.

    The third and fourth formats are called Uniform Resource Locator (URL) address formats. 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 (ISL/ISH) 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 connection time as corbaloc, but, additionally, the client application makes its initial connection to the ISL/ISH using the Secure Socket Layer (SSL) Protocol. The differences between to the two URL address formats is as follows:

    corbaloc: Invocations to the IIOP Listener/Handler are unprotected. Configuring the IIOP Listener/Handler for the SSL protocol is optional. A principal can secure the bootstrapping process by using the SecurityLevel2::Current::authenticate() 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 BEA 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 supported in version 4.2 of the WLE product.

    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. Here 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 WLE version 5.0 software extended the syntax to support a list of multiple URLs, each with a different scheme. Here 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 the online documentation.

    Note: The network address that is specified by programmers in the Bootstrap constructor 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
 tcpip-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 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 NT 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.

  • Native client

    Not supported.

  • Server acting as a client

    For a server, the address parameter in the Tobj_Bootstrap constructor must always be an empty string (not a null pointer). The server always connects to the application in which it is booted. The constructor raises the 

    org.omg.CORBA.BAD_PARAM
    exception if the address is not empty.

Throws:
org.omg.CORBA.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.

org.omg.CORBA.COMM_FAILURE - In the case of a deferred initial connection (using the corbaloc or corbalocs address scheme), the first call to resolve_initial_references() method can trigger the establishment of the initial connection to the BEA Tuxedo domain. If the initial connection cannot be established, this exception is thrown.

Tobj_Bootstrap

public Tobj_Bootstrap(org.omg.CORBA.ORB orb,
                      java.lang.String address_str,
                      java.applet.Applet applet)
               throws org.omg.CORBA.SystemException,
                      InvalidDomain
This class creates the Bootstrap object for applets. The constructor throws the org.omg.CORBA.BAD_PARAM exception if orb is null or if address is not in a valid format.
Parameters:
orb - This is a pointer to the ORB object in the client. The Bootstrap object uses the string_to_object method of orb internally.

address_str - The address of the BEA Tuxedo domain IIOP Listener/Handler. The address is specified differently depending on the type of client. There can be three types of clients, as follows:

  • Remote Client

    For a discussion of remote clients, see the description of the Bootstrap object for applications.

  • Native client

    Not supported.

  • Server acting as a client

    For a discussion of servers acting as clients, see the description of the Bootstrap object for applications.

    applet - 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.

Throws:
org.omg.CORBA.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. The address of the BEA Tuxedo domain IIOP Listener/Handler is specified in the constructor. The constructor is specific to the programming language. For a native client or server, this exception is raised if the domain is not booted.

org.omg.CORBA.COMM_FAILURE - In the case of a deferred initial connection (using the corbaloc or corbalocs address scheme), the first call to resolve_initial_references() method can trigger the establishment of the initial connection to the BEA Tuxedo domain. If the initial connection cannot be established, this exception is thrown.
Method Detail

resolve_initial_references

public org.omg.CORBA.Object resolve_initial_references(java.lang.String id)
                                                throws InvalidName,
                                                       org.omg.CORBA.SystemException
Acquires CORBA object references for the FactoryFinder, SecurityCurrent, TransactionCurrent, NotificationService, Tobj_SimpleEventsService, and InterfaceRepository objects. For the specific object reference, invoke the 
narrow
method. For example, for FactoryFinder, invoke the Tobj.FactoryFinder.narrow method.
Parameters:
id - This parameter must be one of the following: 

  •  "FactoryFinder"
 
  • 
 "SecurityCurrent"
 
  • 
 "TransactionCurrent"
 
  • 
 "InterfaceRepository"
 
  • 
 "NotificationService"
 
  • 
 "Tobj_SimpleEventsService"
Returns:
Object that corresponds to the specified type ID.
Throws:
InvalidName - Raised if id is not one of the names allowed (see id parameter). On the server, also raised when SecurityCurrent is passed.
NO_PERMISSION - this exception is raised if id is TransactionCurrent or SecurityCurrent and another Bootstrap object in the client owns the Current objects.

register_callback_port

public void register_callback_port(org.omg.CORBA.Object objref)
                            throws org.omg.CORBA.SystemException
Registers the joint client/server listening port in the IIOP Handler (ISH). This method is invoked 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 clients, the ISH only supports one listening port per joint client/server; therefore, the 
register_callback_port
method should only be invoked once per connected joint client/server.

Parameters:
objref - The object reference created by the joint client/server.

Throws:
org.omg.CORBA.BAD_PARAM - Raised if the object is nil or if the host contained in the object does not match the connection.

org.omg.CORBA.IMP_LIMIT - Raised if the 
register_callback_port
method is invoked more than once.

org.omg.CORBA.COMM_FAILURE - In the case of a deferred initial connection (using the corbaloc or corbalocs address scheme), the first call to resolve_initial_references() method can trigger the establishment of the initial connection to the BEA Tuxedo domain. If the initial connection cannot be established, this exception is thrown. Note: The following information must be given consideration when using this method:

  • 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 BEAWrapper 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.

destroy_current

public void destroy_current()
                     throws org.omg.CORBA.SystemException
Destroys the Current objects for the domain represented by the Bootstrap object. This method 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 
org.omg.CORBA.BAD_INV_ORDER
. Good programming practice is to release all Current objects before invoking the 
destroy_current
method.

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 the resolve_initial_references method for TransactionCurrent or SecurityCurrent on another domain; otherwise, the resolve_initial_references method raises the org.omg.CORBA.NO_PERMISSION exception.

Throws:
NO_PERMISSION - Raised if the Bootstrap object is not the owner of the Current objects.

getUserTransaction

public UserTransaction getUserTransaction()
                                   throws org.omg.CORBA.SystemException
Acquires a reference to a UserTransaction object, which may then be used to begin and terminate transactions, and get information about transactions. Note that an invocation to the getUserTransaction method has a side effect of invoking the 
resolve_initial_references("TransactionCurrent")
method on the corresponding Bootstrap object. An invocation of the 
destroy_current
method on the Bootstrap object would invalidate the UserTransaction object.
Returns:
Reference to a UserTransaction object.
Throws:
java.lang.IllegalStateException - Raised if another Bootstrap object in the client owns the Current objects.

org.omg.CORBA.COMM_FAILURE - In the case of a deferred initial connection (using the corbaloc or corbalocs address scheme), the first call to resolve_initial_references() method can trigger the establishment of the initial connection to the BEA Tuxedo domain. If the initial connection cannot be established, this exception is thrown.

getNativeProperties

public static java.util.Properties getNativeProperties()

getRemoteProperties

public static java.util.Properties getRemoteProperties()