API Overview

This describes naming conventions, class hierarchies, the file names and directory structure of generated code and other issues relevant to understanding and using the C++ Expert API.
 

Programming Model and Data Type Mapping

Member functions described in this section are generated by C++ Expert based on their description in the Contract Repository, which are derived from BEA TUXEDO service definitions. This table shows the relationship between the BEA TUXEDO, Contract Repository, and C++ Expert definitions.

Table 4-2 Programming Model Relative Mapping

BEA TUXEDO	Contract Repository	C++ Expert
server	module	server
None	interface	service implementation & service request
service	operation	service
parameter	parameter	parameter

The following table shows relationship between the BEA TUXEDO, the Contract Repository and C++ Expert data types.

Table 4-3 Basic Data Type Mapping

BEA TUXEDO	Contract Repository	C++ Expert
short	short	short
long	long	long
char	char	char
float	float	float
double	double	double
string	string	char*
carray	carray	character array
int	converted to long	converted to long
dec_t	Not Supported	Not Supported

The architecture of the application generated by the C++ Expert is built around the Contract Repository metamodel, shown below.

Figure 4-1 Contract Repository Metamodel

The C++ Expert uses the information from the Contract Repository to generate C++ bindings for each item in the form of Service Request classes and Server Implementation classes. Those elements are mapped to C++ classes in this fashion:

• A Contract Repository module is mapped to a C++ namespace and is currently implemented as a nested class. The module becomes a BEA TUXEDO server executable with services that correspond to operations specified in the interfaces of this module.

• A Contract Repository interface is mapped to an abstract base class (nested in the class generated for the module) in which the implementations of all member functions are deferred to derived classes. This class does not have any data members. Two specialized classes are generated from this abstract base class. The member functions of the first are used to implement the specified BEA TUXEDO services. The member functions of the second are used to invoke those services.

• A Contract Repository operation is mapped to a pure virtual member function of the abstract base class. The signature of this member function is derived in this fashion:

  • The name of the operation becomes the name of the member function; the input parameters (and their types) become the parameters of that member function.

  • If the operation throws an exception, the exception is also thrown by the member function.

  • All output parameters are used to generate a reply class which is returned by the member function.

  • The generated exception class and the reply class are nested inside the pure abstract class of the interface.

• Contract Repository parameters are mapped to the parameters of member functions.

• The element and structure entities in the Repository are mapped to the type of the parameters.

• The Contract Repository operation is also used to generate a free standing, global scope C++ function with C linkage. The BEA TUXEDO server main function transfers control to this C++ function in response to a service request from a client.

• Server specific classes are also generated from the Contract Repository module and linked to the BEA TUXEDO application server through the tpsvrinit and tpsvrdone C functions of the BEA TUXEDO server.

C++ Expert Classes and Naming Conventions

There are two types of classes supplied with the C++ Expert:

• Base classes and exception classes supplied with the C++ Expert

• Derived classes and exceptions generated by the C++ Expert with names derived from objects in the Contract Repository

All of the classes supplied with the C++ Expert are contained in the BEATuxBldr namespace.
 

Naming Generated Classes

When we refer to a class with a derived name, the derived part is italicized and enumerated. For example, a Generated Server class takes it's name from the module where it is implemented and would be referred to as the Module1Srv class or object.

Table 4-4 Referring to Generated Classes

Contract Repository	Generated Class Name
module	Module1, Module2, ...
interface	Interface1, Interface2, ...
operation	Operation1, Operation2, ...
parameter	Parameter1, Parameter2, ...

This convention is used in the figures that follow and throughout this document.
 

The BEATuxBldr Namespace

The following diagram shows the hierarchy of classes within the BEATuxBldr namespace. Individual exception classes are shown in a separate diagram.

Figure 4-2 BEATuxBldr namespace

Exception Classes

The following figure shows the exception class hierarchy:

Figure 4-3 Exception Hierarchy, within the BEATuxBldr namespace

All user defined, operation specific exceptions are sub-classes of AppException.

All BEA TUXEDO errors are encapsulated in sub-classes of TuxException. Errors relating to ATMI calls are encapsulated in AtmiException, and errors relating to FML buffer handling operations are encapsulated in FmlException. Client applications requesting a BEA TUXEDO service must be prepared to handle TuxException or handle AtmiException and FmlException individually, in addition to any user specified exceptions for the operations.

