The Production Sample Application


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

BEA Tuxedo Doc Home \| Guide to the CORBA University Sample Applications \| Previous Topic \| Next Topic \| Contents \| Index

This topic includes the following sections:

Note: The client applications in the Production sample application work in the same manner as the client applications in the Wrapper sample application.

Refer to Readme.txt in the \production directory for troubleshooting information and the latest information about using the Production sample application.

How the Production Sample Application Works

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:

Replicates the University server application, the Billing server application, and the ATMI Teller application within the ORA_GRP and APP_GRP server groups defined in the UBBCONFIG file.
Replicates the 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.
Implements a stateless object model to scale up the number of requests from client applications the server application can manage simultaneously.
Assigns unique object IDs (OIDs) to the following objects so that they can be instantiated multiple times simultaneously in their respective server groups, thereby making them available on a per-client-application (and not per-process) basis:
Implements factory-based routing to direct requests from client applications on behalf of some students to one server machine, and other students to another server machine.

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.

Replicating Server Applications

When you replicate server applications:

You obtain a means to balance the load of incoming requests from client applications on that server application. As requests arrive in the Tuxedo domain for the server group, the BEA Tuxedo system routes the request to the least busy server application within that group.
You can specify how many copies of a given server application process are running on a server machine. The number of copies determines the extent to which the Tuxedo domain can process requests in-parallel from client applications.
You obtain a useful failover protection in the event that one of the server application processes stops.

In the Production sample application, the server applications are replicated in the following manner:

The University server application, the ATMI Teller application, and the server application for the University database are replicated within the ORA_GRP group.
The Billing server application is replicated within the 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:

There can be no more than one instance of the RegistrarFactory, Registrar, TellerFactory, or Teller objects within a single server application process.
There can be any number of CourseSynopsisEnumerator objects within a server application process.

Replicating Server Groups

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:

Spread the processing load for a CORBA application across multiple server machines.
Use factory-based routing to send requests from client applications to a particular server machine.

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.

Using a Stateless Object Model

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:

Whenever the objects are invoked, they are instantiated by the Tuxedo domain in the appropriate server group.
After the invocation is complete, the Tuxedo domain deactivates the objects.

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.

Using Factory-based Routing

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:

Requests from client applications to the 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.
Requests from the 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.

The Development Process for the Production Sample Application

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

Note: The steps in this section have been done for you and are included in the Production sample application.

OMG IDL

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:

The find_registrar() operation of the RegistrarFactory object to require a student ID.
The find_teller() operation of the TellerFactory object to require an account number.

For information about implementing factory-based routing, see Creating CORBA Server Applications.

The Client Application

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.

The Server Application

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:

The RegistrarFactory object in the Production sample application specifies the value for criteria to be STU_ID.
The 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

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:

Replicate server application processes and server groups
Implement factory-based routing

Replicating Server Application Processes and Server Groups

During the development process, modify the UBBCONFIG file in the following way to configure replicated server application processes and server groups:

In the 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.
In the SERVERS section of the UBBCONFIG file, enter the following information for the server application process you want to replicate:

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

Implementing Factory-based Routing

For each interface for which you want to enable factory-based routing, you need to define the following information in the UBBCONFIG file:

Details about the data in the routing criteria
For each kind of criteria, the values that route to specific server groups

During the development process, make the following changes to the UBBCONFIG file:

