Chapter 16 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 Jaguar 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 Jaguar 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 Jaguar-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 Jaguar 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 Jaguar 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
  Jaguar 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:

1. Writing detailed error descriptions to the server log file using JagLog.
2. 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 the Jaguar CTS 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 the Jaguar server to use the OTS/XA transaction coordinator. See the Jaguar CTS 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.

Using factories

The TransactionFactory interface is included in Jaguar 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 Jaguar 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.

To execute tasks outside of a transaction using the suspend and resume methods:

1. Execute suspend to temporarily stop execution of the transaction.
   
   
2. Execute the tasks.
   
   
3. 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 Jaguar 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, including:

• The distinguished SSL user name
• The client certificate fingerprint (MD5 message digest)
• The client certificate data
• The chain of issuing certificates

This component implements the CtsSecurity::SessionInfo IDL interface. HTML documentation is available for the interface in the html/ir subdirectory of your Jaguar installation. You can view it by loading the main Jaguar HTML page, then clicking the "Interface Repository" link.

   The CtsSecurity::UserCredentials interface is deprecated The CtsSecurity::UserCredentials interface, which is implemented by the CtsSecurity/UserCredentials component, has been replaced by the CtsSecurity::SessionInfo interface, which provides additional functionality such as certificate parsing. Jaguar supports the CtsSecurity::UserCredentials interface for backwards compatibility. Please use the interface CtsSecurity::SessionInfo if developing new components.

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, Jaguar 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.

To instantiate components hosted by another Jaguar server, you must use the techniques described in Chapter 17, "Creating CORBA C++ Clients"

Using SSL

C++ components (and PowerBuilder NVOs) can make intercomponent calls across different servers using SSL in much the same way as any other C++ client. However, be aware of these considerations:

• The SSLServiceProvider interface is not available to components. Instead set ORB-level SSL properties to initiate server-to-server intercomponent calls using SSL.
• SSL callbacks are not available for components, since components are not interactive. Instead, you can create SSL properties in the All Properties tab for a component or package to store the required SSL properties; you can use any other appropriate method to store SSL properties, such as hard-coding SSL properties in the component. For example, you can specify the quality of protection as the following:
  

  com.sybase.jaguar.component.mysslqop=sybpks_intl

  
  
  These properties can be obtained during component initialization and can be used to initialize the ORB for making intercomponent calls using SSL. To retrieve these components, use the lookup method in the Jaguar::Repository interface.
  
• Components use $JAGUAR/Repository/Security path to locate certificates and key database files. That is, components making intercomponent calls use the Jaguar server's certificate and key database managed by the Jaguar Security Manager.

To components on a non-Jaguar 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 Jaguar client-side ORB for all IIOP connections made from Jaguar components. See "Connecting to third-party ORBs using the Jaguar client ORB" for more information.

Copyright © 2000 Sybase, Inc. All rights reserved.