HOME | SITE MAP | SEARCH | CONTACT | GLOSSARY | PDF FILES | WHAT'S NEW
C++ REFERENCE | TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC
|
|
|
BEA WebLogic Enterprise 4.2 Developer Center |
|
HOME | SITE MAP | SEARCH | CONTACT | GLOSSARY | PDF FILES | WHAT'S NEW |
||
|
C++ REFERENCE | TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC |
||
The FactoryFinder interface provides clients with one object reference that serves as the single point of entry into the WLE domain. The WLE 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 WLE 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 a WLE 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:
Capabilities, Limitations, and Requirements
CosLifeCycle::FactoryFinder interface.
The WLE 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 WLE 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 must invoke the
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). Usingthe WLE TP Framework, the registration of the reference for the factory object can be accomplished using the
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 Listing 5-1 shows the C++ class (static) methods. For more information about these methods, see the sections "TP::register_factory()" on page 3-63 and "TP::unregister_factory()" on page 3-65.
Functional Description
Locating a FactoryFinder
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. For more information, see the section "Tobj_Bootstrap::register_callback_port" on page 4-14.
Registering a Factory
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 Object
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" on page 3-24.
C++ Mapping
Listing 5-1
C++ Mappings for the Factory Registration Pseudo OMG IDL
#include <TP.h>
static void
TP::register_factory(
CORBA::Object_ptr factory_or, const char* factory_id);static void
TP::unregister_factory (
CORBA::Object_ptr factory_or, const char* factory_id);
The TP.h header file contains the two method declarations and is 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.
Figure 5-2 Locating a Factory Object
The WLE software 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.
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 WLE 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 WLE 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
// ------ 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.
Listing 5-3 Life Cycle Service OMG IDL
// ----- 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.
Listing 5-4 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.
Figure 5-3 Inter-Domain FactoryFinder Interaction
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 WLE 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, WLE 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 The CosNaming Specification describes two interfaces that constitute a Names Library interface that can be used to create and manipulate
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.
Creating Application Factory Keys
CosLifeCycle::Keys, which corresponds to CosNaming::Name. A client must be able to construct these keys.
CosLifeCycle::Keys. The pseudo OMG IDL statements for these interfaces is described in the following section.
Names Library Interface Pseudo OMG IDL
Listing 5-5
Names Library Interfaces in Pseudo-IDL
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
set_id operation sets the identifier attribute to the string argument.
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
set_kind operation sets the kind attribute to the string argument.
The following operations are described in this section:
The destroy operation destroys library name component pseudo-objects.
void destroy();
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 ith 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 ith 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.
boolean equal(in LName 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.
void destroy();
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 WLE 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 WLE object ID (OID) and interface name. For a detailed description of the Library Name class, see the section "Names Library Interface Pseudo OMG IDL" on page 5-11.
Listing 5-6 Library Name Class
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.
Listing 5-7 Java Mapping for LNameComponent
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:
CosLifeCycle::FactoryFinder::find_factories
Tobj::Factoryfinder::find_one_factory
Tobj::Factoryfinder::find_one_factory_by_id
Tobj::Factoryfinder::find_factories_by_id
CosLifeCycle::FactoryFinder::find_factories
Synopsis
Obtains a sequence of factory object references.
C++ Mapping
CosLifeCycle::Factories *
CORBA::Object_ptr CosLifeCycle::FactoryFinder::find_factories(
const CosNaming::Name& factory_key)
throw (CosLifeCycle::NoFactory);Java Mapping
import org.omg.CosLifeCycle.*;public org.omg.CORBA.Object[] find_factories(
org.omg.CosNaming.NameComponent[] factory_key)
throws org.omg.CosLifeCycle.NoFactory;Parameter
factory_key- This parameter is an unbounded sequence of NameComponents (tuple of <id, kind> pairs) that uniquely identifies a factory object reference.
- A NameComponent is defined as a having two members: an
idand akind, both of type string. Theidfield is used to represent the identity of factory object. Thekindfield is used to indicate how the value of theidfield should be interpreted.- References to factory object registered using the operation
TP::register_factorywill have a kind value of"FactoryInterface".Exception
CORBA::BAD_PARAM- 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_keyis specified.CosLifeCycle::NoFactory- Indicates that there are no factories registered that match the information in the
factory_keyparameter.Description
The
find_factoriesmethod 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.
Return Values
An unbounded sequence of references to Factory objects that match the information specified as the value of the
factory_keyparameter. In C++, the method returns a sequence of object references of typeCosLifeCycle::Factory. In Java, the method returns an unbounded array of object references of typeorg.omg.CORBA.Object.If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Synopsis
Obtains a reference to a single factory object.
C++ Mapping
virtual CosLifeCycle::Factory_ptr
find_one_factory( const CosNaming::Name& factory_key) = 0;Java Mapping
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;Parameter
factory_key- This parameter is an unbounded sequence of NameComponents (tuple of <id, kind> pairs) that uniquely identifies a factory object reference.
- A NameComponent is defined as a having two members: an
idand akind, both of type string. Theidfield is used to represent the identity of factory object. Thekindfield is used to indicate how the value of theidfield should be interpreted.- References to factory object registered using the operation
TP::register_factorywill have a kind value of"FactoryInterface".Exceptions
CORBA::BAD_PARAM- 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_keyis specified.CosLifeCycle::NoFactory- Indicates that there are no factories registered that match the information in the
factory_keyparameter.Tobj::CannotProceed- Indicates that the FactoryFinder or NameManager encountered an internal error while attempting to locate a reference for a factory object.
- Error information is written to the user log.
Tobj::RegistrarNotAvailable- Indicates that the FactoryFinder could not communicate with the NameManager.
- Error information is written to the user log.
Description
The
find_one_factorymethod 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 thefind_one_factorymethod 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.
Return Values
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 typeorg.omg.CORBA.Object.If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Synopsis
Obtains a reference to a single factory object.
C++ Mapping
virtual CosLifeCycle::Factory_ptr
find_one_factory_by_id( const char * factory_id) = 0;Java Mapping
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;Parameter
factory_id- A NULL-terminated string that contains a value that is used to identify the registered factory object to be found.
- The value of the
factory_idparameter is used as the value of theidfield of a NameComponent that has akindfield with the value"FactoryInterface"when comparing against registered references for factory objects.Exceptions
CORBA::BAD_PARAM- 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_keyis specified.CosLifeCycle::NoFactory- Indicates that there are no factories registered that match the information in the
factory_keyparameter.Tobj::CannotProceed- Indicates that the FactoryFinder or NameManager encountered an internal error while attempting to locate a reference for a factory object.
- Error information is written to the user log.
Tobj::RegistrarNotAvailable- Indicates that the FactoryFinder could not communicate with the NameManager.
- Error information is written to the user log.
Description
The
find_one_factory_by_idmethod 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 thefind_one_factory_by_idoperation multiple times using the same ID may return different object references.The
find_one_factory_by_idmethod behaves the same as thefind_one_factoryoperation that was passed a Key that contains a single NameComponent with anidfield that contains the same value as thefactory_idparameter and akindfield that contains the value"FactoryInterface".The registered identifier for a factory is considered equal to the value of the
factory_idparameter if the result of constructing aCosLifeCycle::Keystructure containing a single NameComponent that has thefactory_idparameter as the value of theidfield and the value"FactoryInterface"as the value of thekindfield. The values must match exactly in all respects (case, location, etc.).Return Values
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 typeorg.omg.CORBA.Object.If the operation raises an exception, the return value is invalid and does not need to be released by the caller
Synopsis
Obtains a sequence of one or more factory object references.
C++ Mapping
virtual CosLifeCycle::Factories *
find_factories_by_id( const char * factory_id) = 0;Java Mapping
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;Parameter
factory_id- A NULL-terminated string that contains a value that is used to identify the registered factory object to be found.
- The value of the
factory_idparameter is used as the value of theidfield of a NameComponent that has akindfield with the value"FactoryInterface"when comparing against registered references for factory objects.Exceptions
CORBA::BAD_PARAM- 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_keyis specified.CosLifeCycle::NoFactory- Indicates that there are no factories registered that match the information in the
factory_keyparameter.Tobj::CannotProceed- Indicates that the FactoryFinder or NameManager encountered an internal error while attempting to locate a reference for a factory object.
- Error information is written to the user log.
Tobj::RegistrarNotAvailable- Indicates that the FactoryFinder could not communicate with the NameManager.
- Error information is written to the user log.
Description
The
find_factories_by_idmethod 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_idmethod behaves the same as thefind_factoryoperation that was passed a Key that contains a single NameComponent with anidfield that contains the same value as thefactory_idparameter and akindfield that contains the value"FactoryInterface".The registered identifier for a factory is considered equal to the value of the
factory_idparameter if the result of constructing aCosLifeCycle::Keystructure containing a single NameComponent that has thefactory_idparameter as the value of theidfield and the value"FactoryInterface"as the value of thekindfield. The values must match exactly in all respects (case, location, etc.).Return Values
An unbounded sequence of references to factory objects that match the information specified as the value of the
factory_keyparameter. In C++, the method returns a sequence of object references of typeCosLifeCycle::Factory. In Java, the method returns an unbounded array of object references of typeorg.omg.CORBA.Object.If the operation raises an exception, the return value is invalid and does not need to be released by the caller.
Synopsis
Obtains a lists of factory objects currently registered with the FactoryFinder.
C++ Mapping
virtual FactoryListing * list_factories() = 0;Java Mapping
public com.beasys.Tobj.FactoryComponent[] list_factories()
throws
com.beasys.Tobj.CannotProceed,
com.beasys.Tobj.RegistrarNotAvailable;Exception
Tobj::CannotProceed- Indicates that the FactoryFinder or NameManager encountered an internal error while attempting to locate a reference for a factory object.
- Error information is written to the user log.
Tobj::RegistrarNotAvailable- Indicates that the FactoryFinder could not communicate with the NameManager.
- Error information is written to the user log.
Description
The
list_factoriesmethod 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.Return Values
An unbounded sequence of
Tobj::FactoryComponent. Each occurrence of aTobj::FactoryComponentin the sequence contains a reference to the registered factory object, as well as theCosLifeCycle::Keythat 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.
Automation Methods
This section describes the DITobj_FactoryFinder Automation methods.
Synopsis
Obtains a single application factory.
MIDL Mapping
HRESULT find_one_factory(
[in] VARIANT factory_key,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] IDispatch** returnValue);Automation Mapping
Function find_one_factory(factory_key, [exceptionInfo]) As ObjectParameters
factory_key- This parameter contains a safe array of DICosNaming_NameComponent (<id, kind> value pairs) that uniquely identifies a factory object reference.
exceptionInfo- An optional input argument that enables the application to get additional exception data if an error occurred.
Exceptions
NoFactory- This exception is raised if the FactoryFinder cannot find an application factory object reference that corresponds to the input
factory_key.CannotProceed- 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.
RegistrarNotAvailable- 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. If no naming services servers are running, restart the application.
Description
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 inputfactory_keymust exactly match each <id, kind> pair in the application factory's key. If multiple factory keys contain the inputfactory_key, the FactoryFinder selects one factory key, based on an internally defined load balancing scheme. Invokingfind_one_factorymultiple times using the sameidmay return different object references.Return Values
Returns a reference to an interface pointer for the application factory.
Synopsis
Obtains a single application factory.
MIDL Mapping
HRESULT find_one_factory_by_id(
[in] BSTR factory_id,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] IDispatch** returnValue);Automation Mapping
Function find_one_factory_by_id(factory_id As String,
[exceptionInfo]) As ObjectParameters
factory_id- This 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 C++ Server Applications.
exceptionInfo- An optional input argument that enables the application to get additional exception data if an error occurred.
Exceptions
NoFactory- This exception is raised if the FactoryFinder cannot find an application factory object reference that corresponds to the input
factory_id.CannotProceed- 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.
RegistrarNotAvailable- 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. If no naming service servers are running, restart the application.
Description
This member function instructs the FactoryFinder to return one application factory object reference whose
idin the key matches the method's inputfactory_id. To accomplish this, the member function performs an equality match (that is, the inputfactory_idmust exactly match theidin the <id,kind> pair in the application factory's key). If multiple factory keys contain the inputfactory_id, the FactoryFinder selects one factory key, based on an internally defined load balancing scheme. Invokingfind_one_factory_by_idmultiple times using the sameidmay return different object references.Return Values
Returns a reference to an interface pointer for the application factory.
Synopsis
Obtains a list of application factories.
MIDL Mapping
HRESULT find_factories_by_id(
[in] BSTR factory_id,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);Automation Mapping
Function find_factories_by_id(factory_id As String,
[exceptionInfo])Parameters
factory_id- This parameter represents a string identifier that will be used to identify the kind or type of application factory. The Creating Client Applications online document provides some suggestions as to the composition of this string.
exceptionInfo- An optional input argument that enables the application to get additional exception data if an error occurred.
Exceptions
NoFactory- This exception is raised if the FactoryFinder cannot find an application factory object reference that corresponds to the input
factory_keyorfactory_id.CannotProceed- 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.
RegistrarNotAvailable- 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. If no naming services servers are running, restart the application.
Description
This member function instructs the FactoryFinder to return a list of application factory object references whose
idin the keys match the method's inputfactory_id. To accomplish this, the member function performs an equality match (that is, the inputfactory_idmust exactly match eachidin the <id,kind> pair in the application factory's keys).Return Values
Returns a variant containing an array of interface pointers to application factories.
Synopsis
Obtains a list of application factories.
MIDL Mapping
HRESULT find_factories(
[in] VARIANT factory_key,
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);Automation Mapping
Function find_factories(factory_key, [exceptionInfo])Parameters
factory_key- This parameter contains a safe array of DICosNaming_NameComponents (<id, kind> value pairs) that uniquely identifies a factory object reference.
- exceptionInfo
- An optional input argument that enables the application to get additional exception data if an error occurred.
Exception
NoFactory- This exception is raised if the FactoryFinder cannot find an application factory object reference that corresponds to the input
factory_key.Description
The
find_factoriesmethod instructs the FactoryFinder to return a list of server application factory object references whose keys match the method's input key. The WLE 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.Return Values
Returns a variant containing an array of interface pointers to application factories.
Synopsis
Lists all of the application factory names and object references.
MIDL Mapping
HRESULT list_factories(
[in,out,optional] VARIANT* exceptionInfo,
[out,retval] VARIANT* returnValue);Automation Mapping
Function list_factories([exceptionInfo])Parameter
exceptionInfo- An optional input argument that enables the application to get additional exception data if an error occurred.
Exception
CannotProceed- This 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.RegistrarNotAvailable- 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.
Description
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.
Return Values
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.
Programming Examples
This section describes how to program using the FactoryFinder interface.
Note: Remember to check for exceptions in your code.
Using the FactoryFinder Object
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::FactoryFinderinterface 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.Registering a Reference to a Factory Object
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 Factory
// Server Application: Registering a factory.
// C++ Example.TP::register_factory( factory_obj.in( ), "TellerFactory" );
Obtaining a Reference to a FactoryFinder Object Using the CosLifeCycle::FactoryFinder Interface
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.
Listing 5-9 Client Application: Getting a FactoryFinder Object Reference
// 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( ) );
Obtaining a Reference to a FactoryFinder Object Using the WLE Extensions Bootstrap object
The following code fragment (Listing 5-10) shows how to use of the WLE extensions Bootstrap object to obtain a reference to a FactoryFinder object.
Listing 5-10 Client Application: Finding One Factory Using the Tobj Approach
// 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 );
Using WLE Extensions to the FactoryFinder Object
WLE 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::FactoryFinderinterface. The operations defined for theTobj::FactoryFinderinterface 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 WLE extensions when developing an application. The interfaceTobj::FactoryFinderis derived from theCosLifeCycle::FactoryFinderinterface.WLE extensions to the FactoryFinder object adhere to all the 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-definedCosLifeCycle::FactoryFinderinterface, or a NULL-terminated string containing the identifier of a factory object to be located.Obtaining One Factory using Tobj::FactoryFinder
The following code fragment (Listing 5-11) shows how to use the WLE extensions interface to obtain one reference to a factory object based on an identifier.
Listing 5-11 Client Application: Finding Factories Using the WLE Extensions Approach
CosLifeCycle::Factory_ptrvar fp_obj = ff_np ->
find_one_factory_by_id( "TellerFactory" );
Obtaining One or More Factories using Tobj::FactoryFinder
The following code fragment (Listing 5-12) shows how to use the WLE extensions to obtain one or more references to factory objects based on an identifier.
Listing 5-12 Client Application: Finding One or More Factories Using the WLE Extensions Approach
CosLifeCycle::Factories * _var flp = ff_np ->
find_factories_by_id( "TellerFactory" );