The server application can throw user-specified exceptions, which are relayed to the client application. Exceptions derived from TuxException hierarchy are raised from the C++ Expert generated code and user programs are not expected to raise them on their own.

Exceptions that are sub-classed from TransactionException are thrown by operations on Transaction. These exceptions correspond to the error codes returned by functions defined in the Tx Transaction Demarcation Specification. A brief text description of the exception is returned by the GetMessage member function of each class.

Note: In order make exception handling vendor-independent, the C++ Expert generates exception objects and throws them by a pointer to the object, rather than by value. Therefore, C++ Expert exceptions must be caught by the client application via pointer, rather than by reference. The client is also responsible for deleting them.
 

Generated Files

This section describes the files generated by the C++ Expert, and where they can be found.
 

Directory Structure

The C++ Expert places its generated class header and source files, make files and FML field table files in a directory structure determined by the name of the project, individual modules and interfaces and the Contract Repository contents. This structure descends from the project root directory, which is specified by the user on the Generate Framework Classes tab of the Settings dialog. A sample of this structures shown in the following figure:

Figure 4-4 Sample Directory Structure

The ProjectRoot directory can be specified on the Generate Settings window.

The Project1.FML file contains the FML field table, generated by the Generate FML Field Tables command. The value of Project1 can be specified on the Generate Settings window. The default name is FMLFieldTableFile.

The Module1 directory contains all the generated files associated with the first module.

The BEATuxBldr.h and BEATuxBldr.cpp files contain all classes and definitions supplied with the C++ Expert.

The Module1.mak file contains the generated make declarations and targets for the server and the test client.

The Module1.h file contains the name space definitions that correspond to the module.

The Module1_tst.cpp file contains the code generated for the test client described in the Testing Default Service Implementations section.

The Module1Srv.h and Module1Srv.cpp files contain the class definition and member functions used for server start-up, shut down and Resource Manager access. Default implementations of them are provided, but you can extend both the interface and the default implementation independently.

The Interface1.h and Interface1.cpp files contains the class definition and member functions used for the remote object used by the client to access services.

The Interface1Impl.h and Interface1Impl.h files contains the class definition and member functions used for implementing BEA TUXEDO services. The body of a member function is left blank, to be provided by the server application developer, when you do not choose to generate operation test logic.

The Interface1Skel.cpp file contains the global scope C++ function with C linkage used by the BEA TUXEDO framework.

The Module1_Interface1.h and Module1_Interface1.cpp contains the class definition and member functions which is used as the base class for the Interface1 and Interface1Impl derived classes.

The files listed below can be moved to the client platform so that client applications can request services defined in this interface:

• FMLFieldTableFile.fml

• Module1.h

• Interface.h, Interface.cpp

• Module1_Interface1.h, Module1_Interface1.cpp

Make files

All the interfaces in a single module are contained in a single BEA TUXEDO server executable. When the C++ Expert generates code for a module selected in the Main Window, a make file is also generated. The name of the generated make file based on the module name and the current platform:

Table 4-5 Generated make file Naming and Use

Platform	File name
UNIX	Module1.mk
Windows NT	Module1.mak

The Resource Manager (if any), the C++ compiler, and compilation flags used in the make file can be specified on the Makefile Settings window. The generated make file is placed in the directory created for each module. While the Confirm Selection window is displayed, you can also override the default Resource Manager and Server name settings on a module by module basis.
 

FML Field Table File

Elements in the Contract Repository can be mapped to FML fields. Users will be able to enter FML field names when they create elements in the repository using the Repository Editor. Uniqueness of these field names is ensured by the repository. The repository also maintains a mapping between these field names and FML field identifier values. The C++ Expert uses this mapping to generate a FML field table file for all the elements in the repository. Using the BEA TUXEDO mkfldhdr utility, a header file is generated from the field table file and used in all the generated server and client files.

The make file has rules for compiling the files generated by the C++ Expert. Default rules are generated for compiling the user defined code in the implementation files (refer to Listing 4-4, Interface1Impl.h and Interface1Impl.cpp) and for building the servers. The user can edit the make file to customize the default rules.
 

The gservers.lst File

This file is generated for the BEA TUXEDO Builder Configuration Expert and placed in the ProjectRoot directory (see Figure 4-4, in the Sample Directory Structure section). The ProjectRoot directory can be specified on the Generate Settings window.

Each line of this text file contains information about the Resource Manager used by the server (if any), the name of the server executable and the module for which the server is constructed.