BEA WebLogic Enterprise 4.2    Developer Center     

        HOME   |   SITE MAP   |   SEARCH   |   CONTACT   |   GLOSSARY  |   PDF FILES |   WHAT'S NEW 
 
        Administration    |   TABLE OF CONTENTS   |   PREVIOUS TOPIC   |   NEXT TOPIC   |   INDEX 

Distributing Applications


This chapter discusses the following topics:

Why distribute an application?

Distributing an application enables you to select which parts of an application should be grouped together logically and where these groups should run. You distribute an application by creating more than one entry in the GROUPS section of the UBBCONFIG file, and by dividing application resources or tasks among the groups. Creating groups of servers enables you to partition a very large application into its component business applications, and in turn each of these into logical components of manageable size and optimal location.

Benefits of a Distributed Application

Characteristics of Distributing an Application

A distributed application has the following characteristics:

Using Factory-based Routing (WLE Servers)

Factory-based routing is a WLE feature that you can use to distribute processing of CORBA interface invocations across specific server groups. Routing is done when a factory creates an object reference. The factory specifies field information in its call to the WLE TP Framework to create an object reference.

The TP Framework executes the routing algorithm based on the routing criteria that you define in the ROUTING section of an application's UBBCONFIG file. The resulting object reference has as its target an appropriate server group for the handling of method invocations on the object reference. Any server that implements the interface in that server group is eligible to activate the servant for the object reference.

The activation of CORBA objects can be distributed by server group based on a criteria defined by you, in cooperation with a system designer. Different implementations of CORBA interfaces can be supplied in different groups. This feature enables you to replicate the same CORBA interface across multiple server groups, based on group-specific differences that you define.

The factory-based routing criteria must be personally communicated to you by the system designer of the application. In the BEA TUXEDO system, an FML field used for a service invocation can be used for routing. This information can be discovered by you independently. For WLE client and server applications, because the routing is done at the factory level and not on a method invocation on the target CORBA object, there is no service request message data or associated buffer information available for routing.

Characteristics of Factory-based Routing

Factory-based routing has the following characteristics:

Example: Factory-based Routing

The University Production sample application demonstrates how to implement factory-based routing. You can find the ubb_p.nt or ubb_p.mk UBBCONFIG files for this sample in the directory where the WLE software is installed. Look in the \samples\corba\university\production subdirectory.

The following INTERFACES, ROUTING, and GROUPS sections from the ubb_b.nt configuration file show how you can implement factory-based routing in a WLE application.

The INTERFACES section lists the names of the interfaces for which you want to enable factory-based routing. For each interface, this section specifies what kinds of criteria the interface routes on. This section specifies the routing criteria via an identifier, FACTORYROUTING, as in the following example:

*INTERFACES

"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID

"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUM

The preceding example shows the fully qualified interface names for the two interfaces in the Production sample application in which factory-based routing is used. The FACTORYROUTING identifier specifies the names of the routing values, which are STU_ID and ACT_NUM, respectively.

The ROUTING section specifies the following data for each routing value:

The following example shows the ROUTING section of the UBBCONFIG file used in the Production sample application:

*ROUTING

STU_ID
FIELD = "student_id"
TYPE = FACTORY
FIELDTYPE = LONG
RANGES = "100001-100005:ORA_GRP1,100006-100010:ORA_GRP2"

ACT_NUM
FIELD = "account_number"
TYPE = FACTORY
FIELDTYPE = LONG
RANGES = "200010-200014:APP_GRP1,200015-200019:APP_GRP2"

The preceding example shows that Registrar objects for students with IDs in one range are instantiated to one server group, and Registrar objects for students with IDs in another range are instantiated in another group. Likewise, Teller objects for accounts in one range are instantiated to one server group, and Teller objects for accounts in another range are instantiated in another group.

The groups specified by the RANGES identifier in the ROUTING section of the UBBCONFIG file need to be identified and configured. For example, the Production sample application specifies four groups: ORA_GRP1, ORA_GRP2, APP_GRP1, and APP_GRP2. These groups need to be configured, and the machines on which they run need to be identified.

The following example shows the GROUPS section of the Production sample UBBCONFIG file. Notice how the names in the GROUPS section match the group names specified in the ROUTING section; this is critical for factory-based routing to work correctly. Furthermore, any change in the way groups are configured in an application must be reflected in the ROUTING section. (Note that the Production sample application packaged with the WLE software is configured to run entirely on one machine. However, you can easily configure this application to run on multiple machines.)

