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 Rose Expert API.
 

Programming Model and Data Type Mapping

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

Table 4-2 Programming Model Relative Mapping

BEA TUXEDO	Rose Model	Rose Expert
server	task module	server
None	control class	service implementation and request classes
service	operation	service
parameter	parameter	parameter

The following table shows relationship between the BEA TUXEDO, the Rose Model and Rose Expert data types.

Table 4-3 Basic Data Type Mapping

BEA TUXEDO	Rose Model	Rose Expert
short	short	short
long	long	long
char	char	char
float	float	float
double	double	double
string	string	char*
carray	char with length	character array
int	converted to long	converted to long
dec_t	Not Supported	Not Supported

The architecture of the application generated by the Rose Expert is built around the Rose metamodel, shown below.

Figure 4-1 Rose Metamodel

The Rose Expert uses the information from the Rose Model 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 Rose Model 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 Control Classes of this module.

• A Rose Model Control Class 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 Rose Model Control Class 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.

• The Structure classes in the Rose Model are mapped to C++ structures and used as a type in the parameter description.

• The Rose Model 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 Rose Model task module and linked to the BEA TUXEDO application server through the tpsvrinit and tpsvrdone C functions of the BEA TUXEDO server.

Rose Expert Classes and Naming Conventions

There are two types of classes supplied with the Rose Expert:

• Base classes and exception classes supplied with the Rose Expert.

• Derived classes and exceptions generated by the Rose Expert with names derived from objects in the Rose Model.

All of the classes supplied with the Rose 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 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 Rose 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 Rose Expert generates exception objects and throws them by a pointer to the object, rather than by value. Therefore, Rose 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 Rose Expert, and where they can be found.
 

Directory Structure

The Rose 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 selected Component Package, individual modules and interfaces and the Rose Model contents. This structure descends from the project root directory, which is specified by the user on the Generation Settings window. A sample of this structures shown in the following figure:

Figure 4-4 Sample Directory Structure

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

The ComponentPackage1.FML file contains the FML field table.

The ComponentPackage1 directory contains all the generated files associated with all the modules in ComponentPackage1.

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

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

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

The ComponentPackage1_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 service 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:

• ComponentPackage1.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 Rose Expert generates code for the selected component package, a make file is also generated. The name of the generated make file based on the Component Package name and the current platform:

Table 4-5 Generated make file Naming and Use

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

The Resource Manager (if any) is specified in the BEABuilder tab for a task module in the Rose Model. (For information on specifying the resource manager, refer to BEABuilder Tab in Rose Component Specification for a Task Module.) 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.
 

FML Field Table File

The Rose Model has Control Classes with operations and Structure Classes with attributes. The operation parameters and the Structure Class attributes can be mapped to FML fields. 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 Rose 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 it.
 

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 for a sample directory structure). The ProjectRoot directory can be specified on the Generation 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.