PersonQuery Sample Application

To understand and use the interceptor examples packaged with the Oracle Tuxedo software, you need to build and run the PersonQuery sample application. The PersonQuery sample application itself does not contain any interceptors; however, this application is used as the basis for the sample interceptor applications that are described in the three chapters that follow.

This topic includes the following sections:

•	How the PersonQuery Sample Application Works

•	The OMG IDL for the PersonQuery Sample Application

•	Building and Running the PersonQuery Sample Application

Notes:

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.

How the PersonQuery Sample Application Works

The PersonQuery sample application implements a simple database query interface. Using the PersonQuery application, a user can get information about people in the database that match specific search criteria, such as:

•	Physical characteristics, such as age, weight, hair color, eye color, or skin color

•	Name, address, or other details

The PersonQuery application contains the following components:

•	A client application, which issues requests that contain a variety of data types as parameters. The client application accepts command line input from the user in a specific form, packages the input according to the sample interface, and sends the appropriate request.

When the client application receives the result of the query from the server, it will report the number of items that were found. The user can then enter the command that displays the result of the latest query, or specify a new query.

•	A server application, which contains a simple, built-in database. The server application accesses the database to service the client request.

PersonQuery Database

The PersonQuery database in the server application contains the following information about each person in the database:

•

Name

•

Address

•	U.S. Social Security number

•

Sex

•

Age

•	Marital status

•

Hobby

•	Date of birth

•

Height

•

Weight

•	Hair color

•	Skin color

•

Eye color

•	Other physical characteristics

Client Application Command-line Interface

The PersonQuery sample application implements a simple command-line interface in the client component with which the user can enter database query commands and the command to exit from the application.

The database query commands have the following syntax:

Option? command [keyword] [command [keyword]]...

In this command syntax:

•	Option? is the PersonQuery command prompt.

•	command is one of the PersonQuery commands from Table 4‑1.

•	keyword is one of the keywords from Table 4‑1. Note the following rules on specifying keywords:

•	Compound keywords, as typically supplied for the name and address commands, must be separated by spaces and enclosed in double-quote characters (""), as in the following command:

Option? name "Thomas Mann"

•	When specifying an address, always separate street name, city name, state or province, country name, and other parts of the address with commas, as in the following command:

Option? address "116 Einbahnstrasse, Frankfurt am Main, BRD"

•	You may specify multiple commands in a single line, as in Table 4‑1:

Option? hair brown eyes blue

 

Table 4‑1 PersonQuery Application Commands and Keywords

Command	Keyword	Description
name	"firstname lastname"	Queries by name. Strings with spaces must be quoted.
address	"number street, city..."	Queries by address. Strings with spaces must be quoted. Address parts are street number, street, town, state, and country. Entries for street, town, state, and country must be separated by commas.
ss	xxx-xx-xxxx	Queries by U.S. Social Security number. The keyword must in the form xxx-xx-xxxx.
sex	sex	Queries by sex. Choices are male, female, and cant_tell.
age	age	Queries by age.
marriage	status	Queries by marital status. Choices are married, single, divorced, and not_known.
hobby	hobby	Queries by hobby. Choices are who_cares, rocks, swim, tv, stamps, photo, and weaving.
dob	mm/dd/yyyy	Queries by date. The keyword must be in the form mm/dd/yyyy.
height	inches	Queries by height, in inches.
weight	pounds	Queries by weight, in pounds.
hair	color	Queries by hair color. Choices are white, black, red, brown, green, yellow, blue, gray, and unknown.
skin	color	Queries by skin color. Choices are white, black, brown, yellow, green, and red.
eyes	color	Queries by eye color. Choices are blue, brown, gray, green, violet, black, and hazel.
other	feature	Queries by other physical features. Choices are tattoo, limb (that is, a limb is missing), scar, and none.
result		Displays the result of last query on output.
exit		Displays bill for services rendered and closes application.

The OMG IDL for the PersonQuery Sample Application

Listing 4‑1 provides the OMG IDL code for the implemented in the PersonQuery sample application.

Listing 4‑1 OMG IDL Code for the PersonQuery Application Interfaces

#pragma prefix “beasys.com”

