Chapter 14: Creating CORBA C++ Components

Writing the class implementation

After you generate the method skeleton file, class header file, and class implementation template, write the code for each method in the class implementation template (you can also write your class implementation from scratch and replace the generated class implementation template).

You must use scoped names to specify the CORBA IDL module, the EAServer SessionManager IDL module, and any component IDL modules that you want to execute methods on. To make using scoped names easier, you can use the C++ using statement for the IDL module namespaces as in the following example:

using namespace CORBA;
using namespace SessionManager;

If your C++ compiler does not support namespaces, define a compiler macro JAG_NO_NAMESPACE when compiling your source files.

CORBA::is_nil(Object) can be used to verify that a specific interface is implemented by a component.

As with any C++ class, you use the constructor and destructor to initialize and perform any cleanup of objects.

Constructors of class variables in file scope not called If you declare a class variable in file scope and compile it into a shared object, such as a component, the Solaris C++ compiler doesn’t call the constructor of the class variable. If the variables need to be in scope only for a particular function, procedure or module, then declare these variables in the appropriate function, procedure, module; otherwise declare these variables in the class definition.

You can also include EAServer C routines to:

Cache connections to third-tier database servers
Return result sets
Set transaction states
Share data between C++ components

Coding these C routines is described in “Write methods”.

Write methods

This section describes how to write methods for EAServer-specific APIs, including C routines, accessing SSL client certificates, and issuing intercomponent calls. A C++ method signature must use the return types and parameter datatypes described in “Supported datatypes”. To implement any of the features that require EAServer C routines, you must include jagpublic.h and implement the methods for each feature as follows:

Handling Errors

Use user-defined or CORBA system exceptions to handle errors. See “Error handling” for more information about system and user-defined exceptions.
Caching Connections to Third-Tier Database Servers

You can use a connection cache to improve performance when connecting to database servers. See “Using Connection Manager routines in C, C++, and ActiveX components” for more information.
Returning Result Sets

A component method can return row results to the client. See “Returning result sets” for more information.
Managing explicit OTS transactions

You can explicitly to manage OTS transactions from your component.
Setting Transaction State

Methods in a transactional component should call one of the transaction primitive routines to set the transaction state before returning. See “Methods that set transactional state” for more information.
Sharing Data Between C++ Components

EAServer provides C routines that allow components within the same package to share data with each other. See “Share data between C or C++ components” for more information.

Returning result sets

You can return result sets by:

Using the C API as described in “Sending result sets from a C or C++ component”. The component method that returns a result set or result sets must return a null pointer in place of the TabularResults::ResultSet or TabularResults::ResultSets pointer. For example:
```
return NULL;
```
See “Sending result sets from a C or C++ component” for more information.
Returning a pointer to an initialized TabularResults::ResultSet or TabularResults::ResultSets object.

Error handling

Handle errors by:

Writing detailed error descriptions to the server log file using JagLog.
Coding one of these tasks:
1. If the component is transactional, call JagDisallowCommit or JagRollbackWork (or you can throw the CORBA::TRANSACTION_ROLLEDBACK exception instead of calling JagRollbackWork).
2. Throw a CORBA system or user-defined IDL exception to be raised by the client stub. See “Handling exceptions” for more information.

For more information about these methods, see Chapter 5, “C Routines Reference,” in the EAServer API Reference.

Managing explicit OTS transactions

You can code components (and clients) to initiate and complete transactions using the OTS (Object Transaction Service) CosTransactions::Current or CosTransactions::TransactionFactory interfaces.

In order to use OTS, you must enable EAServer to use the OTS/XA transaction coordinator. See Chapter 3, “Creating and Configuring Servers,” in the EAServer System Administration Guide for more information.

To use the functionality of these interfaces, include CosTransactions.hpp in your source file.

To explicitly use transactions in a component or client, use the CosTransactions::Current interface to perform these tasks.

Task	Call this method	Catch these exceptions
Start a transaction.	begin	SubtransactionsUnavailable
Temporarily stop a transaction.	suspend	None
Resume a suspended transaction.	resume	InvalidControl
Commit a transaction.	commit	NoTransaction, HeuristicMixed, HeuristicHazard
Roll back a transaction.	rollback	NoTransaction
Make the only possible outcome of the transaction a rollback.	rollback_only	NoTransaction
Roll back a transaction after a specified amount of time has elapsed without any response.	set_timeout	None
Retrieve a transaction’s status.	get_status	None
Retrieve a transaction’s name. Use this method when you need to debug transactions.	get_transaction_name	None