*GROUPS

APP_GRP1
LMID = SITE1
GRPNO = 2
TMSNAME = TMS

APP_GRP2
LMID = SITE1
GRPNO = 3
TMSNAME = TMS

ORA_GRP1
LMID = SITE1
GRPNO = 4
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"
   CLOSEINFO = ""
TMSNAME = "TMS_ORA"

ORA_GRP2
LMID = SITE1
GRPNO = 5
OPENINFO = "ORACLE_XA:Oracle_XA+Acc=P/scott/tiger+SesTm=100+LogDir=.+MaxCur=5"

CLOSEINFO = ""
TMSNAME = "TMS_ORA"

Using Data-dependent Routing (BEA TUXEDO Servers)

Data-dependent routing is a mechanism whereby a service request is routed by a client (or a server acting as a client) to a server within a specific group based on a data value contained within the buffer that is sent. Within the internal code of a service call, the BEA TUXEDO system chooses a destination server by comparing a data field with the routing criteria it finds in the Bulletin Board shared memory.

For any given service, a routing criteria identifier can be specified in the SERVICES section of the UBBCONFIG file. The routing criteria identifier, in particular, the mapping of data ranges to server groups, is specified in the ROUTING section.

Characteristics of Data-dependent Routing

Data-dependent routing has the following characteristics:

Example: A Distributed Application

The following table illustrates how client requests are routed to servers. In this example, a banking application called bankapp uses data-dependent routing. For bankapp, there are three groups (BANKB1, BANKB2, and BANKB3), and two routing criteria (Account ID and Branch ID). The services WITHDRAW, DEPOSIT, and INQUIRY are routed using the Account_ID field; the services OPEN and CLOSE are routed using the Branch_ID field.

Server Group Routing Criteria Used For These Services

BANKB1

Account_ID: 10000 - 49999

WITHDRAW, DEPOSIT, and INQUIRY

Branch_ID: 1 - 4

OPEN and CLOSE

BANKB2

Account_ID: 50000 - 79999

WITHDRAW, DEPOSIT, and INQUIRY

Branch_ID: 5 - 7

OPEN and CLOSE

BANKB3

Account_ID: 80000 - 109999

WITHDRAW, DEPOSIT, and INQUIRY

Branch_ID: 8 - 10

OPEN and CLOSE

Modifying and Creating the UBBCONFIG Sections for a Distributed Application

Data-dependent routing (BEA TUXEDO system) or factory-based routing (WLE system) is described in the UBBCONFIG file, as follows:

Modifying the GROUPS Section

Parameters in the GROUPS section implement two important aspects of distributed transaction processing. They associate a group of servers with a particular LMID and a particular instance of a resource manager. In addition, by allowing a second LMID to be associated with the server group, they name an alternate machine to which a group of servers can be migrated if the MIGRATE option is specified. Table 5-1 describes the parameters in the GROUPS section.

Table 5-1 Description of the GROUPS Section Parameters

Parameter Meaning

LMID

LMID must be assigned in the MACHINES section. It indicates that this server group runs on this particular machine. A second LMID value can be specified (separated from the first by a comma) to name an alternate machine to which this server group can be migrated if the MIGRATE option has been specified. Servers in the group must specify RESTART=Y to migrate.

GRPNO

GRPNO is a required parameter that associates a numeric group number with this server group. The number must be greater than 0 and less than 30000. It must be unique among entries in the GROUPS section in this configuration file.

TMSNAME

Specifies which transaction management server (TMS) should be associated with this server group.

TMSCOUNT

An optional parameter that can be used to specify how many copies of TMSNAME should be started for this server group. The minimum value is 2. If not specified, the default is 3. All TMSNAME servers started for a server group are automatically set up in an MSSQ set.

OPENINFO

Specifies information needed to open a particular instance of a particular resource manager, or it indicates that such information is not required for this server group. When a resource manager is named in the OPENINFO parameter, information such as the name of the database and the access mode is included. The entire value string must be enclosed in double quotes and must not be more than 256 characters. The format of the OPENINFO string is dependent on the requirements of the vendor providing the underlying resource manager. The string required by the vendor must be prefixed with rm_name:, which is the published name of the vendor's transaction (XA) interface followed immediately by a colon (:).

