3 Introduction to Planning and Configuring CORBA Domains

The following sections explain how to plan and configure a domain for an Oracle Tuxedo CORBA Domains environment:

• Overview of the CORBA Domains Environment
  
• Single-Domain Versus Multiple-Domain Communication
  
• Elements of a CORBA Domains Configuration
  
• Understanding and Using the Configuration Files
  
• Specifying Unique Factory Object Identifiers in the factory_finder.ini File
  
• Processing the factory_finder.ini File
  
• Types of CORBA Domains Configurations
  
• Examples of CORBA Domains Configurations
  

3.1 Overview of the CORBA Domains Environment

An Oracle Tuxedo Domains configuration is an extension of the core ATMI domain environment, as explained in What Is the Oracle Tuxedo Domains Component?. An Oracle Tuxedo domain, or business application, is a construct that is entirely administrative. There are no programming interfaces that refer to domains. Only an administrator is aware of domains.

In an Oracle Tuxedo Domains configuration, an administrator can configure which services of a domain are available to other domains in the configuration. So, from a CORBA perspective, the Oracle Tuxedo Domains component is simply the means for Oracle Tuxedo CORBA applications to interoperate with one another and share resources. The CORBA clients and the participating applications themselves do not need to know anything about the Domains configuration. All they need to know is what factory objects are available and how to access those objects.

This transparency between domains allows administrators to configure services in individual domains and to spread resources across multiple domains. If applications were to include information about domains, changing configurations would require that the applications be rewritten as well.

3.2 Single-Domain Versus Multiple-Domain Communication

The following figure shows a simple Domains configuration consisting of two Oracle Tuxedo CORBA applications.

Figure 3-1 Domains Configuration Consisting of Two CORBA Applications

The single-domain and multiple-domain discussions that follow are based on this simple Domains configuration.

• Single-Domain Communication
  
• Multiple-Domain Communication
  

3.2.1 Single-Domain Communication

The following steps describe single-domain communication between CORBA Client X and Domain A in the simple Domains configuration:

1. Client X connects to Domain A using the Bootstrap object. The client application uses the Bootstrap object to locate a FactoryFinder and then uses the FactoryFinder to ask for a factory for objects of type Q. (The FactoryFinder call is itself an invocation on Domain A.)
2. When the FactoryFinder returns a factory, the client invokes that factory in Domain A.
3. The factory returns a reference to an object of type Q, called Q1.
4. The client then invokes on object Q1 in Domain A.

Throughout these steps, the client does not know where any of the objects are, or which domains they are in.

The administrative actions for connecting a client to Domain A are relatively simple for a client because the client is a simple machine and has very little infrastructure; it stands alone for the most part. Indeed, the connection to an Oracle Tuxedo domain is the primary administration for a client. The actual administrative chore is setting the address of the ISL that is in Domain A.

3.2.2 Multiple-Domain Communication

For multiple-domain communication, Q1 in the simple Domains configuration needs the services of Object R1, which is in Domain C; therefore, object Q1 must execute operations similar to those previously described in steps 1 through 4, but across domain boundaries. The actual steps are as follows:

1. Object Q1 uses a Bootstrap object to locate a FactoryFinder and then uses the FactoryFinder to ask for a factory for objects of type R.
2. When the FactoryFinder returns a reference to a factory in Domain C, Object Q1 invokes that factory.
3. The factory returns a reference to an object of type R, called R1.
4. Object Q1 invokes on Object R1.

As with Client X, there must be some administration to allow Object Q1 to get at the factories and objects in Domain C. As the simple Domains configuration shows, the mechanism for communication between domains is a domain gateway. A domain gateway is a system server in a domain.

A system server is different than a user-written server because it is part of the Oracle Tuxedo product; other system servers are the name servers, FactoryFinders, and ISLs. A domain gateway is somewhat similar in concept to an ISL because it is the “contact” point for a domain. It is different from an ISL, however, because a domain gateway connects to another domain gateway, which is itself a contact point for a domain; that is, a domain gateway’s job is to connect to another domain gateway. Thus, the pair of domain gateways cooperate to make sure that invocation on objects that inhabit different domains are routed to the correct domain.

3.3 Elements of a CORBA Domains Configuration

The following elements work together to accomplish an Oracle Tuxedo Domains configuration for CORBA:

Oracle Tuxedo configuration file

This text file, known as the UBBCONFIG file, names a domain and identifies the group and server entry for a domain gateway server. No attributes of domain gateways are specified in the UBBCONFIG file; all such attributes are in the Domains configuration file (explained next).

This text file, known as the UBBCONFIG file, names a domain and identifies the group and server entry for a domain gateway server. No attributes of domain gateways are specified in the UBBCONFIG file; all such attributes are in the Domains configuration file (explained next).

Note:

The Oracle Tuxedo configuration file may have any name as long as the content of the file conforms to the format described on reference page UBBCONFIG(5).

Domains configuration file

This text file, known as the DMCONFIG file, describes the remote domains that are connected to this domain—the local domain. One DMCONFIG file is required for each domain participating in a Domains configuration. If a domain is not connecting to another domain, the DMCONFIG file is not needed. Note that the Domains configuration file may have any name as long as the content of the file conforms to the format described on reference page DMCONFIG(5).

FactoryFinder Domains configuration file

This text file, known as factory_finder.ini, specifies which factories can be searched for or found across domain boundaries. One factory_finder.ini file is required for each domain participating in a CORBA Domains configuration. If a domain is not connecting to another domain, the factory_finder.ini file is not needed. You must carefully coordinate the factory_finder.ini file with the DMCONFIG so that they both have information about the same connected domains and provide the same connectivity.

Note:

The FactoryFinder Domains configuration file may have any name as long as the content of the file conforms to the format described on reference page factory_finder.ini(5).