Using factories

The TransactionFactory interface is included in EAServer only to maintain compatibility with the CORBA OTS specification—Sybase recommends that you use the CosTransactions::Current interface to create explicit transactions.

Sybase recommends that you use suspend with caution so as not to conflict with the EAServer component model. For example, do not use suspend to take control of a transaction that it does not control.

Initializing the ORB

To initialize the ORB and retrieve a reference to the CosTransactions::Current interface, specify the TransactionCurrent ObjectId, which identifies the CosTransactions::Current interface, to the resolve_initial_references method, and narrow it (using the _narrow method) to the CosTransactions::Current interface. Use the is_nil method to verify that the reference to the CosTransactions::Current interface is valid.

For clients

The following code fragment shows how to initialize the ORB from a client. ORB_init must take the argumentList array that specifies the ORBNameServiceURL parameter. You can also set the ORBNameServiceURL using the JAG_NAMESERVICEURL environment variable.

int  argumentCnt = 1;
char *argumentList[] = {
   { "-ORBNameServiceURL iiop://<hostnamehere>:9000" },
   { "" }
   };
try {

  CORBA::ORB_var  orb = CORBA::ORB_init(argumentCnt,     argumentList, 0);
  cerr << "Orb init" << endl;

  CORBA::Object_var  crntObj =
    orb->resolve_initial_references
      ("TransactionCurrent");
  CosTransactions::Current_var CurrentIntf =
    CosTransactions::Current::_narrow(crntObj);
  if( CORBA::is_nil(CurrentIntf) )
  {
    cerr << "Error getting Current" << endl;
    exit(-1);
  }
cerr << "Got Current" << endl;

For components

The following code fragment shows how to initialize the ORB from a component. ORB_init does not need to take any parameters.

orb = CORBA::ORB_init(argumentCnt, NULL, 0);
cerr << "Orb init" << endl;

CORBA::Object_var  crntObj =
  orb->resolve_initial_references
    ("TransactionCurrent");
CurrentIntf =   CosTransactions::Current::_narrow(crntObj);
if( CORBA::is_nil(CurrentIntf) )
{
  cerr << "Error getting Current" << endl;
  /* could be due to:
  **   1. Component not BeanManaged/OTS Style
  **   2. Already in a Txn
  ** 3. not running under OTS
  */
  return CS_FAIL;
}
cerr << "Got Current" << endl;

Calling CosTransactions::Current interface methods

After retrieving a reference to the CosTransactions::Current interface, you can call any of the CosTransactions::Current methods on the CosTransactions::Current reference. After executing the begin method, execute the database operations you want to include in the transaction. Depending on whether the database operations succeed or fail, you can execute other appropriate methods, such as commit, rollback, or rollback_only. This code fragment shows how to begin a transaction and commit or roll it back depending on the return codes received from the databases.

CurrentIntf->begin();
ret = JagCmGetConnection( &cache,
    (SQLCHAR *) USERID, (SQLCHAR *) PASSWD,
    (SQLCHAR *) xaresource, (SQLCHAR *) "CTLIB_110",
    (void*) &conn, JAG_CM_UNUSED );

if (ret != CS_SUCCEED) {
  cerr << "Error getting connection" << endl;
  CurrentInt->rollback();
}

CurrentIntf->commit(CS_FALSE);

Executing tasks outside of a transaction

To execute a method outside of a transaction, you can write the code to perform either:

Execute the method before beginning a transaction, or
Temporarily stop and start execution of the transaction.

Execute tasks outside of a transaction using the suspend and resume methods

Execute suspend to temporarily stop execution of the transaction.
Execute the tasks.
Execute resume to restart the execution of the transaction from where it stopped.

This code fragment shows how to execute tasks outside of a transaction. The suspend method returns the control context. You specify the control context when you use the resume method to restart the transaction. Catch the InvalidControl exception, which may be raised when a control context is out of scope (and not null).

sus_ctrl = CurrentIntf->suspend();

/* The following method is not in the transaction */
component1->method2();

CurrentIntf->resume(sus_ctrl);
/* The following methods are invoked 
in the transaction */
	component2->method1();

CurrentIntf->commit(CS_FALSE);

}
catch(CosTransactions::SubtransactionsUnavailable 
  &ex ) 
{
    cerr << "Exception: SubTxnUnavailable " <<       ex._jagExceptionCode << endl;
}
catch(CosTransactions::NoTransaction &ex )
{
    cerr << "Exception: NoTransaction  " <<       ex._jagExceptionCode << endl;
}
catch(CosTransactions::InvalidControl &ex )
{
    cerr << "Exception: InvalidCtrol  " <<       ex._jagExceptionCode << endl;
}
catch(...)
{
    cerr << "Caught Unexpected exception" << endl;
    exit(-1);
}