The OPENINFO parameter is ignored if TMSNAME is not set or is set to TMS. If TMSNAME is set but the OPENINFO string is set to the null string ("") or if this parameter does not appear on the entry, it means that a resource manager exists for the group but does not require any information for executing an open operation.

CLOSEINFO

Specifies information the resource manager needs when closing a database. The parameter can be omitted or the null string can be specified. The default is the null string.

Modifying the SERVICES Section

The SERVICES section contains parameters that control the way application services are handled. An entry line in this section is associated with a service by its identifier name. Because the same service can be link edited with more than one server, the SRVGRP parameter is provided to tie the parameters for an instance of a service to a particular group of servers. Three parameters in the SERVICES section are particularly related to DTP: ROUTING, AUTOTRAN, and TRANTIME. Table 5-2 describes the parameters in the SERVICES section.

Table 5-2 Description of the SERVICES Section Parameters

Parameter Meaning

ROUTING

The ROUTING parameter in the SERVICES section points to an entry in the ROUTING section where data-dependent routing is specified for transactions that request this service.

AUTOTRAN

Setting the AUTOTRAN parameter to Y or N determines whether a transaction should be started automatically if a message received by this service is not already in transaction mode.The default is N. Use of the parameter should be coordinated with the programmers coding the services for your application.

TRANTIME

The TRANTIME parameter sets a timeout value in seconds for transactions automatically started in this service. The default is 30 seconds. The TRANTIME parameter is needed only if AUTOTRAN =Y, and not even then if the default is acceptable.

Sample SERVICES Section

The following listing shows a sample SERVICES section:

*SERVICES

WITHDRAW ROUTING=ACCOUNT_ID
DEPOSIT ROUTING=ACCOUNT_ID
OPEN_ACCT ROUTING=BRANCH_ID

Creating the ROUTING Section

For information about ROUTING parameters that support the BEA TUXEDO system data-dependent routing or the WLE factory-based routing, see Chapter 3, "Creating a Configuration File."

Example of UBBCONFIG Sections in a Distributed Application

The following UBBCONFIG file contains the GROUPS, SERVICES, and ROUTING sections of a configuration file to accomplish data-dependent routing in the BEA TUXEDO system.

*GROUPS
BANKB1 GRPNO=1
BANKB2 GRPNO=2
BANKB3 GRPNO=3
#
*SERVICES
WITHDRAW ROUTING=ACCOUNT_ID
DEPOSIT ROUTING=ACCOUNT_ID
INQUIRY ROUTING=ACCOUNT_ID
OPEN_ACCT ROUTING=BRANCH_ID
CLOSE_ACCT ROUTING=BRANCH_ID
#
*ROUTING
ACCOUNT_ID FIELD=ACCOUNT_ID BUFTYPE="FML"
RANGES="MIN - 9999:*,
10000-49999:BANKB1,
50000-79999:BANKB2,
80000-109999:BANKB3,
*:*"
BRANCH_ID FIELD=BRANCH_ID BUFTYPE="FML"
RANGES="MIN - 0:*,
1-4:BANKB1,
5-7:BANKB2,
8-10:BANKB3,
*:*"

Modifying the Domain Gateway Configuration File to Support Routing (BEA TUXEDO Servers)

This section is specific to the BEA TUXEDO system and explains how and why you need to modify the domain gateway configuration to support routing. For more information about the domain gateway configuration file, see Chapter 14, ``Working with Multiple Domains (BEA TUXEDO System).''

What is the Domains gateway configuration file?

All Domains gateway configuration information is stored in a binary file, the BDMCONFIG file. The DMCONFIG file (ASCII) is created and edited with any text editor. The compiled BDMCONFIG file can be updated while the system is running by using the dmadmin(1) command.

You must have one BDMCONFIG file for each BEA TUXEDO application wanting to add the Domains functionality. System access to the BDMCONFIG file is provided through the Domains administrative server, DMADM(5). When a gateway group is booted, the gateway administrative server, GWADM(5), requests from the DMADM server a copy of the configuration required by that group. The GWADM server and the DMADM server also ensure that run-time changes to the configuration are reflected in the corresponding Domains gateway groups.

