Building the Introductory Sample Application

This topic includes the following sections:

•

Overview

•	Building and Running the Introductory Sample Application

Note:

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

Overview

The Introductory sample applications simulate a newsroom environment in which a news reporter posts a story and a news subscriber consumes the story.

One implementation of the Introductory sample application is provided: the C++ programming language that uses the Oracle Simple Events application programming interface (API). The Introductory sample application consists of the Reporter and Subscriber applications and the Notification Service. The Reporter application implements a client application that prompts the user to enter news articles, and then posts the news articles as events to the Oracle Tuxedo CORBA Notification Service. The Subscriber application implements a joint client/server application that acts as client when it subscribes and unsubscribes for events, and acts as a server when it receives events. To receive events, the subscriber implements a callback object which is invoked by the Notification Service when an event needs to be delivered.

The Introductory sample application shows the simplest usage of the Notification Service. It demonstrates how to use the Oracle Simple Events API, the CosNotification API, transient subscriptions, and transient object references. It does not demonstrate the use of persistent subscriptions or data filtering. For a sample application that uses persistent subscriptions and data filtering, see Chapter 6, “Building the Advanced Sample Application.”

This Introductory sample application provides two executables (see Figure 5‑1):

•	A Reporter application that posts events to the Notification Service. It is a client without callback capability.

•	A Subscriber application that subscribes to the Notification Service and receives events. The subscriber is a joint client/server that acts as a client when it subscribes to events and acts as a server when it receives events.

Figure 5‑1 Introductory Sample Application Components

The event poster, the Reporter application, uses the structured event domain_name, type_name, and filterable_data fields to construct the event. The domain name defines the industry. In this application, domain_name is set to “News”. The type_name defines the kind of event in the industry and it is set to the category of news story (for example, “Sports”). The application user specifies this value. In the filterable_data fields, a field named “Story” is added, which contains the text of the news story being posted. This text is also specified by the application user.

The Subscriber application uses the structured event domain_name and type_name fields to create a subscription to the Notification Service. The subscription defines the domain_name as a fixed string with the content of “News”. At run time, the Subscriber application queries the user for the “News Category” and uses the input to define the type_name field in the subscription. Obviously, the users of both applications, the reporter and the subscriber, must collaborate on the “News Category” string for the subscription to match an event, otherwise, no events will be delivered to the subscriber. The subscription does not do any checking of the filterable_data field, but rather assumes that the body of the story will be a string, and that the story will be in the first Named/Value pair in the filterable_data field of a structured event.

To post events, the Reporter application uses the push_structured_event method to push news events to the Notification Service. For each event, the Reporter application queries the user for a “News category” (for example, “Sports”) and a story (a multiple-line text string).

To subscribe to news events, the Subscriber application invokes the Notification Service to subscribe to news events. For each subscription, the Subscriber application queries the user for a “News category” (for example, “Sports”). The Subscriber application also implements a callback object (via the NewsConsumer_i servant class) which is used to receive and process news events. When the Subscriber subscribes, it gives the Notification Service a reference to this callback object. When a matching event occurs; that is, when the Reporter posts an event with a “News category” that matches the news category of the subscription, the Notification Service invokes the push_structured_event method on the callback object to deliver the event to the callback object in the subscriber. This method prints out the event, invokes the unsubscribe method on the Notification Service to cancel the subscription, and shuts down the Subscriber. For simplicity, the push_structured_event method assumes that the domain_name, type_name, length, and name field match and the story is in the value field.

Note:

The “News category” is just a string that the Reporter user and the Subscriber user agree on. There are no fixed categories in this sample. Therefore, both the Reporter user and the Subscriber user must type the same string when prompted for a category (including case and white space).

To run this sample, you must start at least one Reporter application and at least one Subscriber application; however, you may run multiple Reporters and Subscribers. Events posted by any Reporter will be delivered to all matching Subscribers (based on “News category”).

Also, be sure to start any subscribers before posting events; otherwise, the events will be lost.

Building and Running the Introductory Sample Application

To build and run the Introductory sample application, you must perform these steps:

1.	Verify that the "TUXDIR" environment variable are set to the correct directory path.

2.	Unset “JAVA_HOME”

3.	Copy the files for the Introductory sample application into a work directory.

4.	Change the protection attributes on the files to grant write and execute access.

5.	For UNIX, ensure the make file is in your path. For Microsoft Windows, ensure the nmake file is in your path

6.	Set the application environment variables.

7.	Build the sample.

8.	Boot the system.

9.	Run the Subscriber and Reporter applications.

10.	Shut down the system.

11.	Restore the directory to its original state.

These steps are described in detail in the following sections.

Verifying the Settings of the Environment Variables