Exceptions

The CosTransactions module includes these exceptions:

SubtransactionsUnavailable – raised when the client thread already has an associated transaction and the transaction coordinator does not support nested transactions.
NoTransaction – raised when there is no transaction associated with the client thread.
InvalidControl – raised when the specified control is not null and not within the scope of the client thread.
Inactive – raised when a method such as rollback_only is executed on a transaction has already been prepared.
InvalidTransaction – raised when a request carries an invalid transaction context, such as if an error occurred when registering a resource.
TransactionRequired – raised when a request carries a null transaction context but required an active transaction. For example, this could occur when a component specifies the Mandatory attribute.
Unavailable – raised when the requested object cannot be returned because OTS/XA transaction coordinator restricts the availability of the object.
TransactionRolledBack – raised when a transaction is marked to roll back or has already been rolled back.

Heuristic exceptions

A heuristic decision is a decision to commit or roll back updates that one or more participants in a transaction make without waiting for the consensus decision from the transaction coordinator. These types of commits and rollbacks are also called heuristic commits and heuristic rollbacks. When a heuristic commit or rollback is made, the transaction can become inconsistent. Therefore, a heuristic commit or rollback is made only in unusual circumstances such as communication failures. When the System Administrator issues a heuristic commit or rollback from EAServer Manager, a heuristic exception is raised.

HeuristicMixed – Raised when a heuristic decision is made and some relevant updates are committed and others are rolled back.
HeuristicHazard – Raised when a heuristic decision may have been made, when not all of the conditions of all relevant updates is known, and for those updates whose condition is known, either all of them were committed or rolled back.
HeuristicRollback – Raised when a heuristic decision to roll back all of a transaction’s relevant updates has been made.
HeuristicCommit – Raised when a heuristic decision to commit all of a transaction’s relevant updates has been made.

Accessing SSL client certificates

Clients can connect to a secure IIOP port using an SSL client certificate. You can issue intercomponent calls to the built-in CtsSecurity/SessionInfo component to retrieve the client certificate data. See Chapter 6, “Using SSL in C++ Clients,” in the EAServer Security Administration and Programming guide for more information about retrieving SSL information and issuing intercomponent calls using SSL.

Issuing intercomponent calls

To invoke other components, instantiate a stub for the second component, then use the stub to invoke methods on the component.

You must use a stub to issue intercomponent calls. If you call methods in another C++ component directly, EAServer features such as transactions and security will not work.

To invoke methods in other components, create an ORB instance to obtain object references to other components and invoke methods on the object references. You obtain object references for other components on the same server by invoking string_to_object with the IOR string specified as Package/Component. For example:

CORBA::Object_var obj = 
    orb->string_to_object("MyPackage/MyComponent");
MyModule::MyInterface_var i =
   MyModule::MyInterface::_narrow(obj);

When making intercomponent calls using string_to_object, the user name of the client that executed the component is automatically used for authorization checking. string_to_object returns an instance running on the same server if the component is locally installed; otherwise, it attempts to resolve a remote instance using the naming server.

To components on a non-EAServer ORB

Your component may need to invoke methods on a component hosted by another vendor’s CORBA server-side ORB. Sybase recommends that C++ components use the EAServer client-side ORB for all IIOP connections made from EAServer components. See “Connecting to third-party ORBs using the EAServer client ORB” for more information.