Invocation of an object in a remote domain

From a CORBA perspective, the whole point of the Oracle Tuxedo Domains component is for an application in one CORBA domain to be able to make an invocation on an object in another CORBA domain, without either the client or server applications being aware that domains are a factor. Configuration information is intended to allow such invocations to cross domain boundaries and to hide those boundaries from applications.

References to objects in a remote domain

Any object reference may specify a local domain or a remote domain. A reference to a remote domain typically happens when a FactoryFinder returns a reference to a factory in a remote domain. It also happens when that factory, in turn, creates and returns a reference to an object in that remote domain (although, of course, the reference is local to the domain of the factory).

Note:

Applications are not aware of the domain of an object reference. Applications cannot find out what domain an object reference refers to.

FactoryFinders

For a server in a local domain to obtain an object reference to an object in another domain, the application uses the same FactoryFinder pattern as it does for objects in the local domain. The application uses the same pattern because it is not aware that the FactoryFinder returns a reference to a factory in another domain. The configuration files hide this fact. Once an object reference has been obtained via a FactoryFinder or factory, the object reference can be passed anywhere; that is, passed to objects in the local domain, returned to a client, or passed to another domain.

See Also:

For more information about UBBCONFIG(5), DMCONFIG(5), and factory_finder.ini(5) in the Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference

3.4 Understanding and Using the Configuration Files

You use the following three configuration files to set up a CORBA Domains configuration:

• UBBCONFIG, the Oracle Tuxedo configuration file
• DMCONFIG, the Domains configuration file
• factory_finder.ini, the FactoryFinder Domains configuration file

Each domain in a CORBA Domains configuration requires a set of these three files. As the administrator, you must coordinate the configurations within each set of configuration files and between sets of configuration files. As the number of domains grows in a Domains configuration, your effort to coordinate the configurations also grows.

• The UBBCONFIG File
  
• The DMCONFIG File
  
• The factory_finder.ini File
  

3.4.1 The UBBCONFIG File

You must specify the following parameters in the UBBCONFIG file to configure multiple domains:

• Domain Name
• Gateway Group
• Gateway Server
• Server Names

• Domain Name
  
• Gateway Group and Server Names
  

3.4.1.1 Domain Name

Though not required for single Oracle Tuxedo domains (that is, standalone domains), a domain that is connected to another domain must have a DOMAINID. You specify this parameter in the RESOURCES section of the UBBCONFIG file as follows:

DOMAINID domain_name

The domain_name must be 1 to13 characters long. For example:

DOMAINID headquarters

domain_name is the name that will be referenced in the DM_EXPORT and DM_IMPORT sections of the related DMCONFIG file. In that file, the domain_name will be referenced as:

"//domain_name"