Note: For more information about the DMCONFIG file, refer to the dmconfig(5) reference page in the BEA TUXEDO Reference Manual.

Description of Parameters in the ROUTING Section of the DMCONFIG File

The DM_ROUTING section provides information for data-dependent routing of service requests using FML, VIEW, X_C_TYPE, and X_COMMON typed buffers. Lines within the DM_ROUTING section have the form CRITERION_NAME, where CRITERION_NAME is the (identifier) name of the routing entry specified in the SERVICES section. The CRITERION_NAME entry may contain no more than 15 characters. The following table describes the parameters in the DM_ROUTING section:

Parameter Meaning

FIELD = identifier

Specifies the name of the routing field. It must contain 30 characters or fewer. This field is assumed to be a field name identified in an FML field table (for FML buffers) or an FML VIEW table (for VIEW, X_C_TYPE, or X_COMMON buffers). The FLDTBLDIR and FIELDTBLS environment variables are used to locate FML field tables; the VIEWDIR and VIEWFILES environment variables are used to locate FML VIEW tables. If a field in an FML32 buffer is used for routing, it must have a field number less than or equal to 8191.

RANGES ="range1:rdom1[,range2:rdom2 ...]"

Specifies the ranges and associated remote domain names (RDOM) for the routing field. The string must be enclosed in double quotes, with the format of a comma-separated ordered list of range/RDOM pairs. A range is either a single value (signed numeric value or character string in single quotes), or a range of the form lower - upper (where lower and upper are both signed numeric values or character strings in single quotes). The value of lower must be less than or equal to upper. A single quote embedded in a character string value (as in "O'Brien," for example), must be preceded by two backslashes ("O\\'Brien").
Use MIN to indicate the minimum value for the data type of the associated FIELD. For strings and carrays, it is the null string; for character fields, it is 0; for numeric values, it is the minimum numeric value that can be stored in the field.
Use MAX to indicate the maximum value for the data type of the associated FIELD. For strings and carrays, it is effectively an unlimited string of octal-255 characters; for a character field, it is a single octal-255 character; for numeric values, it is the maximum numeric value that can be stored in the field. Thus, MIN - -5 is all numbers less than or equal to -5, and 6 - MAX is all numbers greater than or equal to 6.
The metacharacter * (wildcard) in the position of a range indicates any values not covered by the other ranges previously seen in the entry. Only one wildcard range is allowed per entry and it should be last (ranges following it are ignored).

BUFTYPE = "type1[:subtype1[,subtype2 . . . ]][;type2[:subtype3[, . . . ]]] . . ."

A list of types and subtypes of data buffers for which this routing entry is valid. The types are restricted to FML, VIEW, X_C_TYPE, and X_COMMON. No subtype can be specified for type FML, and subtypes are required for the other types (* is not allowed). Duplicate type/subtype pairs cannot be specified for the same routing criteria name; more than one routing entry can have the same criteria name as long as the type/subtype pairs are unique. This parameter is required. If multiple buffer types are specified for a single routing entry, the data types of the routing field for each buffer type must be the same. (If the field value is not set (for FML buffers), or does not match any specific range, and a wildcard range has not been specified, an error is returned to the application process that requested the execution of the remote service.)

Routing Field Description

The routing field can be of any data type supported in FML or VIEW. A numeric routing field must have numeric range values, and a string routing field must have string range values.

String range values for string, carray, and character field types must be placed inside a pair of single quotes and cannot be preceded by a sign. Short and long integer values are a string of digits, optionally preceded by a plus or minus sign. Floating point numbers are of the form accepted by the C compiler or atof(): an optional sign, then a string of digits optionally containing a decimal point, then an optional e or E followed by an optional sign or space, followed by an integer.
When a field value matches a range, the associated RDOM value specifies the remote domain to which the request should be routed. An RDOM value of * indicates that the request can go to any remote domain known by the gateway group. Within a range/RDOM pair, the range is separated from the RDOM by a : (colon).

Example of a Five-Site Domain Configuration Using Routing

The following configuration file defines a five-site domain configuration. Listing 5-1 shows four bank branch domains communicating with a Central Bank Branch. Three of the bank branches run within other BEA TUXEDO system domains. The fourth branch runs under the control of another TP domain, and OSI-TP is used in the communication with that domain. The example shows the BEA TUXEDO system Domains gateway configuration file from the Central Bank point of view. In the DM_TDOMAIN section, this example shows a mirrored gateway for b01.

