Building the Advanced Sample Application

This topic includes the following sections:

•

Overview

•	Building and Running the Advanced 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 Advanced sample application simulates a newsroom environment in which a news reporter posts a story, a wire service posts the story as an event to the Notification Service, and a news subscriber consumes the story.

One implementation of the Advanced sample application is provided: the C++ that uses the CosNotification Service API.

The Advanced sample application consists of the reporter, subscriber, and wire service applications that use the Oracle Tuxedo CORBA Notification Service. The reporter application implements a client application. This application prompts the user to enter news articles and calls the WireService server using application specific IDL. The WireService server, in turn, posts the events. The subscriber implements a joint client/server application. This application 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 callback objects which are invoked by the Notification Service when an event needs to be delivered.

Note:

On UNIX systems, you cannot immediately restart the subscriber because the port takes some time (the actual time depends on the platform) to become available again. If you restart too soon, you will get a CORBA::OBJ_ADAPTER exception. If this occurs, just wait and try again. On Solaris systems, the port can take up to 10 minutes to become available. To see if the port is still in use, use this command: “Restart -a | grep <the port number>”.

This Advanced sample application demonstrates how to use the Oracle Simple Events API, the CosNotification Service API, transient and persistent subscriptions, and data filtering.

This Advanced sample provides three executables (see Figure 6‑1):

•	A WireService application that posts events. It is a Notification Service client and an Oracle Tuxedo CORBA server. It implements an OMG IDL interface, which the Reporter application uses.

•	A Reporter application that reports news stories by invoking methods on the WireService. The WireService, in turn, converts the stories into events and posts them using the Notification Service. The reporter is a pure client.

•	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 for events, and acts as a server when it receives events.

Figure 6‑1 Advanced Sample Application Components

The event poster, the WireService application, uses the structured event domain_name, type_name, and filterable_data fields to construct three events: a news event, a subscriber shutdown event, and a subscriber cancel event.

•	News event

For this event, the domain name is a string and is preset by the application as “News”. The type name is a string and defined by the Reporter application user at run time. It is set to the category of news (for example, “Sports”). Filterable data contains a name/value pair whose name is “Story” and whose value is a string that contains the body of the news story being posted.

•	Subscriber Shutdown event

For this event, the domain name is a string and is preset by the application as “NewsAdmin”. The type name is a string and is preset by the application as “Shutdown”. The filterable data is not used.

•	Subscriber Cancel event

For this event, the domain name is a string and is preset by the application as “NewsAdmin”. The type name is a string and is preset by the application as “Cancel”. The filterable data is not used.

The Subscriber application uses the structured event domain_name, type_name, and filterable_data fields to construct two subscriptions: a news subscription that processes news stories; and a shutdown subscription that processes Cancel and Shutdown events. At run time, the Subscriber application establishes these two subscriptions with the Notification Service.

•	News subscription

The Subscriber application uses the structured event domain_name, type_name, and filterable_data 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 “Keyword” and uses the inputs to define the type_name and data_filter fields in the subscription. Obviously, the users of both applications, the reporter and the subscriber, must collaborate on the “News Category” and “keyword” strings for the subscription to match an event, otherwise, no News 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.

•	Shutdown subscription

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 “NewsAdmin”, the type_name as a string of either “Shutdown” or “Cancel”. The filterable_data field is an empty string.

The Reporter application is responsible for implementing the user interface for reporting news as well as for producing Shutdown and Cancel events. Rather than use the Notification Service directly to post events, it calls methods on the WireService server.

The WireService server uses the Notification Service to post three kinds of events:

•	“News” events (used to deliver news to subscribers)

•	“Shutdown” events (used to shut down subscribers temporarily)

•	“Cancel” events (used to shut down subscribers permanently)

The Notification Service, in turn, delivers the events to the subscribers.

The subscriber uses the Notification Service to create a persistent subscription to news events. The subscriber implements a persistent 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, the Notification Service invokes a push_structured_event method on this callback object to push the event to the subscriber. This method prints out the event.

The subscriber also uses the Notification Service to create a transient subscription to Shutdown and Cancel events. The subscriber implements another callback object (via the ShutdownConsumer_i servant class), which is used to receive and process these events.

Whenever the subscriber runs, it prompts the user for a name. The first time this user runs the subscriber program, the subscriber creates a persistent subscription to News events. To do this, the subscriber prompts the user for which kind of news stories to subscribe to and which port number the subscriber should run on. The subscriber runs on this port, subscribes, then writes the subscription ID, the filter ID (if using the CosNotification API), and the port number to a file (the name of the file is <user_name>.pstore). The next time the subscriber runs, the subscriber prompts the user for a name, opens up the file <user_name>.pstore then reads the subscription ID, filter ID (if using the CosNotification API) and port number for this user from the file. This satisfies the requirement that the subscriber runs on the same port number each time because its news callback object's object reference is persistent.