Before you build and run the Introductory sample application, you need to ensure that the TUXDIR environment variable is set on your system. In most cases, this environment variable is set as part of the installation procedure. However, you need to check the environment variables to ensure they reflect correct information.

Table 5‑1 lists the environment variables required to run the Introductory sample application.

 

Table 5‑1 Required Environment Variables for the Introductory Sample Application

Environment Variable	Description
TUXDIR	The directory path where you installed the Oracle Tuxedo software. For example: Windows TUXDIR=c:\tuxdir UNIX TUXDIR=/usr/local/tuxdir

To verify that the information for the environment variables defined during installation is correct, perform the following steps:

Windows

1.	From the Start menu, select Settings.

2.	From the Settings menu, select the Control Panel.

The Control Panel appears.

3.	Click the System icon.

The System Properties window appears.

4.	Click the Environment tab.

The Environment page appears.

5.	Check the setting for TUXDIR

UNIX

ksh prompt>printenv TUXDIR

To change the settings, perform the following steps:

Windows

1.	On the Environment page in the System Properties window, click the environment variable you want to change.

2.	Enter the correct information for the environment variable in the Value field.

3.	Click OK to save the changes.

UNIX

ksh prompt>export TUXDIR=directorypath

Or

csh> setenv TUXDIR=directorypath

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

You need to copy the files for the Introductory sample application and files in the common directory into a work directory on your local machine.

Note:

The application directory and the common directory must be copied to the same parent directory.

The files are located in the following directories:

Windows

For the C++ Introductory sample:
drive:\tuxdir\samples\corba\notification\introductory_simple_cxx
drive:\tuxdir\samples\corba\notification\common

UNIX

For the C++ Introductory sample:
/usr/local/tuxdir/samples/corba/notification/
introductory_simple_cxx
/usr/local/tuxdir/samples/corba/notification/common

You use the files listed in Table 5‑2 and Table 5‑3 to build and run the C++ Introductory sample application, which is implemented using the Oracle Simple Events API.

 

Table 5‑2 Files Located in the introductory_sample_c++ Directory 

File	Description
Readme.txt	Describes the Introductory sample application and provides instructions for setting up the environment and building and running the application.
setenv.cmd	Sets the environment for Microsoft Windows systems.
setenv.ksh	Sets the environment for UNIX systems.
makefile.nt	Makefile for Microsoft Windows systems.
makefile.mk	Makefile for UNIX systems.
makefile.inc	Common makefile used by the makefile.nt and the makefile.mk files.
Reporter.cpp	Code for the reporter.
Subscriber.cpp	Code for the subscriber.
NewsConsumer_i.h and NewsConsumer.cpp	The callback servant class that subscribers use to receive news events. (For the Subscriber application.)

Table 5‑3 lists other files that the Introductory sample application uses.

 

Table 5‑3 Other Files the Introductory Sample Application Uses 

File	Description
The following files are located in the common directory.
common.nt	Makefile symbols for Microsoft Windows systems.
common.mk	Makefile symbols for UNIX systems.
introductory.inc	Makefile for administrative targets.
ex.h	Utilities to print exceptions. (For C++ only.)
client_ex.h	Client utilities to handle exceptions. (For C++ only.)
The following files are located in the \tuxdir\include directory.
CosEventComm.idl	The OMG IDL code that declares the CosEventComm module.
CosNotification.idl	The OMG IDL code that declares the CosNotification module.
CosNotifyComm.idl	The OMG IDL code that declares the CosNotifyComm module.
Tobj_Events.idl	The OMG IDL code that declares the Tobj_Events module.
Tobj_SimpleEvents.idl	The OMG IDL code that declares the Tobj_SimpleEvents module. Note: This file is needed only for the application that was developed using Oracle Simple Events API.
The following files are needed only for the application that was developed using CosNotification Service API.
CosEventChannelAdmin.idl	The OMG IDL code that declares the CosEventChannelAdmin module.
CosNotifyFilter.idl	The OMG IDL code that declares the CosNotifyFilter module.
CosNotifyChannelAdmin.idl	The OMG IDL code that declares the CosNotifyChannelAdmin module.
Tobj_Notification.idl	The OMG IDL code that declares the Tobj_Notification module.

Changing the Protection Attribute on the Files for the Introductory Sample Application

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

Windows

1.	In a DOS window, change (cd) to your work directory.

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

UNIX

1.	Change (cd) to your work directory.

2.	prompt>/bin/ksh