Listing 5-1 A Five-Site Domains Configuration
# BEA TUXEDO DOMAIN CONFIGURATION FILE FOR THE CENTRAL BANK
#
#
*DM_LOCAL_DOMAINS
# <local domain name> <Gateway Group name> <domain type> <domain id> <log device>
# [<audit log>] [<blocktime>]
# [<log name>] [<log offset>] [<log size>]
# [<maxrdom>] [<maxrdtran>] [<maxtran>]
# [<maxdatalen>] [<security>]
# [<tuxconfig>] [<tuxoffset>]

#
#
DEFAULT: SECURITY = NONE
c01 GWGRP = bankg1
TYPE = TDOMAIN
DOMAINID = "BA.CENTRAL01"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"
DMTLOGNAME = "DMTLG_C01"
c02 GWGRP = bankg2
TYPE = OSITP
DOMAINID = "BA.CENTRAL01"
DMTLOGDEV = "/usr/apps/bank/DMTLOG"
DMTLOGNAME = "DMTLG_C02"
NWDEVICE = "OSITP"
URCH = "ABCD"
#
*DM_REMOTE_DOMAINS
#<remote domain name> <domain type> <domain id>
#
b01 TYPE = TDOMAIN
DOMAINID = "BA.BANK01"
b02 TYPE = TDOMAIN
DOMAINID = "BA.BANK02"
b03 TYPE = TDOMAIN
DOMAINID = "BA.BANK03"
b04 TYPE = OSITP
DOMAINID = "BA.BANK04"
URCH = "ABCD"
#
*DM_TDOMAIN
#
# <local or remote domainname> <network address> [nwdevice]
#
# Local network addresses
c01 NWADDR = "//newyork.acme.com:65432" NWDEVICE ="/dev/tcp"
c02 NWADDR = "//192.76.7.47:65433" NWDEVICE ="/dev/tcp"
# Remote network addresses: second b01 specifies a mirrored gateway
b01 NWADDR = "//192.11.109.5:1025" NWDEVICE = "/dev/tcp"
b01 NWADDR = "//194.12.110.5:1025" NWDEVICE = "/dev/tcp"
b02 NWADDR = "//dallas.acme.com:65432" NWDEVICE = "/dev/tcp"
b03 NWADDR = "//192.11.109.156:4244" NWDEVICE = "/dev/tcp"
#
*DM_OSITP
#
#<local or remote domain name> <apt> <aeq>
# [<aet>] [<acn>] [<apid>] [<aeid>]
# [<profile>]
#
c02 APT = "BA.CENTRAL01"
AEQ = "TUXEDO.R.4.2.1"
AET = "{1.3.15.0.3},{1}"
ACN = "XATMI"
b04 APT = "BA.BANK04"
AEQ = "TUXEDO.R.4.2.1"
AET = "{1.3.15.0.4},{1}"
ACN = "XATMI"
*DM_LOCAL_SERVICES
#<service_name> [<Local Domain name>] [<access control>] [<exported svcname>]
# [<inbuftype>] [<outbuftype>]
#
open_act ACL = branch
close_act ACL = branch
credit
debit
balance
loan LDOM = c02 ACL = loans
*DM_REMOTE_SERVICES
#<service_name> [<Remote domain name>] [<local domain name>]
# [<remote svcname>] [<routing>] [<conv>]
# [<trantime>] [<inbuftype>] [<outbuftype>]
#
tlr_add LDOM = c01 ROUTING = ACCOUNT
tlr_bal LDOM = c01 ROUTING = ACCOUNT
tlr_add RDOM = b04 LDOM = c02 RNAME ="TPSU002"
tlr_bal RDOM = b04 LDOM = c02 RNAME ="TPSU003"
*DM_ROUTING
# <routing criteria> <field> <typed buffer> <ranges>
#
ACCOUNT FIELD = branchid BUFTYPE ="VIEW:account"
RANGES ="MIN - 1000:b01, 1001-3000:b02, *:b03"
*DM_ACCESS_CONTROL
#<acl name> <Remote domain list>
#
branch ACLIST = b01, b02, b03
loans ACLIST = b04


Copyright © 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: July 05, 1999.