Guide to CORBA University Sample Applications
This topic includes the following sections:
Notes: The client applications in the Production sample application work in the same manner as the client applications in the Wrapper sample application.
The BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported in Tuxedo 9.0.
All BEA Tuxedo CORBA Java client and BEA Tuxedo CORBA Java client ORB text references, associated code samples, etc. should only be used:
Technical support for third party CORBA Java ORBs should be provided by their respective vendors. BEA Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.
The Production sample application provides the same end-user functionality as the Wrapper sample application. The Production sample application demonstrates how to use CORBA features of the BEA Tuxedo software to scale a CORBA application. The Production sample application does the following:
ORA_GRP
and APP_GRP
server groups defined in the UBBCONFIG
file.ORA_GRP1
and APP_GRP1
server groups on an additional server machine, Production Machine 2, as ORA_GRP2
and APP_GRP2
and partitions the database.Note: To make the Production sample application easy for you to use, the sample application is configured on the BEA Tuxedo software kit to run on one machine using one database. However, the Production sample application is set up so that it can be configured to run on several machines and to use multiple databases. Changing the configuration to multiple machines and databases involves simply modifying the UBBCONFIG
file and partitioning the database.
The following sections describe how the Production sample application uses replicated server applications, replicated server groups, object state management, and factory-based routing to scale the Production sample application.
When you replicate server applications:
In the Production sample application, the server applications are replicated in the following manner:
ORA_GRP
group.APP_GRP
group.Figure 7-1 shows the replicated ORA_GRP
and APP_GRP
server groups.
Figure 7-1 Replicated Server Groups in the Production Sample Application
In Figure 7-1, note the following:
RegistrarFactory
, Registrar
, TellerFactory
, or Teller
objects within a single server application process.CourseSynopsisEnumerator
objects within a server application process.Server groups are a feature of the BEA Tuxedo software that allow you to add server machines to an existing CORBA application. When you replicate a server group, you can do the following:
The way in which server groups are configured and replicated is specified in the UBBCONFIG
file.
Figure 7-2 shows the server groups in the Production sample application replicated on a second server machine. The replicated server groups are defined as ORA_GRP2
and APP_GRP2
in the UBBCONFIG
file for the Production sample application.
Figure 7-2 Replicating Server Groups Across Server Machines
In Figure 7-2, the only difference between the content of the server groups on Production Machine 1 and Production Machine 2 is the database. The University database is partitioned into two databases. The database on Production Machine 1 contains student and account information for students with IDs between 100001 and 100005. The database on Production Machine 2 contains student and account information for students with IDs between 100006 and 100010.
To achieve scalability gains, the Registrar
and Teller
objects are configured in the Production sample application to have the method activation policy. The method activation policy results in the following behavior changes:
In the Basic through the Production sample applications, the Registrar
object had an activation policy of process
. All requests from client applications on the Registrar
object went to the same object instance in the memory of the server machine. This design is adequate for a small-scale deployment. However, as client application demands increase, requests from client applications on the Registrar
object eventually become queued, and response time drops.
However, when the Registrar
and Teller
objects have an activation policy of method
and the server applications that manage these objects are replicated, the Registrar
and Teller
objects can process multiple requests from client applications in parallel. The only constraint is the number of server application processes that are available to instantiate the Registrar
and Teller
objects.
For the CORBA application to instantiate copies of the Registrar
and Teller
objects in each of the replicated server application processes, each copy of the Registrar
and Teller
objects have an unique object ID (OID). The factories that create these objects are responsible for assigning them unique OIDs. For information about generating unique object IDs, see Creating CORBA Server Applications.
Factory-based routing is a CORBA feature that allows you to send a request from a client application to a specific server group. Using factory-based routing, you can spread the processing load for a CORBA application across multiple server machines. The Production sample application uses factory-based routing in the following way:
Registrar
object are routed based on the student ID. Requests from student ID 100001 to 100005 go to Production Machine 1. Requests from student ID 100006 to 100010 go to Production Machine 2. Registrar
object to the Teller
object are routed based on account number. Billing requests for account 200010 to 200014 go to Production Machine 1. Billing requests for account 200015 to 200019 go to Production Machine 2.For information about setting up factory-based routing, see Creating CORBA Server Applications.
This section describes the development process required when scaling a CORBA application. These steps are in addition to the development process outlined in The Basic Sample Application.
Note: The steps in this section have been done for you and are included in the Production sample application.
During the development process, to support factory-based routing, you would make modifications to the Object Management Group (OMG) Interface Definition Language (IDL) definitions for the following operations:
find_registrar()
operation of the RegistrarFactory
object to require a find_teller()
operation of the TellerFactory
object to require an account number.For information about implementing factory-based routing, see Creating CORBA Server Applications.
During the development process, you would specify a STU_ID
value when creating a Registrar
object. The STU_ID
value defines to which server group the request from the client application is routed.
In the Production sample application, the University server application creates the Teller
object in the same way a client application would. Therefore, an ACT_NUM
value needs to be specified when creating a Teller
object.
During the development process, you need to modify the invocation to the TP::create_object_reference()
operation for the RegistrarFactory
and TellerFactory
objects to include an NVlist
that specifies routing criteria. The criteria
parameter of the TP::create_object_reference()
operation specifies a list of named values to be used for factory-based routing, as follows:
RegistrarFactory
object in the Production sample application specifies the value for criteria
to be STU_ID
.TellerFactory
object in the Production sample application specifies the value for criteria
to be ACT_NUM.The value of the criteria
parameter must match exactly the routing criteria name, field, and field type specified in the ROUTING
section of the UBBCONFIG
file.
For information about implementing factory-based routing in a factory, see Creating CORBA Server Applications.
The UBBCONFIG
file is the key to achieving scalability in a CORBA application. This section describes how the UBBCONFIG
file for the Production sample application is modified to:
During the development process, modify the UBBCONFIG
file in the following way to configure replicated server application processes and server groups:
GROUPS
section of the UBBCONFIG
file, specify the names of the groups you want to configure. In the Production sample application, there are four server groups: APP_GRP1
, APP_GRP2
, ORA_GRP1
, and ORA_GRP2
.SERVERS
section of the UBBCONFIG
file, enter the following information for the server application process you want to replicate:GROUP
parameter, which specifies the name of the server group to which the server application process belongs. If you are replicating a server process across multiple groups, specify the server process once for each group.SRVID
parameter, which specifies a unique administrative ID for the server machine.MIN
parameter, which specifies the number of instances of the server application process to start when the CORBA application is started. You need to start at least two server application processes.MAX
parameter, which specifies the maximum number of server application processes that can be running at any one time.You can specify no more than five server application processes.The MIN
and MAX
parameters determine the degree to which a given server application can process requests in parallel on a given object. During run time, the system administrator can examine resource bottlenecks and start additional server processes, if necessary. In this sense, the application is scaled by the system administrator.
The following example shows lines from the GROUPS
and SERVERS
sections of the UBBCONFIG
file for the Production sample application.
*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"
*SERVERS
# By default, activate 2 instances of each server
# and allow the administrator to activate up to 5
# instances of each server
DEFAULT:
MIN = 2
MAX = 5
tellp_server
SRVGRP = ORA_GRP1
SRVID = 10
RESTART = N
tellp_server
SRVGRP = ORA_GRP2
SRVID = 10
RESTART = N
billp_server
SRVGRP = APP_GRP1
SRVID = 10
RESTART = N
billp_server
SRVGRP = APP_GRP2
SRVID = 10
RESTART = N
univp_server
SRVGRP = ORA_GRP1
SRVID = 20
RESTART = N
univp_server
SRVGRP = ORA_GRP2
SRVID = 20
RESTART = N
For each interface for which you want to enable factory-based routing, you need to define the following information in the UBBCONFIG
file:
During the development process, make the following changes to the UBBCONFIG
file:
INTERFACES
section lists the names of the interfaces for which you want to enable factory-based routing. For each interface, this section specifies the value on which the interface routes. The routing value is specified in the FACTORYROUTING
identifier. The following example shows the FACTORYROUTING
identifier for the Registrar
and Teller
objects in the Production sample application:
INTERFACES
"IDL:beasys.com/UniversityP/Registrar:1.0"
FACTORYROUTING = STU_ID
"IDL:beasys.com/BillingP/Teller:1.0"
FACTORYROUTING = ACT_NUM
TYPE
parameter, which specifies the type of routing. In the Production sample application, the type of routing is factory-based routing. Therefore, this parameter is defined to FACTORY.
FIELD
parameter, which specifies the name that the factory inserts in the routing value. In the Production sample application, the field parameters are student_id
and account_number
.FIELDTYPE
parameter, which specifies the data type of the routing value. In the Production sample application, the field types for STU_ID
and ACT_NUM
are long
.RANGES
parameter, which specifies the values that are routed to each group.*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 example shows that Registrar
objects for students with IDs 100001 through 100005 are instantiated in ORA_GRP1,
and students with IDs 100006 through 100010 are instantiated in ORA_GRP2.
Likewise, Teller
objects
for accounts 200010 through 200014 are instantiated in APP_GRP1,
and accounts 200015 through 200019 are instantiated in APP_GRP2
.
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. Note: The names of the server groups in the GROUPS
section must exactly match the group names specified in the ROUTING
section.
During the development process, you need to change the activation policy of the Registrar
, RegistrarFactory
, Teller
, and TellerFactory
objects from process to method. For information about defining activation and transaction policies for CORBA objects, see Creating CORBA Server Applications.
To build the Production sample application, complete the following steps:
The following sections describe these steps.
Note: Before you can build or run the Production sample application, you need to complete the steps in Setting Up Your Environment.
The files for the Production sample application are located in the following directories:
drive
:\
TUXDIR
\samples\corba\university
\production
/usr/
TUXDIR
/samples/corba/university
/production
In addition, you need to copy the utils
directory into your work directory. The utils
directory contains files that set up logging, tracing, and access to the University database.
You will use the files in Table 7-1 to create the Production sample application.
During the installation of the BEA Tuxedo software, the sample application files are marked read-only. Before you can edit the files or build the files in the Production sample application, you need to change the protection of the files you copied into your work directory, as follows:
prompt>attrib -r drive:\
workdirectory
\*.*
prompt>chmod u+rw /
workdirectory
/*.*
Use the following command to set the environment variables used to build the client and server applications in the Production sample application:
Use the following command to initialize the University database used with the Production sample application:
prompt>nmake -f makefilep.nt initdb
prompt>make -f makefilep.mk initdb
Use the following command to load the UBBCONFIG
file:
The build process for the UBBCONFIG
file prompts you for an application password. This password will be used to log on to the client applications. Enter the password and press Enter. You are then prompted to verify the password by entering it again.
The transaction log records the transaction activities in a CORBA application. During the development process you need to define the location of the transaction log (specified by the TLOGDEVICE
parameter) in the UBBCONFIG
file. For the Production sample application, the transaction log is placed in your work directory.
You need to complete the following steps to open the transaction log for the Production sample application:
crdl -b
blocks
-z
directorypath
crlog -m SITE1
blocks
specifies the number of blocks to be allocated for the transaction log, and directorypath
indicates the location of the transaction log. The directorypath
option needs to match the location specified in the TLOGDEVICE
parameter in the UBBCONFIG
file. The following is an example of the command on Windows:
During the development process, you would use the buildobjclient
and buildobjserver
commands to build the client and server applications. However, for the Production sample application, this step has been done for you. The directory for the Production sample application contains a makefile
that builds the client and server sample applications.
Use the following commands to build the CORBA C++ client and server application in the Production sample application:
prompt>nmake -f makefilep.nt
To run the Production sample application, complete the following steps:
The following sections describe these steps in detail.
Start the system and sample application server applications in the Production sample application by entering the following command:
This command starts the following server processes:
Before using another sample application, enter the following command to stop the system and sample application server processes:
Start the CORBA C++ client application in the Production sample application by completing the following steps:
Note: The CORBA C++ client application in the Production sample application works in the A type library. By default, the type library is placed in \
TUXDIR
\TypeLibraries.
The Production sample application can be scaled even more by:
You need to modify the UBBCONFIG
file to specify the additional server groups, the server application processes that run in the new server groups, and the server machines on which the server groups run.
For example, instead of routing to the two existing server groups in the Production sample application, you can modify the routing rules in the UBBCONFIG
file to partition the application further among additional server groups. Any modification to the routing tables must match the information in the UBBCONFIG
file.
Note: If you add capacity to an existing CORBA application that uses a database, you must consider how the database is set up, particularly when you are using factory-based routing. For example, if the Production sample application is spread across six machines, the database on each machine must be set up appropriately and in accordance with the routing tables in the UBBCONFIG
file.