The Wrapper Sample Application

 

The topic includes the following sections:

• How the Wrapper Sample Application Works

• The Development Process for the Wrapper Sample Application

• Building the Wrapper Sample Application

• Compiling the Wrapper Sample Application

• Running the Wrapper Sample Application

• Using the Client Applications in the Wrapper Sample Application

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

 

---

How the Wrapper Sample Application Works

In the Wrapper sample application, when a student registers for classes, the student's account is charged for the classes and the balance of the student's account is updated. In addition, students can get information about their account balances.

The Wrapper sample application incorporates an additional server application and a BEA Tuxedo application. The Billing server application contains a Teller object, which calls the BEA Tuxedo Teller application. The BEA Tuxedo Teller application performs the following billing operations:

• Debiting a student account

• Crediting a student account

• Obtaining the current balance of a student account

The University database is modified to include account information.

Figure 6-1 illustrates how the Wrapper sample application works.

Figure 6-1 The Wrapper Sample Application

 

---

The Development Process for the Wrapper Sample Application

This section describes the development process required when wrapping a BEA Tuxedo application in a WebLogic Enterprise (WLE) 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 Wrapper sample application.

OMG IDL

When wrapping a BEA Tuxedo application, you need to define an object that interoperates with the BEA Tuxedo application and a factory that creates that object. In the Wrapper sample application, the Teller and TellerFactory objects interact with the BEA Tuxedo Teller application. During the development process, you would define the interfaces of the Teller and the TellerFactory objects in Object Management Group (OMG) Interface Definition Language (IDL), as follows:

Object	Description	Operations
TellerFactory	Returns an object reference to the Teller object	find_teller()
Teller	Interoperates with the BEA Tuxedo Teller application to perform billing and accounting operations	get_balance() credit() debit()

You need to add a Balance field to the StudentDetails structure. Client applications use the Balance field to show the student's account balance. A user exception DelinquentAccount is also added.

The Client Application

During the development process, you would add code to the client application to handle the user exception Delinquent Account that the register_for_courses() operation can raise.

The Server Application

During the development process, you would write the following for the Billing server application:

• Method implementations for the get_balance(), credit(), and debit() operations for the Teller object. The method implementations need to include the code that does the following:

  • Allocates an FML message buffer

  • Fills the FML message buffer with the data you want to send to the BEA Tuxedo Teller application

  • Calls the BEA Tuxedo Teller application

  • Extracts information from the FML message buffer returned from the BEA Tuxedo Teller application

  • Returns the information from the FML message buffer to the University server application

• A method implementation for the find_teller() operation of the TellerFactory object.

• A Billing server object that creates and registers the TellerFactory object and calls the open_XA_RM and close_XA_RM functions.

During the development process, you would add the following to the University server application:

• In the server initialization portion of the code for the University server application, include the Bootstrap object to get a FactoryFinder object for the TellerFactory object. The University server application is using the Bootstrap and FactoryFinder objects like a client application would.

• In the code for the University server application, include a reference to the TellerFactory object in the constructor of the servant for the Registrar object. Use the TellerFactory object to create a Teller object.

• In the method implementations for the get_student_details() and register_for_courses() operations for the Registrar object, invoke the get_balance() and debit() operations on the Teller object.

For information about writing server applications that wrap BEA Tuxedo applications, see Creating C++ Server Applications.

The UBBCONFIG File

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

• Define the following server groups in the GROUPS section of the UBBCONFIG file:

  • ORA_GRP, which contains the University server application, the BEA Tuxedo Teller application, and the server application for the University database. This server group allows both the University server application and the BEA Tuxedo Teller application to access the University database.

  • APP_GRP, which contains the Billing server application.

• Specify the server applications in the Wrapper sample application in the order in which they should be booted in the SERVERS section of the UBBCONFIG file. Start the server applications in the following order:

  1. BEA Tuxedo Teller application

  2. Billing server application

  3. University server application

The ICF File

During the development process, you need to define activation and transaction policies for the Teller and TellerFactory objects. The Teller and TellerFactory objects have the following policies:

• The Teller object has an activation policy of process and a transaction policy of optional.

• The TellerFactory object has an activation policy of process and a transaction policy of ignore.

For information about defining activation and transaction policies for CORBA objects, see Creating C++ Server Applications.

 

---

Building the Wrapper Sample Application

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

1. Copy the files for the Wrapper sample application.

2. Change the protection on the files for the Wrapper sample application.

3. Set the environment variables.

4. Initialize the University database.

5. Load the UBBCONFIG file.

6. Create a transaction log.