The Subscriber creates a transient subscription to receive the Shutdown and Cancel events, therefore, the transient subscription is created and destroyed every time the subscriber is run and shut down. This subscription ID is not written out to the file <user_name>.pstore.

When the subscriber receives a Shutdown event, it destroys the shutdown/callback subscription but leaves the News subscription intact. If News events are posted after the subscriber is shut down and before it is restarted, then the notification service will either deliver the events when the subscriber is restarted, or will put the events on the error queue. (You can use the ntsadmin utility to either delete these events from the error queue or retry delivering them.)

Whether the event is redelivered or is put on the error queue depends on whether the subscriber restarts quickly enough. This depends on the retry parameters of the queue. See advanced.inc (in the notification samples' common directory) for the values of the queue retry parameters.

News events have two parts: a category (for example, headline) and a story (a multiple-line text string). The Subscriber application prompts the user to input a news category. Next the subscriber subscribes to news events whose category matches this string. The Reporter application prompts the user for a news category and a story. Next the reporter (by invoking a method on the wire service) posts a corresponding news event. The event will only be delivered to subscribers who subscribed to that category of news.

Note:

The category is a string. The same string must be used by the Reporter user and the Subscriber user. There are no fixed categories in this sample. Therefore both users, the Reporter user and the Subscriber user, must type the same string when prompted for a category (including case and white space).

This sample also uses data filtering. When a user first runs the Subscriber, the user will be prompted for a “keyword.” Events whose category matches and whose story contains the keyword will be delivered to the subscriber. For example, if the user enters a keyword of “none,” data filtering will not be used (thus the user will receive all events for the chosen news category). If the user enters a keyword “smith”, it translates to “Story %% ’.*smith.*’”. This keyword specifies that the subscription only accepts events that have a “Story” field that contains a string, and that the field starts with any number of characters, has a literal string “smith”, and then ends with any number of characters.

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

Also, be sure to start any subscribers before posting events. Events posted before the subscribers are started will not be delivered.

Building and Running the Advanced Sample Application

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

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

2.	Unset and “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 Advanced 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 the correct information.

Table 6‑1 lists the environment variables required to run the Callback sample application.

 

Table 6‑1 Required Environment Variables for the Callback 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

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

You need to copy the files for the Advanced sample application 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 for the Advanced sample application are located in the following directories:

Windows

For the C++ Advanced sample: drive:\tuxdir\samples\corba\notification\advanced_cos_cxx
drive:\tuxdir\samples\corba\notification\common

UNIX

For the C++ Advanced sample: /usr/local/tuxdir/samples/corba/notification/advanced_cos_cxx
/usr/local/tuxdir/samples/corba/notification/common

You use the files listed in Table 6‑2 and Table 6‑3 to build and run the C++ Advanced sample application, which is implemented using the CosNotification API.

 

You use the files listed in Table 6‑2 and Table 6‑3 to build and run the Advanced sample application.

 

Table 6‑2 Files Located in the advanced_cos_c++ Notification Directory

File	Description
Readme.txt	Describes the Advanced 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	Callback servant class that subscribers use to receive news events. (For the Subscriber application.)
ShutdownConsumer_i.h and ShutdownConsumer.cpp	Callback servant classes that subscribers use to receive Shutdown and Cancel events. (For the Subscriber application.)
WireServiceServer.cpp	Code for the WireService server.
News.icf	ICF file for the WireService interfaces.
WireService_i.h and WireService.cpp	Implements the WireService interfaces.

Table 6‑3 lists other files that the Advanced sample application uses. With the exception of the IDL files, the files are located in the Notification common directory.

 

 

 

Table 6‑3 Other Files That the Advanced Sample Uses 

File	Description
The following files are located in the common directory.
News.idl	IDL definitions for the WireService server.
news_flds	FML field definitions used to perform data filtering and news events.
common.nt	Makefile symbols for Microsoft Windows systems.
common.mk	Makefile symbols for UNIX systems.
advanced.inc	Makefile for administrative targets.
ex.h	Utilities to print exceptions (C++ only).
client_ex.h	Client utilities to handle exceptions (C++ only).
server_ex.h	Server utilities to handle exceptions.
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 Advanced Sample Application

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

Windows

1.	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 the UNIX operating system platform, 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

prompt>. ./setenv.ksh

Building the Advanced Sample Application

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

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, is_subscriber and AS_WIRESERVICE executables, and cleans up the directory of unnecessary files and directories.

4.	Includes the advanced.inc command file. This file executes tmadmin and qadmin commands to create the transaction log and the queues required by the persistent subscriptions. It also creates the UBBCONFIG file and executes the tmloadcf -y ubb command to create the TUXCONFIG file.

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, make sure nmake is in the path of your machine.

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

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

Windows

nmake -f makefile.nt

UNIX

make -f makefile.mk

Starting the Advanced Sample Application

To start the Advanced 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 CORBA Notification Service server that processes requests for subscriptions and event postings.

•	TMNTSFWD_T

An Oracle Tuxedo CORBA Notification Service server that forwards events to subscribers that have transient subscriptions. This server is required for transient subscriptions.

•	TMNTSFWD_P

An Oracle Tuxedo CORBA Notification Service server that forwards persistent events to subscribers that have persistent subscriptions. This server is required for persistent subscriptions.

•

TMQUEUE

The message queue manager is an Oracle Tuxedo system-provided server that enqueues and dequeues messages on behalf of programs calling tpenqueue(3) and tpdequeue(3), respectively. This server is required for persistent subscriptions.

•	TMQFORWARD

The message forwarding server is an Oracle Tuxedo system-provided server that forwards messages that have been stored using tpenqueue(3c) for later processing. This server is required for persistent subscriptions.

•	WIRE_SERVICE_SERVER

A server, specifically built for the Advanced sample application, that receives events from the Reporter application and posts them to the Notification Service. This receive and server posts three types of events: News, Shutdown, and Cancel.

•

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 Advanced Sample Application

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

Using the Subscriber Application to Subscribe to Events

Perform the following steps:

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

Name? (Enter a name (without spaces).)
Port (e.g. 2463) (Enter the port number that this subscriber should run on.)
Category (or all) (Enter the category of news you want or "all.")
Keyword (or none) (Enter a keyword that you want all delivered stories to
contain.)

Note:

If the Subscriber application is shut down by a Shutdown event from the Reporter application (Shutdown events do not cancel persistent subscriptions), on subsequent startups of the Subscriber application, you will only be prompted for your name. The Subscriber application retrieves the remaining information from the <user_name>.pstore file. This guarantees that the same port number is used, which is required for persistent subscriptions.

If the Subscriber application is shut down by a Cancel event from the Reporter application (Cancel events cancel all subscriptions including persistent subscriptions), on subsequent startups of the Subscriber application, you will be prompted for your name, port number, category, and keyword.

2.	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 you specify the same string for the news category.

Similarly, you may type in a string for a keyword. There is no fixed list of keywords either so when you run the reporter and enter the story, make sure that the story contains the same string; otherwise, the story will not be delivered to your subscription.

The first time the Subscriber application is run for your username, category (or all), and keyword (optional), it creates a news subscription. On subsequent runs, the subscriber reuses this subscription. In all cases, the Subscriber application prints “Ready” when it is ready to receive events.

The Subscriber application creates a subscription then prints “Ready” when it is ready to receive events.

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. This is because even though the Subscriber application creates a persistent subscription to News events, that subscription is not created until the Subscriber application is started.

Note:

You can start multiple subscribers by opening another window and repeating this procedure.

Using the Reporter Application to Post Events

Perform the following steps:

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

(r) Report news
(s) Shutdown subscribers
(c) Cancel Subscribers
(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. If you typed in a keyword when subscribing, make sure the story contains this string (including white space and case).

Subscribers whose category and keyword (if specified) matches the category and a keyword in this story will receive and print out the story.

5.

If you choose the “s” option, a Shutdown event will be posted and received by all the subscribers and the subscribers will shut down. While the subscribers are shut down, you may post another news story (by using the “r” option again). The Notification Service will place the news story on the pending queue but the News event subscription is persistent and, therefore, is still in effect. After you restart the subscribers, they will receive this second news story (unless a restart delay caused the event to be moved to the error queue). This is because the subscriber created a persistent subscription for news stories.

Note:

You can use the ntsadmin retryerrevents command to move events from the error queue back to the pending queue.

6.

If you choose the “c” option, a Cancel event will be posted and received by all the subscribers. The subscribers will cancel their news subscriptions and shut down. If you try to restart the subscribers, then you will be prompted again for port, category, and keyword because you are creating a new subscription.

7.	When you are finished reporting news, choose the Exit (e) option.

Note:

You can start multiple reporters by opening another window and repeating this procedure. Any news story reported by any reporter will be delivered to all matching subscribers. Make sure you have exited all reporters before shutting down the system.

Shutting Down the System and Cleaning Up the Directory

Make sure the Reporter and Subscriber processes have stopped and perform the following steps:

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