com.beasys
Class Tobj_Bootstrap

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

The Tobj_Bootstrap class establishes communication between a client application and a WLE domain. This class also obtains object references for the other environmental objects in the WLE domain, such as the FactoryFinder, the Interface Repository, the SecurityCurrent object, and the TransactionCurrent object.

Constructor Summary
Tobj_Bootstrap(org.omg.CORBA.ORB orb, java.lang.String address_str)
          This method creates the Bootstrap object.
Tobj_Bootstrap(org.omg.CORBA.ORB orb, java.lang.String address_str, java.applet.Applet applet)
          This method creates the Bootstrap object.
 
Method Summary
 void destroy_current()
          Destroys the Current objects for the domain represented by the Bootstrap object.
static java.util.Properties getNativeProperties()
          Returns a set of properties that need to be passed in a subsequent invocation of the org.omg.CORBA.ORB.init method.
static java.util.Properties getRemoteProperties()
          Returns the properties needed to initialize the ORB for remote clients.
 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)
          This Java method is invoked to notify the ISH of a listening port in the joint client/server.
 org.omg.CORBA.Object resolve_initial_references(java.lang.String id)
          Acquires CORBA object references for the FactoryFinder, SecurityCurrent, TransactionCurrent, 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 method creates the Bootstrap object. 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 WebLogic Enterprise domain IIOP Server 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 WebLogic Enterprise systems, see the Release Notes.

    For remote clients, address specifies the network address of an IIOP Server Listener/Handler through which client applications gain access to a WebLogic Enterprise domain. The address may be specified in either of the following formats: 

     "//hostname:port_number" 
 "//#.#.#.#: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 local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

    In the second example, 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 local machine.

    In both 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.

    Note: The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the server application's UBBCONFIG file. The format of the address, as well as the capitalization, must match. 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
 /
    For example, if the network address is specified 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 NT systems, see the host system's Network control panel to determine the capitalization used.

    One or more TCP/IP addresses can be specified. Multiple addresses are specified using a comma-separated list. For example: 

     //m1.acme.com:3050 
 //m1.acme.com:3050,//m2.acme.com:3050,//m3.acme.com:3051
    If multiple addresses are specified, the addresses are tried in order until a connection is established. Any member of an address list can be specified as a parenthesized grouping of pipe-separated network addresses. For example: 

     (//m1.acme.com:3050|//m2.acme.com:3050)
    The WebLogic Enterprise system randomly selects one of the parenthesized addresses. This strategy distributes the load randomly across a set of listener processes. 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 chapter that describes how to manage remote client applications in the Administration 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.

  • 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 the org.omg.CORBA.BAD_PARAM exception if the address is not empty.

  • 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:
InvalidDomain - For a remote client, raised if the Bootstrap object cannot connect to the WebLogic Enterprise domain. The address of the WebLogic Enterprise domain IIOP Server Listener/Handler is specified in the constructor that is specific to the programming language. For a native client or server, raised if the domain is not booted.

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 method creates the Bootstrap object. 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 WebLogic Enterprise domain IIOP Server 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 WebLogic Enterprise systems, see the Release Notes.

    For remote clients, address specifies the network address of an IIOP Server Listener/Handler through which client applications gain access to a WebLogic Enterprise domain. The address may be specified in either of the following formats: 

     "//hostname:port_number" 
 "//#.#.#.#: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 local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

    In the second example, 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 local machine.

    In both 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.

    Note: The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the server application's UBBCONFIG file. The format of the address, as well as the capitalization, must match. 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
 /
    For example, if the network address is specified 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 NT systems, see the host system's Network control panel to determine the capitalization used.

    One or more TCP/IP addresses can be specified. Multiple addresses are specified using a comma-separated list. For example: 

     //m1.acme.com:3050 
 //m1.acme.com:3050,//m2.acme.com:3050,//m3.acme.com:3051
    If multiple addresses are specified, the addresses are tried in order until a connection is established. Any member of an address list can be specified as a parenthesized grouping of pipe-separated network addresses. For example: 

     (//m1.acme.com:3050|//m2.acme.com:3050)
    The WebLogic Enterprise system randomly selects one of the parenthesized addresses. This strategy distributes the load randomly across a set of listener processes. 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 chapter that describes how to manage remote client applications in the Administration 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.

  • 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 the org.omg.CORBA.BAD_PARAM exception if the address is not empty.

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

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:
InvalidDomain - For a remote client, raised if the Bootstrap object cannot connect to the WebLogic Enterprise domain. The address of the WebLogic Enterprise domain IIOP Server Listener/Handler is specified in the constructor that is specific to the programming language. For a native client or server, raised if the domain is not booted.
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, 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"
Returns:
Object that corresponds to the specified type ID.
Throws:
InvalidName - Raised if id is not one of the four names allowed (see id parameter). On the server, also raised when SecurityCurrent is passed.
NO_PERMISSION - 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
This Java 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 client ORBs. For GIOP 1.0 and 1.1, the ISH only supports 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:

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 assymmetric outbound IIOP.

Also, if the register_callback_port method is not invoked by the joint client/server, you must start the server’s IIOP Server 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.

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

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.

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 attempt to use the old Current objects from then on throw the exception org.omg. CORBA.BAD_INV_ORDER. Good programming practice is to release all Current objects before invoking the destroy_current method.

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 log off for security and implictly 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.

getNativeProperties

public static java.util.Properties getNativeProperties()
Returns a set of properties that need to be passed in a subsequent invocation of the org.omg.CORBA.ORB.init method. This subsequent invocation causes the BEA Java ORB to be initialized. The getNativeProperties method also initializes the WebLogic Enterprise infrastructure.

The GetNativeProperties method must be invoked before any attempt is made to access any class in the org.omg.CORBA package; otherwise, errors will occur when receiving CORBA exceptions from the server.

Returns:
ORB properties that must be passed to the org.omg.CORBA.ORB.init method.

getRemoteProperties

public static java.util.Properties getRemoteProperties()
Returns the properties needed to initialize the ORB for remote clients.
Returns:
ORB properties that must be passed to the org.omg.CORBA.ORB.init method.