The 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
```
The ROUTING section specifies the following data for each routing value:
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.

Note: The names of the server groups in the GROUPS section must exactly match the group names specified in the ROUTING section.

The ICF File

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.

Building the Production Sample Application

To build the Production sample application, complete the following steps:

Copy the files for the Production sample application into a work directory.
Change the protection on the files for the Production sample application files.
Set the environment variables.
Initialize the University database.
Load the UBBCONFIG file.
Create a transaction log.
Build the client and server sample applications.

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.

Copying the Files for the Production Sample Application into a Work Directory

The files for the Production sample application are located in the following directories:

Windows 2000

drive:\TUXDIR\samples\corba\university\production

UNIX

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

Table 7-1 Files Included in the Production Sample Application

File	Description
billp.idl	The OMG IDL that declares the Teller and TellerFactory interfaces.
univp.idl	The OMG IDL that declares the CourseSynopsisEnumerator, Registrar, and RegistrarFactory interfaces.
billps.cpp	The C++ source code for the Billing server application in the Production sample application.
univps.cpp	The C++ source code for the University server application in the Production sample application.
billp__i.h billp_i.cpp	The C++ source code for the method implementations of the Teller and TellerFactory interfaces.
univp_i.h univp_i.cpp	The C++ source code for method implementations of the CourseSynopsisEnumerator, Registrar, and RegistrarFactory interfaces.
univpc.cpp	The C++ source code for the CORBA C++ client application in the Production sample application.
frmBrowser.frm	The Visual Basic source code for the ActiveX client application in the Production sample application.
university.vbp	The Visual Basic project file for the ActiveX client application in the Production sample application.
University.vbw	The Visual Basic workspace file for the ActiveX client application in the Production sample application.
modPublicDeclarations.bas	A Visual Basic file that contains the declarations for variables used in the sample applications.
frmTracing.frm frmTracing.frx	The files that provide tracing capabilities to the ActiveX client application.
frmLogon.frm	The Visual Basic file that performs the security logon for the ActiveX client application.
univPApplet.java	The Java source code for the CORBA Java client application in the Production sample application.
univp_utils.h univp_utils.cpp	The files that define database access functions for the CORBA C++ client application.
univp.icf	The Implementation Configuration File (ICF) for the University server application in the Production sample application.
billp.icf	The ICF file for the Billing server application in the Production sample application.
tellw_flds, tellw_u.c, tellw_c.h, tellws.ec	The files for the ATMI application Teller.
setenvp.sh	A UNIX script that sets the environment variables needed to build and run the Production sample application.
setenvp.cmd	An MS-DOS command procedure that sets the environment variables needed to build and run the Production sample application.
ubb_p.mk	The UBBCONFIG file for the UNIX operating system.
ubb_p.nt	The UBBCONFIG file for the Windows 2000 operating system.
makefilep.mk	The makefile for the Production sample application on the UNIX operating system.
makefilep.nt	The makefile for the Production sample application on the Windows 2000 operating system.
log.cpp, log.h, log_client.cpp, and log_server.cpp	The files for the client and server applications that provide logging and tracing functions for the sample applications. These files are located in the \utils directory.
oradbconn.cpp and oranoconn.cpp	The files that provide access to an Oracle SQL database instance.These files are located in the \utils directory.
samplesdb.cpp and samplesdb.h	The files that provide print functions for the database exceptions in the sample applications. These files are located in the \utils directory.
unique_id.cpp and unique_id.h	C++ Unique ID class routines for the sample applications.These files are located in the \utils directory.
samplesdbsql.h and samplesdbsql.pc	C++ class methods that implement access to the SQL database. These files are located in the \utils directory.
university.sql	The SQL for the University database. This file is located in the \utils directory.

Changing the Protection on the Files for 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:

Windows 2000

prompt>attrib -r drive:\workdirectory\*.*

UNIX

prompt>chmod u+rw /workdirectory/*.*

Setting the Environment Variables

Use the following command to set the environment variables used to build the client and server applications in the Production sample application:

Windows 2000

prompt>setenvp

UNIX

prompt>/bin/ksh

prompt>. ./setenvp.sh

Initializing the University Database

Use the following command to initialize the University database used with the Production sample application:

Windows 2000

prompt>nmake -f makefilep.nt initdb

UNIX

prompt>make -f makefilep.mk initdb

Loading the UBBCONFIG File

Use the following command to load the UBBCONFIG file:

Windows 2000

prompt>tmloadcf -y ubb_p.nt

UNIX

prompt>tmloadcf -y ubb_p.mk

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.

Creating a Transaction Log

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:

Enter the following command to start the Interactive Administrative Interface:
tmadmin
Enter the following command to create a transaction log:
crdl -b blocks -z directorypath
crlog -m SITE1

where

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

crdl -b 500 -z c:\mysamples\university\production\TLOG
Enter q to quit the Interactive Administrative Interface.

Compiling the Production Sample Application

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:

Windows 2000

prompt>nmake -f makefilep.nt

UNIX

prompt>make -f makefilep.mk

To build the CORBA Java client application:

Windows 2000

prompt>nmake -f makefilep.nt javaclient

UNIX

prompt>make -f makefilep.mk javaclient

For information about starting the ActiveX client application, see Starting the ActiveX Client Application.

For more information about the buildobjclient and buildobjserver commands, see the BEA Tuxedo Command Reference.

Running the Production Sample Application

To run the Production sample application, complete the following steps:

Start the server application.
Start one or more of the client applications.

The following sections describe these steps in detail.

Starting the Server Application

Start the system and sample application server applications in the Production sample application by entering the following command:

prompt>tmboot -y

This command starts the following server processes:

TMSYSEVT
The BEA Tuxedo system EventBroker.
TMFFNAME
The transaction management services, including the NameManager and the FactoryFinder services.
TMIFSRVR
The Interface Repository server process. This server process is used only by ActiveX client applications.
univp_server
Four processes of the University server application.
tellp_server
Four processes of the ATMI application Teller.
billp_server
Four processes of the Billing server application.
ISL
The IIOP Listener/Handler process.

Before using another sample application, enter the following command to stop the system and sample application server processes:

prompt>tmshutdown

Starting the CORBA C++ Client Application

Start the CORBA C++ client application in the Production sample application by completing the following steps:

At the MS-DOS prompt, enter the following command:
prompt>univp_client
At the Enter student id: prompt, enter any number between 100001 and 100010.
Press Enter.
At the Enter domain password: prompt, enter the password you defined when you loaded the UBBCONFIG file.
Press Enter.

Note: The CORBA C++ client application in the Production sample application works in the same manner as the CORBA C++ client application in the Wrapper sample application.

Starting the CORBA Java Client Application

To run the CORBA Java client application in the Production sample application, complete the following steps:

Modify the following lines in the UnivPApplet.html file:
code="UnivPApplet.class"
codebase=.
to read as follows:

code="UnivPApplet"
archive="UnivPApplet.jar,m3envobj.jar"
Copy the modified UnivPApplet.html file to the source directory for the Web server (the directory varies by Web server product).
After executing the makefile to build the Production sample application, create a UnivPApplet.jar file, as follows:
1. Create a tmp directory under the directory where you built the sample application and copy the UniversityP subdirectory and the class files it contains into the tmp directory.
  Copy the class files in the Production sample application directory that were generated by the makefile into the tmp directory, set the directory (cd) to the tmp directory, and issue one of the following commands to create a .JAR file that contains all the Production sample application classes:
  
  jar -cf ..\UnivPApplet.jar *.* (Microsoft Windows 2000 systems)
  jar -cf ../UnivPApplet.jar * (UNIX systems)
Copy the UnivPApplet.jar file you just created to the source directory for the Web server (the directory name varies by Web server product).
Copy the m3envobj.jar file from the appropriate subdirectory (%TUXDIR%\udataobj\java Microsoft Windows 2000 systems or ${TUXDIR}/udataobj/java UNIX systems) to the Web server source directory.
Make sure the Security server application is running, start up your Web browser, and point it to the node where the Web server is running.

Note: On Microsoft Windows 2000 systems, the node name needs to be in all uppercase characters. For example, if the node is specified as SERVER in the UBBCONFIG file and in the UnivPApplet.html file, set your browser to http://SERVER/UnivPApplet.html.

Enter a number between 100001 and 100010 in the student ID field.
In the Domain Password field, enter the password you defined when you loaded the UBBCONFIG file.
Double-click the Logon button.

Note: The CORBA Java client application in the Production sample application works in the same manner as the CORBA Java client application in the Wrapper sample application.

Starting the ActiveX Client Application

Note: For the University sample applications, the task of loading the OMG IDL for the CORBA interfaces into the Interface Repository is automated by the makefile.

Before you can start the ActiveX client application, you must use the Application Builder to create ActiveX bindings for the CORBA interfaces.

To create an ActiveX binding for a CORBA interface, complete the following steps:

Click the BEA Application Builder icon in the BEA Tuxedo program group.
The IIOP Listener window appears.
In the IIOP Listener window, enter the host name and port number that you specified in the ISL parameter in the UBBCONFIG file . You must match exactly the capitalization used in the UBBCONFIG file.
The Logon window appears.
In the Logon window, enter a student ID between 100001 and 100010 for the username and the password you defined when you loaded the UBBCONFIG file.
The Application Builder window appears. All the CORBA interfaces loaded in the Interface Repository appear in the Services window of the Application Builder.
Highlight the UniversityP folder in the Services window and drag it to the Workstation Views window, or copy the UniversityP folder from the Services window and paste it into the Workstation Views window.
A confirmation window appears.
Click Create to create the ActiveX bindings for the CORBA interfaces in the Production sample application.
The Application Builder creates the following:

To run the ActiveX client application, complete the following steps:

Open the University.vbw file in Visual Basic.
From the Run menu, click Start.
The IIOP Listener window appears.
In the IIOP Listener window, enter the host name and port number that you specified in the ISL parameter in the UBBCONFIG file. You must exactly match the capitalization used in the UBBCONFIG file.
The Logon window appears.
In the Logon window, enter a student ID between 100001 and 100010 for the username and the password you defined when you loaded the UBBCONFIG file.

Note: The ActiveX client application in the Production sample application works in the same manner as the ActiveX client application in the Wrapper sample application.

How the Production Sample Application Can Be Scaled Further

The Production sample application can be scaled even more by:

Replicating the server groups in the Production sample application across additional machines.
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.
Changing the factory-based routing tables
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.