3.	ksh prompt>chmod u+w /workdirectory/*.*

On UNIX systems, you also need to change the permission of setenv.ksh to give execute permission to the file, as follows:

ksh prompt>chmod +x setenv.ksh

Setting Up the Environment

To set up the environment, enter the following command:

Windows

prompt>.\setenv.cmd

UNIX

ksh prompt>. ./setenv.ksh

Building the Introductory Sample Application

You use the make command to run makefiles, which are provided for Microsoft Windows and UNIX, to build the sample application. For UNIX, use make. For Microsoft Windows, use nmake.

Makefile Summary

The makefile automates the following steps:

1.	Checks that the set environment command (setenv.cmd) has been run. If the environment variables have not been set, the makefile prints an error message to the screen and exits.

2.	Includes the common.nt (for Microsoft Windows) or common.mk (for UNIX) command file. This file defines the makefile symbols used by the samples. These symbols allow the UNIX and Microsoft Windows makefiles to delegate the build rules to platform-independent makefiles.

3.	Includes the makefile.inc command file. This file builds the is_reporter and is_subscriber executables, and cleans up the directory of unneeded files and directories.

4.	Includes the introductory.inc command file. This file creates the UBBCONFIG file and executes the tmloadcf -y ubb command to create the TUXCONFIG file. This is a platform-independent makefile fragment that defines the administrative build rules common to the Introductory sample application.

Executing the Makefile

Before executing the makefile, you need to check the following:

•	Ensure that you have the appropriate administrative privileges to build and run applications.

•	On Microsoft Windows, verify that nmake is in the path of your machine.

•	On UNIX, verify that make is in the path of your machine.

To build the Introductory sample application, enter the make command as follows:

Windows

nmake -f makefile.nt

UNIX

make -f makefile.mk

Starting the Introductory Sample Application

To start the Introductory sample application, enter the following commands:

1.	To boot the Oracle Tuxedo system:

prompt>tmboot -y

This command starts the following server processes:

•

TMSUSREVT

An Oracle Tuxedo system-provided, EventBroker server that is used by the Notification Service.

•

TMNTS

An Oracle Tuxedo Notification Service server that processes requests for subscriptions and event postings.

•	TMNTSFWD_T

An Oracle Tuxedo Notification Service server that forwards events to subscribers that have transient subscriptions.

•

ISL

The IIOP Listener/Handler process.

2.	To start the Subscriber application:

For C++: prompt>is_subscriber

To start another Subscriber, open another window, change (cd) to your work directory, set the environment variables (by running setenv.cmd or setenv.ksh), and enter the start command that is appropriate for your platform.

3.	To start the Reporter application, open another window and enter the following:

For C++: prompt>is_reporter

To start another Reporter, open another window, change (cd) to your work directory, set the environment variables (by running setenv.cmd or setenv.ksh), and enter the start command that is appropriate for your platform.

Using the Introductory Sample Application

To use the Introductory sample application, you must use the Subscriber application to subscribe to an event and the Reporter application to post an event. Be sure to subscribe before you post each event; otherwise, events will be lost.

Note:

The Subscriber application shuts down after it receives one event.

Using the Subscriber Application to Subscribe to Events

Perform these steps:

1.	When you start the Subscriber application (prompt>is_subscriber), the following prompts are displayed:

Name? (Enter a name (without spaces).)
Category (or all)? (Enter the category of news you want or "all".)

You may type in any string for the news category; that is, there is no fixed list of news categories. However, when you use the Reporter application to post an event, make sure to specify the same string for the news category.

2.	The Subscriber application creates a subscription then prints “Ready” when it is ready to receive events. After the Subscriber receives one event, it shuts down.

Note:

You should always use the Subscriber application to subscribe to events before you use the Reporter application to post events; otherwise, events will be lost.

Using the Reporter Application to Post Events

Perform these steps:

1.	When you start the Reporter application (prompt> is_reporter), the following prompts are displayed:

(r) Report news
(e) Exit

Option?

2.	Enter r to report news. The following prompt is displayed:

Category?

3.	Enter the news category. It must match exactly the category you typed on the Subscriber application (including white space and case).

After you enter the news category, the following prompt is displayed:

Enter story (terminate with '.')

4.	Enter your story. It can span multiple lines. Finish the story by typing a period only (".") on a line, followed by a carriage return.

Subscribers whose category matches the category of this story will receive, and print out the story. When a subscriber receives a story, the subscriber automatically shuts down.

5.	To send and receive more news stories, start another subscriber, then report another story. When you are done reporting news, choose the Exit (e) option.

Note:

The Subscriber application shuts down after it receives one event. Therefore, always use the Subscriber application to subscribe to events before you use the Reporter application to post an event; otherwise, events will be lost.

Shutting Down the System and Cleaning Up the Directory

Perform the following steps:

Note:

Make sure the Reporter and Subscriber processes have stopped.

1.	To shut down the system, in any window, type:

prompt>tmshutdown -y

2.	To restore the directory to its original state, in any window, type:

Windows

prompt>nmake -f makefile.nt clean

UNIX

prompt>make -f makefile.mk clean