7. Build the client and server sample applications.

The following sections describe these steps.

Note: Before you can build or run the Wrapper sample application, you need to complete the steps in Setting Up Your Environment.

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

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

Windows NT

drive:\WLEdir\samples\corba\university\wrapper

UNIX

/usr/WLEdir/samples/corba/university/wrapper

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 listed in Table 6-1 to create the Wrapper sample application.

Table 6-1 Files Included in the Wrapper Sample Application

File	Description
billw.idl	The OMG IDL that declares the Teller and TellerFactory interfaces.
univw.idl	The OMG IDL that declares the CourseSynopsisEnumerator, Registrar, and RegistrarFactory interfaces.
billws.cpp	The C++ source code for the Billing server application in the Wrapper sample application.
univws.cpp	The C++ source code for the University server application in the Wrapper sample application.
billw__i.h billw_i.cpp	The C++ source code for the method implementations of the Teller and TellerFactory interfaces.
univw_i.h univw_i.cpp	The C++ source code for the method implementations of the CourseSynopsisEnumerator, Registrar, and RegistrarFactory interfaces.
univwc.cpp	The C++ source code for the CORBA C++ client application in the Wrapper sample application.
frmBrowser.frm	The Visual Basic source code for the ActiveX client application in the Wrapper sample application.
university.vbp	The Visual Basic project file for the ActiveX client application in the Wrapper sample application.
University.vbw	The Visual Basic workspace file for the ActiveX client application in the Wrapper 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.
univWApplet.java	The Java source code for the CORBA Java client application in the Wrapper sample application.
univw_utils.h univw_utils.cpp	The files that define database access functions for the CORBA C++ client application.
univw.icf	The ICF file for the University server application in the Wrapper sample application.
billw.icf	The ICF file for the Billing server application in the Wrapper sample application.
setenvw.sh	A UNIX script that sets the environment variables needed to build and run the Wrapper sample application.
tellw_flds, tellw_u.c, tellw_c.h, tellws.ec	The files for the BEA Tuxedo Teller application.
setenvw.cmd	An MS-DOS command procedure that sets the environment variables needed to build and run the Wrapper sample application.
ubb_w.mk	The UBBCONFIG file for the UNIX operating system.
ubb_w.nt	The UBBCONFIG file for the Windows NT operating system.
makefilew.mk	The makefile for the Wrapper sample application on the UNIX operating system.
makefilew.nt	The makefile for the Wrapper sample application on the Windows NT 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 Wrapper Sample Application

During the installation of the WebLogic Enterprise software, the sample application files are marked read-only. Before you can edit the files or build the files in the Wrapper sample application, you need to change the protection of the files you copied into your work directory, as follows:

Windows NT

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 Wrapper sample application:

Windows NT

prompt>setenvw

UNIX

prompt>/bin/ksh

prompt>. ./setenvw.sh

Initializing the University Database

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

Windows NT

prompt>nmake -f makefilew.nt initdb

UNIX

prompt>make -f makefilew.mk initdb

Loading the UBBCONFIG File

Use the following command to load the UBBCONFIG file:

Windows NT

prompt>tmloadcf -y ubb_w.nt

UNIX

prompt>tmloadcf -y ubb_w.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 WebLogic Enterprise 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 Wrapper sample application, the transaction log is placed in your work directory.

To open the transaction log for the Wrapper sample application, complete the following steps:

1. Enter the following command to start the Interactive Administrative Interface:

   tmadmin

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

   crdl -b 500 -z c:\mysamples\university\wrapper\TLOG

3. Enter q to quit the Interactive Administrative Interface.

 

---

Compiling the Wrapper Sample Application

During the development process, you would use the buildobjclient and buildobjserver commands to build the client and server applications. However, for the Wrapper sample application, this step has been done for you. The directory for the Wrapper 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 Wrapper sample application:

Windows NT

prompt>nmake -f makefilew.nt

UNIX

prompt>make -f makefilew.mk

To build the CORBA Java client application:

Windows NT

prompt>nmake -f makefilew.nt javaclient

UNIX

prompt>make -f makefilew.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 Commands, System Processes, and MIB Reference.

 

---

Running the Wrapper Sample Application

To run the Wrapper sample application, complete the folllowing steps:

1. Start the server application.

2. Start one or more of the client applications.

These steps are described in the following sections.

Starting the Server Application

Start the system and sample application server processes in the Wrapper sample application by entering the following command:

prompt>tmboot -y

This command starts the following server processes:

• TMSYSEVT

  The BEA Tuxedo system event broker.

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