interface PersonQuery
{
       enum MONTHS {Empty,Jan, Feb, Mar, Apr, May, Jun, Jul, Aug,
                     Sep, Oct, Nov, Dec};
       struct date_ {
                      MONTHS Month;
                      short Day;
                      short Year;
                  };
       typedef date_ Date;
       struct addr_ {
              short number;
              string street;
              string town;
              string state;
              string country;
       };
       typedef addr_ Address;
       enum MARRIAGE {not_known, single, married, divorced};
       enum HOBBIES {who_cares, rocks, swim, tv, stamps, photo,
                     weaving};
       enum SEX {cant_tell, male, female};
       enum COLOR {white, black, brown, yellow, red, green, blue,
                   gray, violet, hazel, unknown, dontcare};
       enum MARKINGS {dont_care, tattoo, scar, missing_limb,
                      none};
       struct person_ {
              string        name;
              Address       addr;
              string        ss;
              SEX           sex;
              short         age;
              MARRIAGE      mar;
              HOBBIES       rec;
              Date          dob;
              short         ht;
              long          wt;
              COLOR         hair;
              COLOR         eye;
              COLOR         skin;
              MARKINGS      other;
       };
typedef person_ Person;
        typedef sequence <Person> Possibles;
        union reason_ switch (short)
                {
                case 0:      string      name;
                case 1:      Address     addr;
                case 2:      string      ss;
                case 3:      SEX         sex;
                case 4:      short       age;
                case 5:      MARRIAGE    mar;
                case 6:      HOBBIES     rec;
                case 7:      Date        dob;
                case 8:      short       ht;
                case 9:      long        wt;
                case 10:     COLOR       hair;
                case 11:     COLOR       eyes;
                case 12:     COLOR       skin;
                case 13:     MARKINGS    other;
       };
       typedef reason_ Reason;

