• The FactoryFinder interface is in compliance with the CosLifeCycle::FactoryFinder interface.
• Invoke the Tobj_Bootstrap::resolve_initial_references operation with a value of “FactoryFinder”. This operation returns a reference to a FactoryFinder that is in the domain to which the client application is currently attached. You should use this mechanism if you are using the Oracle Tuxedo client software. For more information, see the section Tobj_Bootstrap::resolve_initial_references.
• Invoke the CORBA::ORB::resolve_initial_references operation with a value of “FactoryFinder”. This operation returns a reference to a FactoryFinder that is in the domain to which the client application is currently attached. You should use this mechanism if you are using a third-party client ORB. For more information, see the section CORBA::ORB::resolve_initial_references.For a client application to be able to obtain a reference to a factory, an application server must register a reference to any factory object for which it provides an implementation with the FactoryFinder (see Figure 5‑1). Using the Oracle Tuxedo CORBA TP Framework, the registration of the reference for the factory object can be accomplished using the TP::register_factory operation, once a reference to a factory object has been created. The reference to the factory object, along with a value that identifies the factory, is passed to this operation. The registration of references to factory objects is typically done as part of initialization of the application (normally as part of the implementation of the operation Server::initialize).Figure 5‑1 Registering a Factory ObjectWhen the server application is shutting down, it must unregister any references to factory objects that it has previously registered in the application server. This is done by passing the same reference to the factory object, along with the corresponding value used to identify the factory, to the TP::unregister_factory operation. Once unregistered, the reference to the factory object can then be destroyed. The process of unregistering a factory with the FactoryFinder is typically done as part of the implementation of the Server::release operation. For more information about these operations, see the section Server Interface.Listing 5‑1 shows the C++ class (static) methods. For more information about these methods, see the sections TP::register_factory() and TP::unregister_factory().The TP.h header file contains the two method declarations. This file must to be included in any server application that wants to use these methods.For a client application to request a factory to create a reference to an object, it must first obtain a reference to the factory object. The reference to the factory object is obtained by querying a FactoryFinder with specific selection criteria (see Figure 5‑2). The criteria are determined by the format of the particular FactoryFinder interface and method used.Figure 5‑2 Locating a Factory ObjectOracle Tuxedo CORBA extends the CosLifeCycle::FactoryFinder interface by introducing four methods in addition to the find_factories() method declared for the FactoryFinder. Therefore, using the Tobj extensions, a client can use either the find_factories() or find_factories_by_id() methods to obtain a list of application factories. A client can also use the find_one_factory() or find_one_factory_by_id() method to obtain a single application factory, and list_factories () to obtain a list of all registered factories.
Note: You can used the Oracle Tuxedo CORBA extensions to the CosLifeCycle::FactoryFinder interface if you use the Tobj_Bootstrap object, however, use of the Tobj_Bootstrap object is not required to locate a factory. If you use CORBA INS, you can use the find_factories() method provided by the CosLifeCycle::FactoryFinder interface.The CosLifeCycle::FactoryFinder interface defines a factory_key, which is a sequence of id and kind strings conforming to the CosNaming Name shown below. The kind field of the NameComponent for all application factories is set to the string FactoryInterface by the TP Framework when an application factory is registered. Applications supply their own value for the id field.Assuming that the CORBAservices Life Cycle Service modules are contained in their own file (ns.idl and lcs.idl, respectively), only the OMG IDL code for that subset of both files that is relevant for using the Oracle Tuxedo FactoryFinder is shown in the following listings.Listing 5‑2 shows the portions of the ns.idl file that are relevant to the FactoryFinder.Listing 5‑2 CORBAservices Naming OMG IDL// This information is taken from CORBAservices: Common Object
// Services Specification, page 3-6. Revised Edition:
// March 31, 1995. Updated: November 1997. Used with permission by OMG.Listing 5‑3 shows the portions of the lcs.idl file that are relevant to the FactoryFinder.Listing 5‑3 Life Cycle Service OMG IDL// This information is taken from CORBAservices: Common Object
// Services Specification, pages 6-10, 11. Revised Edition:
// March 31, 1995. Updated: November 1997. Used with permission by OMG.Listing 5‑4 shows the Tobj Module OMG IDL.Listing 5‑4 Tobj Module OMG IDLTypically, a FactoryFinder returns references to factory objects that are in the same domain as the FactoryFinder itself. However, it is possible to return references to factory objects in domains other than the domain in which a FactoryFinder exists. This can occur if a FactoryFinder contains information about factories that are resident in another domain (see Figure 5‑3). A FactoryFinder finds out about these interdomain factory objects through configuration information that describes the location of these other factory objects.Figure 5‑3 Inter-Domain FactoryFinder InteractionTwo of the five methods provided by the FactoryFinder interface accept CosLifeCycle::Keys, which corresponds to CosNaming::Name. A client must be able to construct these keys.The CosNaming Specification describes two interfaces that constitute a Names Library interface that can be used to create and manipulate CosLifeCycle::Keys. The pseudo OMG IDL statements for these interfaces is described in the following section.
Note: This information is taken from the CORBAservices: Common Object Services Specification, pp. 3-14 to18. Revised Edition: March 31, 1995. Updated: November 1997. Used with permission by OMG.Pseudo-object references cannot be passed across OMG IDL interfaces. As described in Chapter 3 of the CORBAservices: Common Object Services Specification, in the section “The CosNaming Module,” the CORBAservices Naming Service supports the NamingContext OMG IDL interface. The names library supports an operation to convert a library name into a value that can be passed to the name service through the NamingContext interface.
Note: The names library consists of two pseudo-IDL interfaces, the LNameComponent interface and the LName interface, as shown in Listing 5‑5.Listing 5‑5 Names Library Interfaces in Pseudo-IDLThe returned pseudo-object reference can then be operated on using the operations shown in Listing 5‑5.A name component consists of two attributes: identifier and kind. The LNameComponent interface defines the operations associated with these attributes, as follows:The get_id operation returns the identifier attribute’s value. If the attribute has not been set, the NotSet exception is raised.The get_kind operation returns the kind attribute’s value. If the attribute has not been set, the NotSet exception is raised.
• Getting the ith name componentThe destroy operation destroys library name component pseudo-objects.A name has one or more components. Each component except the last is used to identify names of subcontexts. (The last component denotes the bound object.) The insert_component operation inserts a component after position i.If component i-1 is undefined and component i is greater than 1 (one), the insert_component operation raises the NoComponent exception.If the library cannot allocate resources for the inserted component, the OverFlow exception is raised.Getting the ith Name ComponentIf the component does not exist, the NoComponent exception is raised.If the component does not exist, the NoComponent exception is raised.After a delete_component operation has been performed, the compound name has one fewer component and components previously identified as i+1...n are now identified as i...n-1.The num_components operation returns the number of components in a library name.This operation returns TRUE if the library name is less than the library name ln passed as an argument. The library implementation defines the ordering on names.Pseudo-objects cannot be passed across OMG IDL interfaces. The library name is a pseudo-object; therefore, it cannot be passed across the OMG IDL interface for the CORBAservices Naming Service. Several operations in the NamingContext interface have arguments of an OMG IDL-defined structure, Name. The following PIDL operation on library names produces a structure that can be passed across the OMG IDL request.If the name is of length 0 (zero), the InvalidName exception is returned.Pseudo-objects cannot be passed across OMG IDL interfaces. The library name is a pseudo-object; therefore, it cannot be passed across the OMG IDL interface for the CORBAservices Naming Service. The NamingContext interface defines operations that return an IDL struct of type Name. The following PIDL operation on library names sets the components and kind attribute for a library name from a returned OMG IDL defined structure, Name.The destroy operation destroys library name pseudo-objects.The Names Library pseudo OMG IDL interface maps to the C++ classes shown in Listing 5‑6, which can be found in the NamesLib.h header file.Two Oracle Tuxedo extensions to CORBA are included to support scalability. Specifically, the LNameComponent::set_id() and LNameComponent::set_kind() methods raise an OverFlow exception if the length of the input string exceeds MAX_LNAME_STRLEN. This length coincides with the maximum length of the Oracle Tuxedo object ID (OID) and interface name. For a detailed description of the Library Name class, see the section Names Library Interface Pseudo OMG IDL.Listing 5‑6 Library Name ClassThe Names Library pseudo OMG IDL interface maps to the Java classes contained in the com.beasys.Tobj package, shown in Listing 5‑7. All exceptions are contained in the same package.For a detailed description of the Library Name class, refer to Chapter 3 in the CORBAservices: Common Object Services Specification.Listing 5‑7 Java Mapping for LNameComponent
Note: All FactoryFinder member functions, except the less_than member function in LName, are implemented in both C++ and Java.
Note: The CosLifeCycle::FactoryFinder::find_factories method is the standard CORBA CosLifeCycle method. The four Tobj methods are extensions to the CosLifeCycle interface and, therefore, inherit the attributes of the CosLifeCycle interface.A NameComponent is defined as a having two members: an id and a kind, both of type string. The id field is used to represent the identity of factory object. The kind field is used to indicate how the value of the id field should be interpreted.References to factory object registered using the operation TP::register_factory will have a kind value of “FactoryInterface”.Indicates that the value of an input parameter has an inappropriate value or is invalid. Of particular importance, the exception is raised if no value or a NULL value for the parameter factory_key is specified.Indicates that there are no factories registered that match the information in the factory_key parameter.The find_factories method is called by an application to obtain a sequence of factory object references. The operation is passed a key used to identify the desired factory. The key is a name, as defined by the CORBAservices Naming service. More than one factory may match the key, and, if that is the case, the FactoryFinder returns a sequence of factories.An unbounded sequence of references to factory objects that match the information specified as the value of the factory_key parameter. In C++, the method returns a sequence of object references of type CosLifeCycle::Factory. In Java, the method returns an unbounded array of object references of type org.omg.CORBA.Object.A NameComponent is defined as a having two members: an id and a kind, both of type string. The id field is used to represent the identity of factory object. The kind field is used to indicate how the value of the id field should be interpreted.References to factory object registered using the operation TP::register_factory will have a kind value of “FactoryInterface”.Indicates that the value of an input parameter has an inappropriate value or is invalid. Of particular importance, the exception is raised if no value or a NULL value for the parameter factory_key is specified.Indicates that there are no factories registered that match the information in the factory_key parameter.The find_one_factory method is called by an application to obtain a reference to a single factory object whose key matches the value of the key specified as input to the method. If more than one factory object is registered with the specified key, the FactoryFinder selects one factory object based on the FactoryFinder’s load balancing scheme. As a result, invoking the find_one_factory method multiple times using the same key may return different object references.An object reference for a factory object. In C++, the method returns an object reference of type CosLifeCycle::Factory. In Java, the method returns an object reference of type org.omg.CORBA.Object.The value of the factory_id parameter is used as the value of the id field of a NameComponent that has a kind field with the value “FactoryInterface” when comparing against registered references for factory objects.Indicates that the value of an input parameter has an inappropriate value or is invalid. Of particular importance, the exception is raised if no value or a NULL value for the parameter factory_key is specified.Indicates that there are no factories registered that match the information in the factory_key parameter.The find_one_factory_by_id method is called by an application to obtain a reference to a single factory object whose registration ID matches the value of the ID specified as input to the method. If more than one factory object is registered with the specified ID, the FactoryFinder selects one factory object based on the FactoryFinder’s load balancing scheme. As a result, invoking the find_one_factory_by_id operation multiple times using the same ID may return different object references.The find_one_factory_by_id method behaves the same as the find_one_factory operation that was passed a key that contains a single NameComponent with an id field that contains the same value as the factory_id parameter and a kind field that contains the value “FactoryInterface”.The registered identifier for a factory is considered equal to the value of the factory_id parameter if the result of constructing a CosLifeCycle::Key structure containing a single NameComponent that has the factory_id parameter as the value of the id field and the value “FactoryInterface” as the value of the kind field. The values must match exactly in all respects (case, location, etc.).An object reference for a factory object. In C++, the method returns an object reference of type CosLifeCycle::Factory. In Java, the method returns an object reference of type org.omg.CORBA.Object.The value of the factory_id parameter is used as the value of the id field of a NameComponent that has a kind field with the value “FactoryInterface” when comparing against registered references for factory objects.Indicates that the value of an input parameter has an inappropriate value or is invalid. Of particular importance, the exception is raised if no value or a NULL value for the parameter factory_key is specified.Indicates that there are no factories registered that match the information in the factory_key parameter.The find_factories_by_id method is called by an application to obtain a sequence of one or more factory object references. The method is passed a NULL-terminated string that contains the identifier of the factory to be located. If more than one factory object is registered with the specified ID, the FactoryFinder will return a list of object references for the matching registered factory objects.The find_factories_by_id method behaves the same as the find_factory operation that was passed a key that contains a single NameComponent with an id field that contains the same value as the factory_id parameter and a kind field that contains the value “FactoryInterface”.The registered identifier for a factory is considered equal to the value of the factory_id parameter if the result of constructing a CosLifeCycle::Key structure containing a single NameComponent that has the factory_id parameter as the value of the id field and the value “FactoryInterface” as the value of the kind field. The values must match exactly in all respects (case, location, etc.).An unbounded sequence of references to factory objects that match the information specified as the value of the factory_key parameter. In C++, the method returns a sequence of object references of type CosLifeCycle::Factory. In Java, the method returns an unbounded array of object references of type org.omg.CORBA.Object.The list_factories method is called by an application to obtain a list of the factory objects currently registered with the FactoryFinder. The method returns both the key used to register the factory, as well as a reference to the factory object.The number of factories returned by list_factories will be one more than the ones registered by the user. For example, if the user registered four factories then the number of factories returned by list_factories will be five.An unbounded sequence of Tobj::FactoryComponent. Each occurrence of a Tobj::FactoryComponent in the sequence contains a reference to the registered factory object, as well as the CosLifeCycle::Key that was used to register that factory object.DITobj_FactoryFinder.find_one_factoryThis exception is raised if the FactoryFinder or CORBAservices Naming Service encounter an internal error during the search with the error being written to the user log (ULOG). Notify the operations staff immediately if this exception is raised. Depending on the severity of the internal error, the server running the FactoryFinder or CORBAservices Naming Service may have terminated. If a FactoryFinder service has terminated, start a new FactoryFinder service. If a CORBAservices Naming Service has terminated and there is another CORBAservices Naming Service running, start a new CORBAservices Naming Service. If no naming services servers are running, restart the application.This member function instructs the FactoryFinder to return one application factory object reference whose key matches the input factory_key. To accomplish this, the member function performs an equality match; that is, every NameComponent <id, kind> pair in the input factory_key must exactly match each <id, kind> pair in the application factory’s key. If multiple factory keys contain the input factory_key, the FactoryFinder selects one factory key, based on an internally defined load balancing scheme. Invoking find_one_factory multiple times using the same id may return different object references.DITobj_FactoryFinder.find_one_factory_by_idThis parameter represents a string identifier that is used to identify the kind or type of application factory. For some suggestions as to the composition of this string, see Creating CORBA Server Applications.This exception is raised if the FactoryFinder or CORBAservices Naming Service encounter an internal error during the search, with the error being written to the user log (ULOG). Notify the operations staff immediately if this exception is raised. Depending on the severity of the internal error, the server running the FactoryFinder or the CORBAservices Naming Service may have terminated. If a FactoryFinder service has terminated, start a new FactoryFinder service. If a CORBAservices Naming Service has terminated and there is another CORBAservices Naming Service running, start a new CORBAservices Naming Service. If there are no naming services running, restart the application.This member function instructs the FactoryFinder to return one application factory object reference whose id in the key matches the method’s input factory_id. To accomplish this, the member function performs an equality match (that is, the input factory_id must exactly match the id in the <id,kind> pair in the application factory’s key). If multiple factory keys contain the input factory_id, the FactoryFinder selects one factory key, based on an internally defined load balancing scheme. Invoking find_one_factory_by_id multiple times using the same id may return different object references.DITobj_FactoryFinder.find_factories_by_idThis parameter represents a string identifier that will be used to identify the kind or type of application factory. The Creating CORBA Client Applications online document provides some suggestions as to the composition of this string.This exception is raised if the FactoryFinder cannot find an application factory object reference that corresponds to the input factory_key or factory_id.This exception is raised if the FactoryFinder or CORBAservices Naming Service encounter an internal error during the search with the error being written to the user log (ULOG). Notify the operations staff immediately if this exception is raised. Depending on the severity of the internal error, the server running the FactoryFinder or CORBAservices Naming Service may have terminated. If a FactoryFinder service has terminated, start a new FactoryFinder service. If a CORBAservices Naming Service has terminated and there is another CORBAservices Naming Service running, start a new CORBAservices Naming Service. If no naming services servers are running, restart the application.This member function instructs the FactoryFinder to return a list of application factory object references whose id in the keys match the method’s input factory_id. To accomplish this, the member function performs an equality match (that is, the input factory_id must exactly match each id in the <id,kind> pair in the application factory’s keys).DITobj_FactoryFinder.find_factoriesThe find_factories method instructs the FactoryFinder to return a list of server application factory object references whose keys match the method's input key. The Oracle Tuxedo system assumes that an equality match is to be performed. This means that for the two sequences of <id,kind> pairs (those corresponding to the input key and those in the application factory's keys), each are of equal length; for every pair in one sequence, there is an identical pair in the other.DITobj_FactoryFinder.list_factoriesThis exception is raised if the FactoryFinder or the CORBAservices Naming Service encounter an internal error during the search with the error being written to the user log (ULOG). Notify the operations staff immediately if this exception is raised. Depending on the severity of the internal error, the server running the FactoryFinder or the CORBAservices Naming Service may have terminated. If a FactoryFinder service has terminated, start a new FactoryFinder service. If a CORBAservices Naming Service has terminated and there is another CORBAservices Naming Service running, start a new CORBAservices Naming Service. If there are no naming service servers running, restart the application.This exception is raised if the FactoryFinder object cannot locate the CORBAservices Naming Service object. Notify the operations staff immediately if this exception is raised. It is possible that no naming service servers are running. Restart the application.All FactoryFinder objects support the CosLifeCycle::FactoryFinder interface as defined in CORBAservices Specification, Chapter 6 “Life Cycle Service,” December 1997, published by the Object Management Group. The interface contains one operation that is used to obtain one or more references to factory objects that meet the criteria specified.The following code fragment (Listing 5‑8) shows how to use the TP Framework interface to register a reference to a factory object with a FactoryFinder.Listing 5‑8 Server Application: Registering a FactoryThe following code fragment (Listing 5‑9) shows how to use of the CORBA-compliant interface to obtain one or more references to factory objects.CosLifeCycle::Key_var factory_key = new CosLifeCycle::Key( );
factory_key ->length(1);
factory_key[0].id = string_dupalloc( “strlen(“TellerFactory”) +1 );
factory_key[0].kind = string_dupalloc(
strlen(““FactoryInterface”) + 1);
strcpy( factory_key[0].id, “”TellerFactory” );
strcpy( facory_key[0].kind, “FactoryInterface” );
CosLifeCycle::Factories_var * flp = ff_np ->
find_factories( factory_key.in( ) );The following code fragment (Listing 5‑10) shows how to use of the Oracle Tuxedo extensions Bootstrap object to obtain a reference to a FactoryFinder object.Tobj_Bootstrap * bsp = new Tobj_Bootstrap(
orb_ptr.in( ), host_port );
CORBA::Object_varptr ff_op = bsp ->
resolve_initial_references( “FactoryFinder” );
Tobj::FactoryFinder_ptrvar ff_np =
Tobj::FactoryFinder::_narrow( ff_op);
Note: You can used the Oracle Tuxedo CORBA extensions to the CosLifeCycle::FactoryFinder interface if you use the Tobj_Bootstrap object, however, use of the Tobj_Bootstrap object is not required to locate a factory. If you use CORBA INS, you can use the find_factories() method provided by the CosLifeCycle::FactoryFinder interface.Oracle Tuxedo extends the FactoryFinder object with functionality to support similar capabilities to those provided by the operations defined by CORBA, but with a much simpler and more restrictive signature. The enhanced functionality is provided by defining the Tobj::FactoryFinder interface. The operations defined for the Tobj::FactoryFinder interface are intended to provide a focused, simplified form of the equivalent capability defined by CORBA. An application developer can choose to use the CORBA-defined or Oracle Tuxedo extensions when developing an application. The interface Tobj::FactoryFinder is derived from the CosLifeCycle::FactoryFinder interface.The implementation of the extended FactoryFinder object requires users to supply either a CosLifeCycle::Key, as in the CORBA-defined CosLifeCycle::FactoryFinder interface, or a NULL-terminated string containing the identifier of a factory object to be located.The following code fragment (Listing 5‑11) shows how to use the Oracle Tuxedo extensions interface to obtain one reference to a factory object based on an identifier.The following code fragment (Listing 5‑12) shows how to use the Oracle Tuxedo extensions to obtain one or more references to factory objects based on an identifier.