The quotes are part of the reference. The slashes (//) mean that the name applies to Oracle Tuxedo CORBA domains, rather than to Oracle Tuxedo ATMI domains. For example:

"//headquarters"

Every domain in an enterprise must have a unique domain_name.

3.4.1.2 Gateway Group and Server Names

As with every other Oracle Tuxedo system server, there must be a group and a server name specified for a gateway. For example, the GROUPS section in the UBBCONFIG file might contain:

LGWGRP LMID=LDOM GRPNO=4

In this example, LGWGRP is a name chosen by a user (perhaps an abbreviation for “Local Gateway Group”).

The server name for an Oracle Tuxedo domain gateway—the TDomain gateway—is GWTDOMAIN and must be associated, like every other group, with a server group and a server ID. You specify the GWTDOMAIN name in the SERVERS section associated with the server group name chosen. For example:

GWTDOMAIN SRVGRP=LGWGRP SRVID=1

This entry tells the Oracle Tuxedo CORBA application that a TDomain gateway is to be used and that additional information is found in the DMCONFIG file.

3.4.2 The DMCONFIG File

Each Oracle Tuxedo domain participating in a Domains configuration requires its own DMCONFIG file. A DMCONFIG file describes the relationship between the local domain (the domain in which the DMCONFIG file resides) and one or more remote domains (the domains with which the local domain will interoperate).

In most documentation for the DMCONFIG file, the focus is on the configuring of Oracle Tuxedo ATMI domains to share services, a concept not applicable to Oracle Tuxedo CORBA environments. For an Oracle Tuxedo CORBA Domains environment, a “service” is simply the name of an Oracle Tuxedo domain that can service Oracle Tuxedo CORBA requests.

The following seven sections of the DMCONFIG file apply to a CORBA Domains environment:

• DM_LOCAL (also known as DM_LOCAL_DOMAINS)
• DM_REMOTE (also known as DM_REMOTE_DOMAINS)
• DM_EXPORT (also known as DM_LOCAL_SERVICES)
• DM_IMPORT (also known as DM_REMOTE_SERVICES)
• DM_RESOURCES
• DM_ACCESS_CONTROL
• DM_TDOMAIN

Note:

The DM_LOCAL section must precede the DM_REMOTE section.

Many of the of the parameters in these seven sections are not relevant to configuring a CORBA Domains environment because they are ATMI-specific parameters.

The discussions that follow are based on the sample DMCONFIG file shown in the following Listing

Listing Sample DMCONFIG File for a Oracle Tuxedo CORBA Domains Environment

#
# Oracle Tuxedo CORBA Domains Configuration File
#
*DM_RESOURCES
VERSION=Experimental8.9
*DM_LOCAL
LDOM   GWGRP=LGWGRP  TYPE=TDOMAIN  ACCESSPOINTID="MUTT"
*DM_REMOTE
TDOM1  TYPE=TDOMAIN  ACCESSPOINTID="JEFF"
*DM_EXPORT
"//MUTT"
*DM_IMPORT
"//JEFF" RACCESSPOINT=TDOM1
*DM_TDOMAIN
LDOM NWADDR="//sanfran.kmart.com:2507"
TDOM1 NWADDR="//sanhose.kmart.com:3186"

Note:

The ACCESSPOINTID parameter in this listing may be replaced with the DOMAINID parameter, and the RACCESSPOINT parameter may be replaced with the RDOM parameter. This listing uses the improved DMCONFIG terminology.

• DM_RESOURCES
  
• DM_LOCAL
  
• DM_REMOTE
  
• DM_EXPORT
  
• DM_IMPORT
  
• DM_ACCESS_CONTROL
  
• DM_TDOMAIN
  

3.4.2.1 DM_RESOURCES

The DM_RESOURCES section specifies global Domains configuration information, specifically a user-supplied configuration version string. The only parameter in this section is VERSION= string, where string is a field in which users can enter a version number for the current DMCONFIG file. This field is not checked by the software.

In the sample DMCONFIG file, the VERSION parameter is set to Experimental8.9:

*DM_RESOURCES
VERSION=Experimental8.9

3.4.2.2 DM_LOCAL

The DM_LOCAL section, also known as the DM_LOCAL_DOMAINS section, defines one or more local domain access points (logical names). For each local domain access point that you define, you specify a domain gateway group (TDOMAIN, ...) for the access point in this section, and—for the CORBA environment—you specify in the DM_EXPORT section the domain_name of the local Oracle Tuxedo domain available through the access point. The local domain will be available through the local domain access point to CORBA clients in one or more remote Oracle Tuxedo domains.

The DM_LOCAL section must have one and only one entry for each domain gateway group defined in the UBBCONFIG file. Each entry specifies the parameters required for the domain gateway processes running in that group.

Entries in the DM_LOCAL section have the form:

LocalAccessPoint required_parameters [optional_parameters]

where LocalAccessPoint is the local domain access point identifier (logical name) that you choose to represent a gateway group defined in the UBBCONFIG file. Note that the local domain access point is not the same name as the domain_name or the gateway group that is specified in the UBBCONFIG file. Rather, a local domain access point is a name used only within the DMCONFIG file to provide an extra level of insulation from potential changes in the UBBCONFIG file (changes in UBBCONFIG will affect only the defined parameters for the local domain access point, not the logical name of the local domain access point used throughout the DMCONFIG file).

The following parameters are required parameters:

GWGRP = identifier

This parameter specifies the name of a domain gateway server group (the name provided in the GROUPS section of the UBBCONFIG file) associated with this local domain access point.

TYPE = TDOMAIN

The TYPE parameter is required to specify the use of TDomain gateways for Oracle Tuxedo CORBA environments.

ACCESSPOINTID = string

The ACCESSPOINTID parameter, also known as DOMAINID, is used to identify the gateway group associated with this local domain access point for purposes of security when setting up connections to remote domains. The gateway server group specified in the GWGRP parameter uses this string during any security checks. It has no required relationship to the domain_name found in the RESOURCES section of the UBBCONFIG file. ACCESSPOINTIDmust be unique across both local and remote domains. The value of stringcan be a sequence of characters (for example, “BA.CENTRAL01”), or a sequence of hexadecimal digits preceded by 0x (for example, “0x0002FF98C0000B9D6”). ACCESSPOINTID must be 32 octets or fewer in length. If the value is a string, it must be 32 characters or fewer (counting the trailing NULL).

For example, the lines

*DM_LOCAL
LDOM GWGRP=LGWGRP TYPE=TDOMAIN ACCESSPOINTID="MUTT"

identify LDOM as the local domain access point associated with the local TDomain gateway group having server group name LGWGRP (as specified in the UBBCONFIG file). If the domain gateway is ever involved in a domain-to-domain security check, it goes by the name MUTT.

Note:

If the domain gateway is ever involved in a domain-to-domain security check and the CONNECTION_PRINCIPAL_NAME parameter is specified for the local domain access point, the gateway goes by the name specified in that parameter.

Optional parameters in the DM_LOCAL section describe resources and limits used in the operation of domain gateways. For a description of these parameters, see reference page DMCONFIG(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

3.4.2.3 DM_REMOTE

The DM_REMOTE section, also known as the DM_REMOTE_DOMAINS section, defines one or more remote domain access points (logical names). For each remote domain access point that you define, you specify a domain gateway group (TDOMAIN, ...) for the access point in this section, and—for the CORBA environment—you specify in the DM_IMPORT section the domain_name of the remote Oracle Tuxedo domain available through the access point. The remote domain will be available through the remote domain access point to CORBA clients in the local domain.

You can define multiple remote domain access points in this section, one or more for each domain gateway group used by this Oracle Tuxedo domain to communicate with a remote domain.

Entries in the DM_REMOTE section have the form:

RemoteAccessPoint required_parameters

where RemoteAccessPointis a remote domain access point identifier (logical name) that you choose for a particular remote domain to be accessed by a particular gateway group defined in the UBBCONFIG file. Note that a remote domain access point is not the same name as the domain_name or the gateway group that is specified in the local or remote domain’s UBBCONFIG file. Rather, a remote domain access point is a name used only within the DMCONFIG to provide an extra level of insulation from potential changes in UBBCONFIG (changes in UBBCONFIG will affect only the defined parameters for the remote domain access point, not the logical name of the remote domain access point used throughout the DMCONFIG file).

The required parameters are:

TYPE = TDOMAIN

The TYPE parameter is required to specify the use of TDomain gateways for Oracle Tuxedo CORBA environments.

ACCESSPOINTID = string

The ACCESSPOINTID parameter, also known as DOMAINID, is used to identify the remote domain associated with this remote domain access point for purposes of security when setting up a connection to the remote domain. The gateway uses this string during any security checks. ACCESSPOINTID has no required relationship to the domain_name found in the RESOURCES section of the UBBCONFIG file. ACCESSPOINTID must be unique across both local and remote domains. The value of string can be a sequence of characters (for example, “BA.BANK01”), or a sequence of hexadecimal digits preceded by 0x (for example, “0x0002FF98C0000B9D6”). ACCESSPOINTIDmust be 32 octets or fewer in length. If the value is a string, it must be 32 characters or fewer (counting the trailing NULL).

For example, the lines

*DM_REMOTE
TDOM1 TYPE=TDOMAIN ACCESSPOINTID="JEFF"

identify TDOM1 as a remote domain access point name associated with a local TDomain gateway group. If the domain gateway is ever involved in a domain-to-domain security check with a partner gateway, the gateway expects that partner to go by the name JEFF.

Note:

If the domain gateway is ever involved in a domain-to-domain security check and the CONNECTION_PRINCIPAL_NAME parameter is specified for the remote domain access point, the gateway expects the partner to go by the name specified in that parameter.

3.4.2.4 DM_EXPORT

The DM_EXPORT section, also known as the DM_LOCAL_SERVICES section, specifies in a CORBA environment the domain_name of the Oracle Tuxedo domain to be exported through a local domain access point defined in the DM_LOCAL section. The Oracle Tuxedo domain specified for a local domain access point is available to CORBA clients on one or more remote Oracle Tuxedo domains. The DM_EXPORT section is required for a CORBA Domains configuration.

Entries in the DM_EXPORT section have the form:

service [LACCESSPOINT=local access point name]
[ACL=...]

where service is of the form:

"//domain_name"

This domain_name is the name assigned to the DOMAINID parameter in the RESOURCES section of the local UBBCONFIG file. Entering this name in the DM_EXPORT section means that the local domain accepts CORBA requests from remote domains. Also possible is to specify a service entry that accepts requests for a domain name other than the domain name of the local domain, in the case where the local domain acts as a pass-through for routing purposes.

The optional parameter, ACL, specifies the name of the access control list (ACL) to be used by the local domain to restrict requests made to the local domain by remote Oracle Tuxedo CORBA domains. The name of the ACL is defined in the DM_ACCESS_CONTROL section of the DMCONFIG file. If this parameter is not specified, access control is not performed for remote requests to the local domain.

For example, the lines:

*DM_EXPORT
"//MUTT"

mean that the local domain with name MUTT accepts remote CORBA requests through any remote domain access point defined in the DM_REMOTE section.

3.4.2.5 DM_IMPORT

The DM_IMPORT section, also known as the DM_REMOTE_SERVICES section, specifies in a CORBA environment the domain_name of the Oracle Tuxedo domain to be imported through a remote domain access point defined in the DM_REMOTE section. The Oracle Tuxedo domain specified for a remote domain access point is available to CORBA clients on the local domain. The DM_IMPORT section is required for a CORBA Domains configuration.

Entries in the DM_IMPORT section have the form:

service [RACCESSPOINT=remote domain access point]
[LACCESSPOINT=local domain access point]
         [TRANTIME=...]

where service is of the form:

"//domain_name"

This domain_name is the name assigned to the DOMAINID parameter in the RESOURCES section of the remote UBBCONFIG file. Entering this name in the DM_IMPORT section means that the remote domain accepts CORBA requests from the local domain. Also possible is to specify a service entry that accepts requests for a domain name other than the domain name of the remote domain, in the case where the remote domain acts as a pass-through for routing purposes.

For example, the lines:

*DM_IMPORT
"//JEFF" RACCESSPOINT=TDOM1

mean that the remote domain with name JEFF and associated with remote domain access point TDOM1 accepts CORBA requests through any local domain access point defined in the DM_LOCAL section.

3.4.2.6 DM_ACCESS_CONTROL

The DM_ACCESS_CONTROL section specifies one or more access control list (ACL) names and associates one or more remote domain access points with each specified ACL name. You can use the ACL parameter in the DM_EXPORT section by setting ACL=ACL_NAME to restrict access to a local domain exported through a particular local domain access point to just those remote domain access points associated with the ACL_NAME .

Entries in the DM_ACCESS_CONTROL section have the form:

ACL_NAME required_parameters

where ACL_NAME is an identifier used to specify an access control list; it may contain no more than 15 characters.

The only required parameter is:

ACLIST = identifier [, identifier ]

where an ACLIST is composed of one or more remote domain access point names separated by commas. The wildcard character (*) can be used to specify that all the remote domain access points defined in the DM_REMOTE section can access a local domain.

3.4.2.7 DM_TDOMAIN

The DM_TDOMAIN section defines the network addressing information for the TDomain gateways implementing the Oracle Tuxedo CORBA domains. The DM_TDOMAIN section must have:

• One entry per local domain access point if CORBA requests from remote domains are accepted through that access point
• One entry per remote domain access point if CORBA requests from the local domain to the remote domain are accepted through that access point

In the DM_TDOMAIN section, you can also define the configuration for one or more remote domain access points associated with one or more WebLogic Server applications, to combine Tuxedo CORBA servers and WebLogic Server Enterprise JavaBean (EJB) servers in an application. For details, see “Interoperability with Oracle WebLogic Server” on page2‑1 in Oracle Tuxedo Interoperability.

Entries in the DM_TDOMAIN section have the form:

AccessPoint required_parameters [optional_parameters]

where AccessPointis an identifier value used to identify either (1) a local domain access point in the DM_LOCAL section or (2) a remote domain access point in the DM_REMOTE section.

The following parameter is required:

NWADDR = string

This parameter specifies the network address associated with a local domain access point or a remote domain access point. If the association is with a local domain access point, the network address is used by the local domain gateway to listen for connection requests from remote domains. If the association is with a remote domain access point, the network address is used by the local domain gateway to initiate a connection to the remote domain.

If string has the form "0x hex-digits " or "\\x hex-digits ", it must contain an even number of valid hex digits. These forms are translated internally into a character array containing TCP/IP addresses. The addresses may also be in either of the following two forms:

"//hostname:port_number"
"//#.#.#.#:port_number"

In the first of these formats, hostname is resolved to a TCP/IP host address at the time the address is bound, using the locally configured name resolution facilities accessed via gethostbyname(3c). The " # . # . # . # " is the dotted decimal format, where each # represents a decimal number in the range 0 to 255.

Port_number is a decimal number in the range 0 to 65535 (the hexadecimal representations of the string specified).

For example, the lines:

*DM_TDOMAIN
LDOM NWADDR="//sanfran.kmart.com:2507"
TDOM1 NWADDR="//sanhose.kmart.com:3186"

mean that the TDomain gateway belonging to gateway group LGWGRP—as stated in the DM_LOCAL section for the LDOM access point—is configured to listen at address "//sanfran.kmart.com:2507" for connection requests from remote domains. The TDomain gateway is also configured to initiate a connection to "//sanhose.kmart.com:3186" when sending requests to the remote domain associated with the TDOM1 access point.

For a description of the optional parameters for the DM_TDOMAIN section, see reference page DMCONFIG(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

3.4.3 The factory_finder.ini File

The factory_finder.ini file identifies the remote factory objects that can be used in the local domain. It also identifies the local factory objects that can be used in remote domains.

The factory_finder.ini file contains two sections, DM_REMOTE_FACTORIES and DM_LOCAL_FACTORIES. As clarified in the following display, the format of the factory_finder.ini file is modeled after the syntax used in the DMCONFIG file:

*DM_REMOTE_FACTORIES
"local_factory_id.factory_kind"
DOMAINID="domain_id"
RNAME="remote_factory_id.factory_kind"
...
*DM_LOCAL_FACTORIES
"factory_id.factory_kind"

The following display demonstrates the syntax for CORBA factory objects:

*DM_REMOTE_FACTORIES
"AccountFactory.FactoryKind"
DOMAINID="MyAccountFactoryDomain"
RNAME="MyAccountFactory.FactoryKind

where AccountFactory is the name used to register the factory in the local domain’s FactoryFinder, MyAccountFactoryDomain is the name of the remote domain, and MyAccountFactory is the name used to register the factory in the remote domain’s FactoryFinder.

Note:

No two CORBA domains participating in a Domains configuration are allowed to have factory objects with the same factory_id.factory_kind identifier. For details, see Specifying Unique Factory Object Identifiers in the factory_finder.ini File.

• DM_REMOTE_FACTORIES
  
• DM_LOCAL_FACTORIES
  

3.4.3.1 DM_REMOTE_FACTORIES

The DM_REMOTE_FACTORIES section specifies which factory objects in remote domains are available (imported) to the local domain. Identifiers for remote factory objects are listed in this section. The identifier, under which the object is registered, including a kind value of FactoryInterface, must be listed in this section. For example, the entry for a remote factory object to be registered by the TP Framework with the identifier Teller in domain Norwest would be specified as:

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

If the RNAME is not specified, the factory_kind must be specified in the factory name, and the factory name must be enclosed in quotation marks; otherwise, the NameManager is not able to locate the appropriate factory. An entry that does not contain a factory_kind value is not defaulted with a value of FactoryInterface.

The following example shows a factory object to be registered with the identifier Teller in domain Norwest. Note the absence of the RNAME specification, the specification of the factory_kind value, and the quotation marks around the factory name.

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"

Because the identities of factories in a Domains configuration may collide, the factory identifier and the RNAME parameters allow you to specify alternative identities, or “aliases,” in the local domain for remote factories. The following Listing shows two examples of a remote factory that is registered by the TP Framework with the identifier BankTeller in domain Norwest. In both examples, the factory is made available in the local domain with an alias of Teller.

Listing Assigning an Alias to a Remote Factory

#EXAMPLE 1:
*DM_REMOTE_FACTORIES
Teller
DOMAINID="Norwest"
RNAME=”BankTeller.FactoryInterface”
#EXAMPLE 2:
*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

You can also assign multiple aliases to the same remote factory. In the example shown in the following Listing, the remote factory will be registered in the local domain with two aliases: Teller and BankTeller.

Listing Assigning Multiple Aliases to a Remote Factory

*DM_REMOTE_FACTORIES
"Teller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"
"BankTeller.FactoryInterface"
DOMAINID="Norwest"
RNAME="BankTeller.FactoryInterface"

3.4.3.2 DM_LOCAL_FACTORIES

The DM_LOCAL_FACTORIES section specifies which factory objects in the local domain are available (exported) to remote domains. This section can be used in the following ways:

• If the DM_LOCAL_FACTORIES section is not present in a factory_finder.ini, or is present but empty, all factory objects in the local domain are available to remote domains. This software behavior allows administrators an easy means to make local factory objects available to remote domains without having to provide an entry for every factory object in the local domain.
• If the DM_LOCAL_FACTORIES section is present in a factory_finder.ini file but contains the reserved keyword NONE, none of the factory objects in the local domain are available to remote domains. Using the NONE keyword allows administrators to restrict access without having to provide an entry for every factory object in the local domain.

The identifier, or name, under which the factory object is registered, including a kind value of FactoryInterface, must be listed in the DM_LOCAL_FACTORIES section. For example, the entry for a factory object to be registered by the TP Framework with the identifier Teller would be specified as:

*DM_LOCAL_FACTORIES
"Teller.FactoryInterface"

The factory_kind must be specified for the NameManager to locate the appropriate factory object. An entry that does not contain a factory_kind value is not defaulted with a value of FactoryInterface. This software behavior allows for the use of the CORBA NamingService.

An entry into the file for Domain A might be:

*DM_REMOTE_FACTORIES
fA.FactoryInterface DOMAINID=B

This entry means that a request in Domain A to find a factory with the identifier fA can be satisfied by the FactoryFinder in Domain B. Of course, the UBBCONFIG and DMCONFIG files for the two domains must also be set up so that there are connected domain gateways between the two domains.

An alternate form of the entry is:

CDE.FactoryInterface DOMAINID=B RNAME=fA.FactoryInterface

This entry means that a request in Domain A to find a factory with the identifier CDE will be satisfied by the FactoryFinder in Domain B using the ID fA. The alternate form is sometimes called an alias.

Note:

The factory ID must have .FactoryInterface at the end. For simplicity, in discussions about test configurations, the .FactoryInterface is left off, but it should appear in the factory_finder.ini file.

See Also:

• UBBCONFIG(5), DMCONFIG(5), and factory_finder.ini(5) in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference

3.5 Specifying Unique Factory Object Identifiers in the factory_finder.ini File

In a single-domain configuration, multiple factory objects with the same name are allowed, to achieve load balancing. In a Domains configuration, however, no two domains are allowed to have factory objects with the same factory_id.factory_kind identifier. If the same identifier, or name, is used in two domains, the software’s behavior varies depending on whether or not Oracle WebLogic Enterprise was used to configure the CORBA Domains environment:

• In releases prior to Oracle WebLogic Enterprise 5.1, the software allows the first server in a domain to register the factory without issuing an error message. If two factories with the same name are registered in a domain, the Master NameManager fails.
• In Oracle WebLogic Enterprise 5.1 or later and Oracle Tuxedo 8.0 or later, the software generates an error and writes it to the ULOG.

There are two ways to ensure that your identifiers, or names, are unique across domains and thus avoid this problem:

• In Oracle WebLogic Enterprise 5.1 or later and Oracle Tuxedo 8.0 or later, the software generates an error and writes it to the ULOG.
• In the factory_finder.ini file, use the RNAME parameter so that an alias is used by the local NameManager. Choosing this method means that you must also modify local clients to use the alias to access the remote factory object. The listing Assigning an Alias to a Remote Factory shows an example of a factory_finder.ini file that uses the RNAME parameter to create an alias.

3.6 Processing the factory_finder.ini File

When starting up, the Master NameManager reads the factory_finder.ini file. The condition under which the Master NameManager is started determines whether the Master NameManager reads all or just some of the factory_finder.ini file:

• If the Master NameManager process is started as part of booting the CORBA application (the initialization mode), it reads the entire content of the factory_finder.ini file. Thus, any new factory objects added to the DM_REMOTE_FACTORIES section of the factory_finder.ini file are made known to the local Oracle Tuxedo application.
• If the Master NameManager process is restarted as a result of process failure, it reads only the DM_LOCAL_FACTORIES section of the factory_finder.ini file. Thus, any new factory objects added to the DM_REMOTE_FACTORIES section are not made known to the local Oracle Tuxedo application.

When adding a new domain with factory objects to the DM_REMOTE_FACTORIES section of the factory_finder.ini file, you must shut down and restart the Master NameManager. For more information about NameManager, see TMFFNAME(5)in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

3.7 Types of CORBA Domains Configurations

When using the Oracle Tuxedo Domains component to connect multiple Oracle Tuxedo CORBA domains, you can configure two types of configurations: directly connected domains and indirectly connected domains. You, as the administrator, configure both types using the DMCONFIG file.

• Directly Connected Domains
  
• Indirectly Connected Domains
  

3.7.1 Directly Connected Domains

Every domain in a Domains configuration can have a gateway connection—a direct connection—to every other domain in the Domains configuration. With directly connected domains, a request goes directly to the target domain.

A directly connected Domains configuration, or “n-way” configuration, is reasonable when the number of domains is small, but each new domain added to the configuration requires two, four, ... or more new gateways. At some point, you may consider giving up speed of delivery for ease of management of domain connections by configuring indirectly connected domains.

3.7.2 Indirectly Connected Domains

You should consider what the likely traffic patterns are. Domains that have only occasional interactions are candidates for gateway removal. Since there will still be interactions, it must still be possible to reach the other domain. The technique used is to route the request through an intermediate domain that does have direct access to the target domain.

For example, consider the three domains, A, B, and C, shown in the following figure.

Figure 3-2 Indirectly Connected Domains

Domains A and B are directly connected, and Domains B and C are directly connected, but A and C are not directly connected. For Domains A and C to communicate, they must use Domain B as the intermediary. Therefore, the DMCONFIG file for Domain A must state that it is possible to connect to Domain C by going through Domain B (and vice versa). That is, the connectivity is:

Domains     A   <->  B <-> C
Gateways        GAB GBA       GBC GCB

Domain A has a gateway process, GAB (the gateway from A to B), that connects to Domain B. The Domain A DMCONFIG file states that GAB acts as a gateway to two domains, Domains B and C. The DMCONFIG file for Domain C has a similar configuration, stating that GCB is connected to B and A. The DMCONFIG file for Domain B has two gateway processes, one which connects to A (GBA) and one which connects to C (GBC). This configuration is called an indirect connection.

Given this indirect connection, when a server in A invokes a request on an object in C, Oracle Tuxedo CORBA server knows that it can send the request to gateway GAB. The Oracle Tuxedo gateway does not know that its partner gateway in B cannot service the request itself, but that is acceptable. Once the request is in Domain B, it is routed through GBC to C, which can service the request. Thus, the request is serviced with one extra hop.

It is even possible for the two gateways in Domain B to be a single gateway, so that there is not an extra hop within B. In effect, the same processing occurs in Domain B, but it all occurs within a single gateway process.

3.8 Examples of CORBA Domains Configurations

The following examples show how to configure directly connected CORBA domains. If you want to use these examples, you will need to change the APPDIR, TUXCONFIG, and TUXDIR variables to match your environment. Also, you will have to substitute appropriate information wherever text is enclosed by left (<) and right (>) angle brackets (for example, <App Server Name> ) and delete the angle brackets.

• Sample UBBCONFIG Files
  
• Sample DMCONFIG File
  
• Sample factory_finder.ini File
  

3.8.1 Sample UBBCONFIG Files

The following Listings show the UBBCONFIG files for three directly connected domains: Here, There, and Yonder. To use these files, you must replace host with the name of the local machine.

Listing UBBCONFIG File for the Here Domain

#
#
#
# RESOURCES
#
*RESOURCES
IPCKEY 123312
DOMAINID HereD
MASTER LAPP
MODEL SHM
LDBAL N#
# MACHINES
#
*MACHINES
<host>
LMID=LAPP
APPDIR="/tst1/wle4.2/test_dom/t07:
/tst1/wle4.2/dec_unix/wlemdomai"
TUXCONFIG="/tst1/wle4.2/test_dom/tuxconfig"
TUXDIR="/lclobb/lc"
MAXWSCLIENTS=10
#
# GROUPS
#
*GROUPS
DEFAULT: LMID=LAPP
ICEGRP GRPNO=11 OPENINFO=NONE
GROUP1 GRPNO=21 OPENINFO=NONE
LDMGRP GRPNO=3
LGWGRP GRPNO=4
#
# SERVERS
#
*SERVERS
DEFAULT: CLOPT="-A"
DMADM SRVGRP=LDMGRP SRVID=1
GWADM SRVGRP=LGWGRP SRVID=1
GWTDOMAIN SRVGRP=LGWGRP SRVID=2
TMSYSEVT SRVGRP=ICEGRP SRVID=1
TMFFNAME SRVGRP=ICEGRP SRVID=2
CLOPT="-A -- -N -M -f <FF ini file for Here>"
TMFFNAME SRVGRP=ICEGRP SRVID=3 CLOPT="-A -- -N"
TMFFNAME SRVGRP=ICEGRP SRVID=4 CLOPT="-A -- -F"
<App Server Name> SRVGRP=GROUP1 SRVID=2
ISL SRVGRP=GROUP1 SRVID=1
CLOPT="-A -- -d /dev/tcp -n //<host>:<port>"
#
# SERVICES
#
*SERVICES
 

Listing UBBCONFIG File for the “There” Domain

#
#
# RESOURCES
#
*RESOURCES
IPCKEY 133445
DOMAINID ThereD
MASTER LAPP1
MODEL SHM
LDBAL N
#
# MACHINES
#
*MACHINES
<host>
LMID=LAPP1
APPDIR="D:\test_dom\t07;D:\Iceberg\qa\orb\bld\wlemdomain"
TUXCONFIG="D:\test_dom\tuxconfig"
TUXDIR="D:\Iceberg"
MAXWSCLIENTS=10
#
# GROUPS
#
*GROUPS
DEFAULT LMID=LAPP1
ICEGRP GRPNO=11 OPENINFO=NONE
GROUP1 GRPNO=21 OPENINFO=NONE
LDMGRP GRPNO=3
LGWGRP GRPNO=4
#
# SERVERS
#
*SERVERS
DEFAULT: CLOPT="-A"
DMADM SRVGRP=LDMGRP SRVID=1
GWADM SRVGRP=LGWGRP SRVID=1
GWTDOMAIN SRVGRP=LGWGRP SRVID=2
TMSYSEV SRVGRP=ICEGRP SRVID=1
TMFFNAME SRVGRP=ICEGRP SRVID=2
CLOPT="-A -- -N -M -f <FF ini file for There>"
TMFFNAME SRVGRP=ICEGRP SRVID=3 CLOPT="-A -- -N"
TMFFNAME SRVGRP=ICEGRP SRVID=4 CLOPT="-A -- -F"
<App Server Name> SRVGRP=GROUP1 SRVID=2
ISL SRVGRP=GROUP1 SRVID=1
CLOPT="-A -- -d /dev/tcp -n //<host>:<port>"
#
# SERVICES
#
*SERVICES

Listing UBBCONFIG File for the Yonder Domain

#
# RESOURCES
#
*RESOURCES
IPCKEY 123334
DOMAINID YonderD
MASTER LAPP
MODEL SHM
LDBAL N
#
# MACHINES
#
*MACHINES
<host>
LMID=LAPP
APPDIR="/tst1/wle4.2/test_dom/t07p:
/tst1/wle4.2/<host3>/wlemdomain"
TUXCONFIG="/tst1/wle4.2/test_dom/<host3>/tuxconfig"
TUXDIR="/lclobb/lc"
MAXWSCLIENTS=10
#
# GROUPS
#
*GROUPS
DEFAULT: LMID=LAPP
ICEGRP GRPNO=11 OPENINFO=NONE
GROUP1 GRPNO=21 OPENINFO=NONE
LDMGRP GRPNO=3
LGWGRP GRPNO=4
#
# SERVERS
#
*SERVERS
DEFAULT: CLOPT="-A"
DMADM SRVGRP=LDMGRP SRVID=1
GWADM SRVGRP=LGWGRP SRVID=1
GWTDOMAIN SRVGRP=LGWGRP SRVID=2
TMSYSEVT SRVGRP=ICEGRP SRVID=1
TMFFNAME SRVGRP=ICEGRP SRVID=2
CLOPT="-A -- -N -M"
TMFFNAME SRVGRP=ICEGRP SRVID=3 CLOPT="-A -- -N"
TMFFNAME SRVGRP=ICEGRP SRVID=4 CLOPT="-A -- -F"
<App Server Name> SRVGRP=GROUP1 SRVID=2
ISL SRVGRP=GROUP1 SRVID=1
CLOPT="-A -- -d /dev/tcp -n //<host>:<port>"
#
# SERVICES
#
*SERVICES

3.8.2 Sample DMCONFIG File

The following Listings show the DMCONFIG files for three directly connected domains: Here, There, and Yonder. To use these listings in a Domains configuration, you must replace host1 with the name of the local machine for the Here domain, replace host2 with the name of the local machine for the There domain, and replace host3 with the name of the local machine for the Yonder domain.

Listing DMCONFIG File for the Local Machine in the Here Domain in a Three-Domain Configuration

#
#
# Tuxedo Domains Configuration File
#
*DM_RESOURCES
VERSION=U22
#
# DM_LOCAL
#
*DM_LOCAL
LDOM1 GWGRP=LGWGRP TYPE=TDOMAIN ACCESSPOINTID="HereG"
#
# DM_REMOTE
#
*DM_REMOTE
TDOM1 TYPE=TDOMAIN ACCESSPOINTID="ThereG"
TDOM2 TYPE=TDOMAIN ACCESSPOINTID="YonderG"
#
# DM_TDOMAIN
#
*DM_TDOMAIN
LDOM1 NWADDR="//<host1>:<tcpport>"
TDOM1 NWADDR="//<host2>:<tcpport>"
TDOM2 NWADDR="//<host3>:<tcpport>"
#
# DM_EXPORT
#
*DM_EXPORT
"//HereD"
#
# DM_IMPORT
#
*DM_IMPORT
"//ThereD" RACCESSPOINT=TDOM1
"//YonderD" RACCESSPOINT=TDOM2

To use the following listing in a Domains configuration, you must replace host1 with the name of the local machine for the There domain, replace host2 with the name of the local machine for the Here domain, and replace host3 with the name of the local machine for the Yonder domain.

Listing DMCONFIG File for the There Domain in a Three-Domain Configuration

#
#
# Tuxedo Domains Configuration File
#
*DM_RESOURCES
VERSION=U22
#
# DM_LOCAL
#
*DM_LOCAL
LDOM1 GWGRP=LGWGRP TYPE=TDOMAIN ACCESSPOINTID="ThereG"
#
# DM_REMOTE
#
*DM_REMOTE
TDOM1 TYPE=TDOMAIN ACCESSPOINTID="HereG"
TDOM2 TYPE=TDOMAIN ACCESSPOINTID="YonderG"
#
# DM_TDOMAIN
#
*DM_TDOMAIN
LDOM1 NWADDR="//<host1>:<tcpport>"
TDOM1 NWADDR="//<host2>:<tcpport>"
TDOM2 NWADDR="//<host3>:<tcpport>"
#
# DM_EXPORT
#
*DM_EXPORT
"//ThereD"
#
# DM_IMPORT
#
*DM_IMPORT
"//HereD" RACCESSPOINT=TDOM1
"//YonderD" RACCESSPOINT=TDOM2

To use the following listing in a Domains configuration, you must replace host1 with the name of the local machine for the Yonder domain, replace host2 with the name of the local machine for the Here domain, and replace host3 with the name of the local machine for the There domain.

Listing DMCONFIG File for the Yonder Domain in a Three-Domain Configuration

#
#
# Tuxedo Domains Configuration File
#
*DM_RESOURCES
VERSION=U22
#
# DM_LOCAL
#
*DM_LOCAL
LDOM1 GWGRP=LGWGRP TYPE=TDOMAIN ACCESSPOINTID="YonderG"
#
# DM_REMOTE
#
*DM_REMOTE
TDOM1 TYPE=TDOMAIN ACCESSPOINTID="HereG"
TDOM2 TYPE=TDOMAIN ACCESSPOINTID="ThereG"
#
# DM_TDOMAIN
#
*DM_TDOMAIN
LDOM1 NWADDR="//<host1>:<tcpport>"
TDOM1 NWADDR="//<host2>:<tcpport>"
TDOM2 NWADDR="//<host3>:<tcpport>"
#
# DM_EXPORT
#
*DM_EXPORT
"//YonderG"
#
# DM_IMPORT
#
*DM_IMPORT
"//HereD" RACCESSPOINT=TDOM1
"//ThereD" RACCESSPOINT=TDOM2

3.8.3 Sample factory_finder.ini File

The following Listings show the factory_finder.ini files for the Here and There domains. The Yonder domain does not require a factory_finder.ini file.

Listing factory_finder.ini File for the Here Local Domain

#
# Factory Finder Initialization file for Domain “Here”
# This is the local domain.
#
# DM_LOCAL_FACTORIES
#
*DM_LOCAL_FACTORIES
"AFactory.FactoryInterface"
#
# DM_REMOTE_FACTORIES
#
*DM_REMOTE_FACTORIES
"AFacYonder.FactoryInterface"
DOMAINID="YonderD"
RNAME="AFactory.FactoryInterface"

"BFactory.FactoryInterface"
DOMAINID="YonderD"

Listing factory_finder.ini File for the There Remote Domain

#
# Factory Finder Initialization file for Domain “There”
# This is a remote domain.
#
# DM_LOCAL_FACTORIES
#
*DM_LOCAL_FACTORIES
"AFactory.FactoryInterface"
#
# DM_REMOTE_FACTORIES
#
*DM_REMOTE_FACTORIES
"AFacYonder.FactoryInterface"
DOMAINID="YonderD"
RNAME="AFactory.FactoryInterface"
"BFactory.FactoryInterface"
DOMAINID="YonderD"