The FactoryFinder interface provides clients with one object reference that serves as the single point of entry into the Oracle Tuxedo domain. The Oracle Tuxedo NameManager provides the mapping of factory names to object references for the FactoryFinder. Multiple FactoryFinders and NameManagers together provide increased availability and reliability. In this release the level of functionality has been extended to support multiple domains.
Note: | The NameManager is not a naming service, such as CORBAservices Naming Service, but is merely a vehicle for storing registered factories. |
In the Oracle Tuxedo environment, application factory objects are used to create objects that clients interact with to perform their business operations (for example, TellerFactory and Teller). Application factories are generally created during server initialization and are accessed by both remote clients and clients located within the server application.
The FactoryFinder interface and the NameManager services are contained in separate (nonapplication) servers. A set of application programming interfaces (APIs) is provided so that both client and server applications can access and update the factory information.
The support for multiple domains in this release benefits customers that need to scale to a large number of machines or who want to partition their application environment. To support multiple domains, the mechanism used to find factories in an Oracle Tuxedo environment has been enhanced to allow factories in one domain to be visible in another. The visibility of factories in other domains is under the control of the system administrator.
During server application initialization, application factories need to be registered with the NameManager. Clients can then be provided with the object reference of a FactoryFinder to allow them to retrieve a factory object reference based on associated names that were created when the factory was registered.
The following functional capabilities, limitations, and requirements apply to this release:
CosLifeCycle::FactoryFinder
interface.
The Oracle Tuxedo CORBA environment promotes the use of the factory design pattern as the primary means for a client to obtain a reference to an object. Through the use of this design pattern, client applications require a mechanism to obtain a reference to an object that acts as a factory for another object. Because the Oracle Tuxedo environment has chosen CORBA as its visible programming model, the mechanism used to locate factories is modeled after the FactoryFinder as described in the CORBAservices Specification, Chapter 6 “Life Cycle Service,” December 1997, published by the Object Management Group.
In the CORBA FactoryFinder model, application servers register active factories with a FactoryFinder. When an application server’s factory becomes inactive, the application server removes the corresponding registration from the FactoryFinder. Client applications locate factories by querying a FactoryFinder. The client application can control the references to the factory object returned by specifying criteria that is used to select one or more references.
A client application must obtain a reference to a FactoryFinder before it can begin locating an appropriate factory. To obtain a reference to a FactoryFinder in the domain to which a client application is associated, the client application can use either of two bootstrapping mechanisms:
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.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.Note: | The references to the FactoryFinder that are returned to the client application can be references to factory objects that are registered on the same machine as the FactoryFinder, on a different machine than the FactoryFinder, or possibly in a different domain than the FactoryFinder. |
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)
.
When 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().
#include <TP.h>
static voidTP::register_factory
(
CORBA::Object_ptr factory_or, const char* factory_id);
static voidTP::unregister_factory
(
CORBA::Object_ptr factory_or, const char* factory_id);
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.
A server application generally includes this header file within the application file that contains the methods for application server initialization and release.
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.
Oracle 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.
// ------ ns.idl ------
module CosNaming {
typedef string Istring;
struct NameComponent {
Istring id;
Istring kind;
};
typedef sequence <NameComponent> Name;
};
// 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.
// ----- lcs.idl -----
#include “ns.idl”
module CosLifeCycle{
typedef CosNaming::Name Key;
typedef Object Factory;
typedef sequence<Factory> Factories;
exception NoFactory{ Key search_key; }
interface FactoryFinder {
Factories find_factories(in Key factory_key)
raises(NoFactory);
};
};
// 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.
// ----- Tobj.idl -----
module Tobj {
// Constants
const string FACTORY_KIND = "FactoryInterface";
// Exceptions
exception CannotProceed { };
exception InvalidDomain {};
exception InvalidName { };
exception RegistrarNotAvailable { };
// Extension to LifeCycle Service
struct FactoryComponent {
CosLifeCycle::Key factory_key;
CosLifeCycle::Factory factory_ior;
};
typedef sequence<FactoryComponent> FactoryListing;
interface FactoryFinder : CosLifeCycle::FactoryFinder {
CosLifeCycle::Factory find_one_factory(in CosLifeCycle::Key
factory_key)
raises (CosLifeCycle::NoFactory,
CannotProceed,
RegistrarNotAvailable);
CosLifeCycle::Factory find_one_factory_by_id(in string
factory_id)
raises (CosLifeCycle::NoFactory,
CannotProceed,
RegistrarNotAvailable);
CosLifeCycle::Factories find_factories_by_id(in string
factory_id)
raises (CosLifeCycle::NoFactory,
CannotProceed,
RegistrarNotAvailable);
FactoryListing list_factories()
raises (CannotProceed,
RegistrarNotAvailable);
};
};
Typically, 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.
When a FactoryFinder receives a request to locate a factory object, it must first determine if a reference to a factory object that meets the specified criteria exists. If there is registration information for a factory object that matches the criteria, the FactoryFinder must then determine if the factory object is local to the current domain or needs to be imported from another domain. If the factory object is from the local domain, the FactoryFinder returns the reference to the factory object to the client.
If, on the other hand, the information indicates that the actual factory object is from another domain, the FactoryFinder delegates the request to an interdomain FactoryFinder in the appropriate domain. As a result, only a FactoryFinder in the same domain as the factory object will contain an actual reference to the factory object. The interdomain FactoryFinder is responsible for returning the reference of the factory object to the local FactoryFinder, which subsequently returns it to the client.
The Oracle Tuxedo software extends the interfaces defined in the CORBAservices specification, Chapter 6 “Life Cycle Service,” December 1997, published by the Object Management Group, for the following reasons:
Therefore, Oracle Tuxedo extends the interfaces defined in the CORBAservices specification to make using a FactoryFinder easier. The extensions are manifested as refined interfaces to the FactoryFinder that are derived from the interfaces specified in the CORBAservices specification.
Two 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. |
To allow the representation of names to evolve without affecting existing client applications, it is desirable to hide the representation of names from the client application. Ideally, names themselves would be objects; however, names must be lightweight entities that are efficient to create, manipulate, and transmit. As such, names are presented to programs through the names library.
The names library implements names as pseudo-objects. A client application makes calls on a pseudo-object in the same way it makes calls on an ordinary object. Library names are described in pseudo-IDL (to suggest the appropriate language binding). C++ client applications use the same client language bindings for pseudo-IDL (PIDL) as they use for IDL.
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: | It is not a requirement to use the names library in order to use the CORBAservices Naming Service. |
The names library consists of two pseudo-IDL interfaces, the LNameComponent interface and the LName interface, as shown in Listing 5-5.
interface LNameComponent { // PIDL
const short MAX_LNAME_STRLEN = 128;
exception NotSet{ };
exception OverFlow{ };
string get_id
raises (NotSet);
void set_id(in string i)
raises (OverFlow);
string get_kind()
raises(NotSet);
void set_kind(in string k)
raises (OverFlow);
void destroy();
};
interface LName { // PIDL
exception NoComponent{ };
exception OverFlow{ };
exception InvalidName{ };
LName insert_component(in unsigned long i,
in LNameComponent n)
raises (NoComponent, OverFlow);
LNameComponent get_component(in unsigned long i)
raises (NoComponent);
LNameComponent delete_component(in unsigned long i)
raises (NoComponent);
unsigned long num_components();
boolean equal(in LName ln);
boolean less_than(in LName ln);
Name to_idl_form()
raises (InvalidName);
void from_idl_form(in Name n);
void destroy();
};
LName create_lname(); // C/C++
LNameComponent create_lname_component(); // C/C++
To create a library name component pseudo-object, use the following C/C++ function:
LNameComponent create_lname_component(); // C/C++
The returned pseudo-object can then be operated on using the operations shown in Listing 5-5.
To create a library name pseudo-object, use the following C/C++ function:
LName create_lname(); // C/C++
The 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:
string get_id()
raises(NotSet);
void set_id(in string k);
string get_kind()
raises(NotSet);
void set_kind(in string k);
get_id
get_id
operation returns the identifier
attribute’s value. If the attribute has not been set, the NotSet
exception is raised.
set_id
get_kind
get_kind
operation returns the kind
attribute’s value. If the attribute has not been set, the NotSet
exception is raised.
set_kind
The following operations are described in this section:
The 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
.
LName insert_component(in unsigned long i, in LNameComponent lnc)
raises(NoComponent, OverFlow);
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.
The get_component
operation returns the i
th component. The first component is numbered 1 (one).
LNameComponent get_component(in unsigned long i)
raises(NoComponent);
If the component does not exist, the NoComponent
exception is raised.
The delete_component
operation removes and returns the i
th component.
LNameComponent delete_component(in unsigned long i)
raises(NoComponent);
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.
unsigned long num_components();
The equal operation tests for equality with library name ln
.
The less_than
operation tests for the order of a library name in relation to library name ln
.
boolean less_than(in LName ln);
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.
Name to_idl_form()
raises(InvalidName);
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
.
void from_idl_form(in Name n);
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.
const short MAX_LNAME_STRLEN = 128;
class LNameComponent {
public:
class NotSet{ };
class OverFlow{ };
static LNameComponent* create_lname_component();
void destroy();
const char* get_id() const throw (NotSet);
void set_id(const char* i) throw (OverFlow);
const char* get_kind() const throw (NotSet);
void set_kind(const char* k) throw (OverFlow);
};
class LName {
public:
class NoComponent{ };
class OverFlow{ };
class InvalidName{ };
static LName* create_lname();
void destroy();
LName* insert_component(const unsigned long i,
LNameComponent* n)
throw (NoComponent, OverFlow);
const LNameComponent* get_component(
const unsigned long i) const
throw (NoComponent);
const LNameComponent* delete_component(
const unsigned long i)
throw (NoComponent);
unsigned long num_components() const;
CORBA::Boolean equal(const LName* ln) const;
CORBA::Boolean less_than(
const LName* ln) const; // not implemented
CosNaming::Name* to_idl_form()
throw (InvalidName);
void from_idl_form(const CosNaming::Name& n);
};
The 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.
public class LNameComponent {
public static LNameComponent create_lname_component();
public static final short MAX_LNAME_STRING = 128;
public void destroy();
public String get_id() throws NotSet;
public void set_id(String i) throws OverFlow;
public String get_kind() throws NotSet;
public void set_kind(String k) throws OverFlow;
};
public class LName {
public static LName create_lname();
public void destroy();
public LName insert_component(long i, LNameComponent n)
throws NoComponent, OverFlow;
public LNameComponent get_component(long i)
throws NoComponent;
public LNameComponent delete_component(long i)
throws NoComponent;
public long num_components();
public boolean equal(LName ln);
public boolean less_than(LName ln); // not implemented
public org.omg.CosNaming.NameComponent[] to_idl_form()
throws InvalidName;
public void from_idl_form(org.omg.CosNaming.NameComponent[] nr);
};
This section describes the FactoryFinder C++ member functions and Java methods.
Note: | All FactoryFinder member functions, except the less_than member function in LName, are implemented in both C++ and Java. |
The following methods are described in this section:
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. |
Obtains a sequence of factory object references.
CosLifeCycle::Factories *
CORBA::Object_ptr CosLifeCycle::FactoryFinder::find_factories(
const CosNaming::Name& factory_key)
throw (CosLifeCycle::NoFactory);
import org.omg.CosLifeCycle.*;
public org.omg.CORBA.Object[] find_factories(
org.omg.CosNaming.NameComponent[] factory_key)
throws org.omg.CosLifeCycle.NoFactory;
factory_key
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”
.
CORBA::BAD_PARAM
factory_key
is specified.
CosLifeCycle::NoFactory
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.
The scope of the key is the FactoryFinder. The FactoryFinder assigns no semantics to the key. It simply matches keys. It makes no guarantees about the interface or implementation of the returned factories or objects they create.
Key values are considered equal if they are of equal length (same number of elements in the sequence), and if every NameComponent value in the key matches the corresponding NameComponent value at the exact same location in the key that was specified when the reference to the factory object was registered.
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
.
If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Obtains a reference to a single factory object.
virtual CosLifeCycle::Factory_ptr
find_one_factory( const CosNaming::Name& factory_key) = 0;
public org.omg.CORBA.Object
find_one_factory( org.omg.CosNaming.NameComponent[] factory_key)
throws
org.omg.CosLifeCycle.NoFactory,
com.beasys.Tobj.CannotProceed,
com.beasys.Tobj.RegistrarNotAvailable;
factory_key
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”
.
CORBA::BAD_PARAM
factory_key
is specified.
CosLifeCycle::NoFactory
factory_key
parameter.
Tobj::CannotProceed
Tobj::RegistrarNotAvailable
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.
The scope of the key is the FactoryFinder. The FactoryFinder assigns no semantics to the key. It simply matches keys. It makes no guarantees about the interface or implementation of the returned factory or objects they create.
Key values are considered equal if they are of equal length (same number of elements in the sequence), and if every NameComponent value in the key matches the corresponding NameComponent value at the exact same location in the key that was specified when the reference to the factory object was registered.
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
.
If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Obtains a reference to a single factory object.
virtual CosLifeCycle::Factory_ptr
find_one_factory_by_id( const char * factory_id) = 0;
public org.omg.CORBA.Object
find_one_factory_by_id( java.lang.String factory_id)
throws
org.omg.CosLifeCycle.NoFactory,
com.beasys.Tobj.CannotProceed,
com.beasys.Tobj.RegistrarNotAvailable;
factory_id
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.
CORBA::BAD_PARAM
factory_key
is specified.
CosLifeCycle::NoFactory
factory_key
parameter.
Tobj::CannotProceed
Tobj::RegistrarNotAvailable
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
.
If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Obtains a sequence of one or more factory object references.
virtual CosLifeCycle::Factories *
find_factories_by_id( const char * factory_id) = 0;
public org.omg.CORBA.Object[]
find_factories_by_id( java.lang.String factory_id)
throws
org.omg.CosLifeCycle.NoFactory,
com.beasys.Tobj.CannotProceed,
com.beasys.Tobj.RegistrarNotAvailable;
factory_id
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.
CORBA::BAD_PARAM
factory_key
is specified.
CosLifeCycle::NoFactory
factory_key
parameter.
Tobj::CannotProceed
Tobj::RegistrarNotAvailable
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
.
If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Obtains a list of factory objects currently registered with the FactoryFinder.
virtual FactoryListing * list_factories() = 0;
public com.beasys.Tobj.FactoryComponent[] list_factories()
throws
com.beasys.Tobj.CannotProceed,
com.beasys.Tobj.RegistrarNotAvailable;
Tobj::CannotProceed
Tobj::RegistrarNotAvailable
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.
Note: | This change in behavior is because the OMG Transaction Service specification version 1.1 in section 2.1.2 specifies that the Transaction Factory is located using the FactoryFinder interface of the Life Cycle Service. Hence the Transaction factory is registered internally by the product with the FactoryFinder. |
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.
If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
This section describes the DITobj_FactoryFinder Automation methods.
Obtains a single application factory.
HRESULT find_one_factory(
[in] VARIANT factory_key,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] IDispatch** returnValue);
Function find_one_factory(factory_key, [exceptionInfo]) As Object
factory_key
exceptionInfo
NoFactory
factory_key
.
CannotProceed
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.
RegistrarNotAvailable
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.
Returns a reference to an interface pointer for the application factory.
Obtains a single application factory.
HRESULT find_one_factory_by_id(
[in] BSTR factory_id,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] IDispatch** returnValue);
Function find_one_factory_by_id(factory_id As String,
[exceptionInfo]) As Object
factory_id
exceptionInfo
NoFactory
factory_id
.
CannotProceed
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.
RegistrarNotAvailable
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.
Returns a reference to an interface pointer for the application factory.
Obtains a list of application factories.
HRESULT find_factories_by_id(
[in] BSTR factory_id,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);
Function find_factories_by_id(factory_id As String,
[exceptionInfo])
factory_id
exceptionInfo
NoFactory
factory_key
or factory_id
.
CannotProceed
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.
RegistrarNotAvailable
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).
Returns a variant containing an array of interface pointers to application factories.
Obtains a list of application factories.
HRESULT find_factories(
[in] VARIANT factory_key,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);
Function find_factories(factory_key, [exceptionInfo])
factory_key
NoFactory
factory_key
.
The 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.
Returns a variant containing an array of interface pointers to application factories.
Lists all of the application factory names and object references.
HRESULT list_factories(
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);
Function list_factories([exceptionInfo])
exceptionInfo
CannotProceed
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.
RegistrarNotAvailable
This method instructs the FactoryFinder to return a list containing all of the factory keys and associated object references for application factories registered with the CORBAservices Naming Service.
Returns a variant containing an array of DITobj_FactoryComponent objects. The FactoryComponent object consists of a variant containing an array of DICosNaming_NameComponent objects and an interface pointer to the application factory.
This section describes how to program using the FactoryFinder interface.
Note: | Remember to check for exceptions in your code. |
A FactoryFinder object is used by programmers to locate a reference to a factory object. The FactoryFinder object provides operations to obtain one or more references to factory objects based on the criteria specified.
There can be more than one FactoryFinder object in a process address space. Multiple references to a FactoryFinder object must be supported. A FactoryFinder object is semi-stateful in that it maintains state about the association between FactoryFinder objects within a domain and a particular IIOP Server Listener/Handler (ISL/ISH) through which to access the domain.
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.
// Server Application: Registering a factory.
// C++ Example.
TP::register_factory( factory_obj.in( ), “TellerFactory” );
The following code fragment (Listing 5-9) shows how to use of the CORBA-compliant interface to obtain one or more references to factory objects.
// Client Application: Obtaining the object reference
// 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.
// Client Application: Finding one factory using the Tobj
// approach.
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.
Oracle Tuxedo extensions to the FactoryFinder object adhere to allthe same rules as the FactoryFinder object defined in the CORBAservices Specification, Chapter 6 “Life Cycle Service,” December 1997, published by the Object Management Group.
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.
CosLifeCycle::Factory_ptrvar fp_obj = ff_np ->
find_one_factory_by_id( “TellerFactory” );
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.
CosLifeCycle::Factories * _var flp = ff_np ->
find_factories_by_id( “TellerFactory” );