       exception DataOutOfRange
       {
              Reason why;
       };
      boolean findPerson (
                in Person who, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByName (
                in string name, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByAddress (
                in Address addr, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonBySS (
                in string ss, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByAge (
                in short age, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByMarriage (
                in MARRIAGE mar, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByHobbies (
                in HOBBIES rec, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonBydob (
                in Date dob, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByHeight (
                in short ht, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByWeight (
                in long wt, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByHairColor (
                in COLOR col, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonBySkinColor (
                in COLOR col, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByEyeColor (
                in COLOR col, out Possibles hits)
                raises (DataOutOfRange);
      boolean findPersonByOther (
                in MARKINGS other, out Possibles hits)
                raises (DataOutOfRange);
      void      exit();
};
interface QueryFactory
{
      PersonQuery createQuery (in string name);
};

 

Building and Running the PersonQuery Sample Application

To build and run the PersonQuery sample application:

1.	Copy the files for the PersonQuery sample application into a work directory.

2.	Change the protection of the files for the PersonQuery sample application.

3.	Set the environment variables.

4.	Build the CORBA client and server sample applications.

5.	Start the PersonQuery client and server applications.

6.	Using the client application, enter a number of commands to search the database on the server.

7.	Stop the PersonQuery sample application.

Copying the Files for the PersonQuery Sample Application

The request-level interceptor sample application files are located in the following directory:

$TUXDIR\samples\corba\interceptors_cxx

To create a copy of these files so that you can build them and run them, do the following:

1.	Create a working directory into which to copy the sample files.

2.	Copy the interceptors_cxx samples to the working directory created in the previous step:

Windows 2003

> xcopy /s/i %TUXDIR%\samples\corba\interceptors_cxx <workdirectory>\cxx

UNIX

> cp -R $TUXDIR/samples/corba/interceptors_cxx <workdirectory>/cxx

3.	Change to the working directory containing the sample files:

Windows 2003

> cd <workdirectory>\cxx

UNIX

> cd <workdirectory>/cxx

You will use the files listed and described in Table 4‑2 in the PersonQuery sample application.

 

Table 4‑2 Files Included in the Interceptors Sample Applications

Directory	File	Description
app_cxx (subdirectory under interceptors_cxx)	Readme.txt	The file that provides the latest information about building and running the set of interceptor sample applications.
	makefile.mk	The makefile for building the entire set of interceptor sample applications (the PersonQuery application and all the sample interceptors) on UNIX systems.
	makefile.nt	The makefile for building the entire set of interceptors sample applications (the PersonQuery application and all the sample interceptors) on Windows 2003 systems.
	makefile.inc	The generic makefile that uses the macros defined in the appropriate platform.inc file.
	personquery_i.h and personquery_i.cpp	The implementation of the PersonQuery interfaces.
	personqueryc.cpp	The PersonQuery client application source file.
	personquerys.cpp	The PersonQuery database server source file.
	setenv.ksh	The shell file that sets all the required environment variables for building the entire set of interceptor sample applications on UNIX systems.
	setenv.cmd	The command file that sets all the required environment variables for building the entire set of interceptor sample applications on Windows 2003 systems.
data_cxx (subdirectory under interceptors_cxx)	InterceptorData.cpp	The InterceptorData C++ source file.
	InterceptorData.h	The InterceptorData class definition file.
	makefile.inc	The generic makefile that uses the macros defined in the appropriate platform.inc file to build the InterceptorData interceptors.
	makefile.mk	The makefile that builds the InterceptorData interceptors on UNIX systems.
	makefile.nt	The makefile that builds the InterceptorData interceptors on Windows 2003 systems.
simple_cxx (subdirectory under interceptors_cxx)	InterceptorSimp.cpp	The InterceptorSimp C++ source file.
	InterceptorSimp.h	The InterceptorSimp class definition file.
	makefile.inc	The generic makefile that uses the macros defined in the appropriate platform.inc file to build the InterceptorSimp interceptors.
	makefile.mk	The makefile that builds the InterceptorSimp interceptors on UNIX systems.
	makefile.nt	The makefile that builds the InterceptorSimp interceptors on Windows 2003 systems.
security_cxx (subdirectory under interceptors_cxx)	InterceptorSec.cpp	The InterceptorSec C++ source file.
	InterceptorSec.h	The InterceptorSec class definition file.
	makefile.inc	The generic makefile that uses the macros defined in the appropriate platform.inc file to build the InterceptorSec interceptors.
	makefile.mk	The makefile that builds the InterceptorSec interceptors on UNIX systems.
	makefile.nt	The makefile that builds the InterceptorSec interceptors on Windows 2003 systems.
common (subdirectory under interceptors_cxx)	app.inc	The file that contains the makefile definitions for the application configuration.
	platform.inc	The file that contains platform-specific make definitions for building the set of interceptor sample applications, where platform represents the system platform for the machine you are using.
	common.mk	The file that contains makefile definitions for UNIX systems.
	makefile.inc	The generic makefile that uses the macros defined in the appropriate platform.inc file.
	makefile.mk	The makefile that builds the entire set of sample application files on UNIX systems.
	makefile.nt	The makefile that builds the entire set of sample application files on Windows systems.
	personquery.idl	The OMG IDL file that defines the interfaces for the PersonQuery sample application.

Changing the Protection on PersonQuery Application Files

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

Windows 2003

prompt>attrib -r /s *.*

UNIX

prompt>/bin/ksh
ksh prompt>chmod -R u+w *.*

Setting the Environment Variables

Before building and running the PersonQuery sample application, you need to set the environment in which the application runs. To set the environment variables and other property settings needed to build and run the PersonQuery sample application, enter the following command:

Windows 2003

> setenv.cmd

UNIX:

> $ . ./setenv.ksh

Building the CORBA Client and Server Applications

The following command builds the PersonQuery application, creates a machine-specific UBBCONFIG file, and loads the UBBCONFIG file:

Windows 2003

> nmake -f makefile.nt

UNIX

$ make -f makefile.mk

Note:

For convenience, the makefile executed in this step builds the entire set of interceptor samples. This includes the InterceptorSimp, InterceptorSec, and InterceptorData interceptors as well. Details on implementing and building those interceptors, as well as running them with the PersonQuery sample application, are provided in the chapters that follow.

Start the PersonQuery Client and Server Applications

Start the PersonQuery sample application by entering the following command:

prompt> tmboot -y

Running the PersonQuery Sample Application

A typical usage scenario of the PersonQuery sample application involves the following steps:

1.	Enter a query command for one feature, and check for number of returned items, for example:

Option? hair brown eyes blue

2.	Enter additional query data about the feature queried in the preceding step.

3.	Continue queries until all the query data is narrowed down to a desirable level.

4.	Enter the result command to see the final query result.

5.	Start a new query cycle.

6.	Enter the exit command to quit from the application.

Stopping the PersonQuery Sample Application

To stop the PersonQuery sample application, enter the following command:

prompt>tmshutdown -y