• univw_server

  The University server process.

• tellw_server

  The BEA Tuxedo Teller application process.

• billw_server

  The Billing server application process.

• 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 Wrapper sample application by completing the following steps:

1. At the MS-DOS prompt, enter the following command:

   prompt>univw_client

2. At the Enter student id: prompt, enter any number between 100001 and 100010.

3. Press Enter.

4. At the Enter domain password: prompt, enter the password you defined when you loaded the UBBCONFIG file.

5. Press Enter.

Starting the CORBA Java Client Application

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

1. Modify the following lines in the UnivWApplet.html file:

   code="UnivWApplet.class"
   codebase=.
   to read as follows:

   code="UnivWApplet"
   archive="UnivWApplet.jar,m3envobj.jar"

2. Copy the modified UnivWApplet.html file to the source directory for the Web server (the directory varies by Web server product).

3. After executing the makefile to build the Wrapper sample application, create a UnivWApplet.jar file, as follows:

   1. Create a tmp directory under the directory where you built the sample application and copy the UniversityW subdirectory and the class files it contains into the tmp directory.

      Copy the class files in the Wrapper 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 Wrapper sample application classes:
      
      jar -cf ..\UnivWApplet.jar *.* (Microsoft Windows NT systems)
      jar -cf ../UnivPWpplet.jar * (UNIX systems)

4. Copy the UnivWApplet.jar file you just created to the source directory for the Web server (the directory name varies by Web server product).

5. Copy the m3envobj.jar file from the appropriate subdirectory (%TUXDIR%\udataobj\java Microsoft Windows NT systems or ${TUXDIR}/udataobj/java UNIX systems) to the Web server source directory.

6. Make sure the Wrapper 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 NT 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 UnivWApplet.html file, set your browser to http://SERVER/UnivWApplet.html.

7. Enter a number between 100001 and 100010 in the student ID field.

8. In the Domain Password field, enter the password you defined when you loaded the UBBCONFIG file.

9. Double click the Logon button.

Exceptions appear in the status bar of the Appletviewer window or in the MS-DOS window in which the CORBA Java client application was started.

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:

1. Click the BEA Application Builder icon in the WebLogic Enterprise program group.

   The IIOP Listener window appears.

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

3. In the Logon window, enter a student ID between 100001 and 100010 for the user name 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.

4. Highlight the UniversityW folder in the Services window and drag it to the Workstation Views window, or copy the UniversityW folder from the Services window and paste it into the Workstation Views window.

   A confirmation window appears.

5. Click Create to create the ActiveX bindings for the CORBA interfaces in the Wrapper sample application.

   The Application Builder creates the following:

   • A binding for the CORBA interface. The binding is named DImodulename_interfacename. For example, the binding for the Registrar interface is named DIUniversityW_Registrar.

   • A type library. By default, the type library is placed in \WLEdir\TypeLibraries.

     The type library file is named DImodulename_interfacename.tlb.

   • A Windows system registry entry, including unique Program IDs for each object type, for the CORBA interface.

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

1. Open the University.vbw file in Visual Basic.

2. From the Run menu, click Start.

   The IIOP Listener window appears.

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

4. In the Logon window, enter a student ID between 100001 and 100010 for the user name and the password you defined when you loaded the UBBCONFIG file.

 

---

Using the Client Applications in the Wrapper Sample Application

The following sections explain how to use the client applications in the Wrapper sample application.

The CORBA C++ Client Application

The CORBA C++ client application in the Wrapper sample application has the following additional option:

<B>    Display Your Balance

The Display Your Balance option displays the account balance associated with the student ID used to log on to the CORBA C++ client application.

To exit the C++ CORBA client application, enter E at the Options prompt.

The CORBA Java Client Application

The CORBA Java client application in the Wrapper sample application allows you to display an account balance.

When you log on to the CORBA Java client application, a Student Account Summary window appears. The Student Account Summary window displays the account balance associated with the student ID used to log on to the CORBA Java client application. When you register for additional courses, the amount in the Balance text box in the Student Account Summary window increases.

To exit the CORBA Java client application, click the Logoff button in the Student Account Summary window, or choose Quit from the File menu.

The ActiveX Client Application

The ActiveX client application in the Wrapper sample application allows you to display an account balance.

When you log on to the ActiveX client application, a Course Browser window appears. The Course Browser window displays the registered courses and account balance for the student ID used to log on to the ActiveX client application. When you register for additional courses, the amount in the Balance text box in the Course Browser window increases.

To exit the ActiveX client application, choose Exit from the File menu.