Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.beasys.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WLE Doc Home   |   Notification Services & Related Topics   |   Previous   |   Next   |   Contents   |   Index

This section contains the following topics:

• Overview

• Building and Running the Introductory Sample Application

Overview

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

Two implementations of the Introductory sample application are provided: one in the C++ programming language that uses the BEA Simple Events application programming interface (API), and another in Java that uses the CosNotification Service 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 WLE Notification Service. The subscriber 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.

This sample application shows the simplest usage of Notification Service. It demonstrates how to use the BEA 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 Building the Advanced Sample Application.

This Introductory sample 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" and "JAVA_HOME" environment variables are set to the correct directory path.

   Note: The "JAVA_HOME" environment variable is required for Java applications only.

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

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

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

5. Set the application environment variables.

6. Build the sample.

7. Boot the system.

8. Run the Subscriber and Reporter Applications.

9. Shut down the system.

10. 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 WLE software. For example: Windows NT TUXDIR=c:\wledir UNIX TUXDIR=/usr/local/wledir
JAVA_HOME (For Java applications only)	The directory path where you installed the JDK software. For example: Windows NT JAVA_HOME=c:\JDK1.2.2 UNIX JAVA_HOME=/usr/local/JDK1.2.1

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

Microsoft Windows NT

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 and JAVA_HOME .

UNIX

ksh prompt>printenv TUXDIR

ksh prompt>printenv JAVA_HOME

To change the settings, perform the following steps:

Microsoft Windows NT

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

ksh prompt>export JAVA_HOME= directorypath

Or

csh> setenv TUXDIR=directorypath

csh> setenv JAVA_HOME=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:

Microsoft Windows NT

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

For the Java Introductory sample: drive:\wledir \samples\corba\notification\introductory_cos_java
drive:\wledir \samples\corba\notification\common

UNIX

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

For the Java Introductory sample: /usr/local/wledir /samples/corba/notification/
introductory_simple_cxx
/usr/local/wledir /samples/corba/notification/common

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

Table 5-2 Files Located in the introductory_sample_c++ Notification 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 NT systems.
setenv.ksh	Sets the environment for UNIX systems.
makefile.nt	Makefile for Microsoft Windows NT 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 Files Located in the introductory_cos_java Notification 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 NT systems.
setenv.ksh	Sets the environment for UNIX systems.
makefile.nt	Makefile for Microsoft Windows NT systems.
makefile.mk	Makefile for UNIX systems.
makefile.inc	Common makefile used by the makefile.nt and the makefile.mk files.
Reporter.java	Code for the reporter.
Suscriber.java	Code for the subscriber.
NewsConsumer_i.java	The callback servant class that subscribers use to receive news events. (For the Subscriber application.)

Table 5-4 lists other files that the Introductory sample uses.

Table 5-4 Other Files that the Introductory Sample Uses

File	Description
The following files are located in the common directory.
common.nt	Makefile symbols for Microsoft Windows NT 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.)
ShutdownManager.java	Class to help the main and the servant in the Notification Service java samples coordinate shutting down the server. Note: This file is needed for the Java application 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 BEA 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 WLE 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:

Microsoft Windows NT

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:

Microsoft Windows NT

prompt>.\setenv.com

UNIX

ksh prompt>. ./setenv.ksh

Building the Introductory Sample Application

You use the make command to run makefiles , which are provided for Microsoft Windows NT and UNIX, to build the sample application. For UNIX, use make . For Microsoft Windows NT, 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 NT) 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 NT 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 samples.

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 NT, 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:

Microsoft Windows NT

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 WLE system:

prompt>tmboot -y

This command starts the following server processes:

• TMSUSREVT

  A BEA TUXEDO system-provided, event broker server that is used by the Notification Service.

• TMNTS

  A WLE Notification Service server that processes requests for subscriptions and event postings.

• TMNTSFWD_T

  A WLE Notification Service server that forwards events to subscribers that have transient subscriptions.

• ISL

  The IIOP Server Listener/Handler process.

1. To start the Subscriber application:

   For C++: prompt>is_subscriber
   For Java on Microsoft Windows NT: prompt>java %IC_SUBSCRIBER%
   For Java on UNIX: prompt>java $IC_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.

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

   For C++: prompt>is_reporter
   For Java on Microsoft Windows NT: prompt>java %IC_REPORTER%
   For Java on UNIX: prompt>java $IC_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.

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 Subscribe application to subscribe to events before you use the Reporter application to post events; otherwise, events will be lost.

Perform these steps:

1. When you start the Report 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 Subscribe application to subscribe to events before you use the Reporter application to post an event; otherwise, events will be lost.

Perform these steps:

Note: Make sure the Reporter and Subscriber processes have stopped.

1. To shutdown the system, in any window, type:

prompt>tmshutdown -y

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

Microsoft Windows NT

prompt>nmake -f makefile.nt clean

UNIX

prompt>make -f makefile.mk clean