CORBA Programming Reference

FactoryFinder Interface

The FactoryFinder interface provides clients with one object reference that serves as the single point of entry into the BEA Tuxedo domain. The BEA 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.

In the BEA 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 a BEA 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.

Capabilities, Limitations, and Requirements

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:

Functional Description

The BEA 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 BEA 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.

Locating a FactoryFinder

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:

Registering a Factory

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

C++ Mapping

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

Locating a Factory

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.

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

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 BEA Tuxedo FactoryFinder is shown in the following listings.

CORBAservices Naming Service Module OMG IDL

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.

CORBAservices Life Cycle Service Module OMG IDL

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.

Tobj Module OMG IDL

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);
   };
};

Locating Factories in Another Domain

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.

Why Use BEA Tuxedo CORBA Extensions?

The BEA 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, BEA 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.

Creating Application Factory Keys

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.

Names Library Interface Pseudo OMG IDL

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.

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++

Creating a Library Name Component

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.

Creating a Library Name

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.

The LNameComponent Interface

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

set_id

get_kind

set_kind

The LName Interface

The following operations are described in this section:

Destroying a Library Name Component Pseudo-Object

The destroy operation destroys library name component pseudo-objects.

void destroy();

Inserting a Name Component

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.

Getting the i^th Name Component

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.

Deleting a Name Component

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.

Number of Name Components

The num_components operation returns the number of components in a library name.

unsigned long num_components();

Testing for Equality

The equal operation tests for equality with library name ln.

boolean equal(in LName ln);

Testing for Order

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.

Producing an OMG IDL Form

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.

Translating an IDL Form

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);

Destroying a Library Name Pseudo-Object

The destroy operation destroys library name pseudo-objects.

void destroy();

C++ Mapping

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 BEA 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 BEA 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);
};

Java Mapping

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);
};

C++ Member Functions and Java Methods

This section describes the FactoryFinder C++ member functions and Java methods.

The following methods are described in this section:

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

Exception

CORBA::BAD_PARAM

CosLifeCycle::NoFactory

Description

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.

Return Values

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.

Tobj::FactoryFinder::find_one_factory

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

Exceptions

CORBA::BAD_PARAM

CosLifeCycle::NoFactory

Tobj::CannotProceed

Tobj::RegistrarNotAvailable

Description

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.

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

Tobj::FactoryFinder::find_one_factory_by_id

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

Exceptions

CORBA::BAD_PARAM

CosLifeCycle::NoFactory

Tobj::CannotProceed

Tobj::RegistrarNotAvailable

Description

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

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

Tobj::FactoryFinder::find_factories_by_id

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

Exceptions

CORBA::BAD_PARAM

CosLifeCycle::NoFactory

Tobj::CannotProceed

Tobj::RegistrarNotAvailable

Description

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

Return Values

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.

Tobj::Factoryfinder::list_factories

Synopsis

Obtains a list 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

Tobj::RegistrarNotAvailable

Description

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.

Return Values

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.

Automation Methods

This section describes the DITobj_FactoryFinder Automation methods.

DITobj_FactoryFinder.find_one_factory

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 Object

Parameters

factory_key

exceptionInfo

Exceptions

NoFactory

CannotProceed

RegistrarNotAvailable

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

Return Values

Returns a reference to an interface pointer for the application factory.

DITobj_FactoryFinder.find_one_factory_by_id

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 Object

Parameters

factory_id

exceptionInfo

Exceptions

NoFactory

CannotProceed

RegistrarNotAvailable

Description

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.

Return Values

Returns a reference to an interface pointer for the application factory.

DITobj_FactoryFinder.find_factories_by_id

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

exceptionInfo

Exceptions

NoFactory

CannotProceed

RegistrarNotAvailable

Description

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

Return Values

Returns a variant containing an array of interface pointers to application factories.

DITobj_FactoryFinder.find_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

exceptionInfo

Exception

NoFactory

Description

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

Return Values

Returns a variant containing an array of interface pointers to application factories.

DITobj_FactoryFinder.list_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

Exception

CannotProceed

RegistrarNotAvailable

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.

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

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.

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

// 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 Extensions Bootstrap object

The following code fragment (Listing 5-10) shows how to use of the BEA 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);

Using Extensions to the FactoryFinder Object

BEA 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 BEA Tuxedo extensions when developing an application. The interface Tobj::FactoryFinder is derived from the CosLifeCycle::FactoryFinder interface.

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

Obtaining One Factory Using Tobj::FactoryFinder

The following code fragment (Listing 5-11) shows how to use the BEA 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” );

Obtaining One or More Factories Using Tobj::FactoryFinder

The following code fragment (Listing 5-12) shows how to use the BEA 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” );