Introduction

This article is intended to help developers using TXSeries Encina begin writing J2EE applications that use IBM's WebSphere platform for their existing Encina applications. Much of the information presented in this article can serve as a general guide for developing J2EE applications using a J2EE connector for an enterprise information system. However, after some background on J2EE Connector Architecture and a review of the task at hand, we will specifically walk through various programming and configuration techniques for developing and deploying applications using the Encina J2EE Connector, introduced in TXSeries V5.1.

This article assumes familiarity with Java™ programming and object-oriented programming concepts, J2EE, and TXSeries Encina. A sample enterprise application, provided in a download file, will be used for illustration purposes throughout this article. (The README packaged with the application gives detailed instructions on how to get the application running.) To run the examples and sample code, you will need:

• TXSeries Encina 5.1 installed, with an Encina cell and node configured. Make sure the DE-Light Gateway and DE-Light Client components are installed.
• WebSphere Application Server V5.1, IBM's J2EE application server environment which supports the J2EE Connector Architecture.

Back to top

J2EE and Encina

This section presents some background information about the architecture and interfaces that enable the J2EE and Encina environments to interact.

J2EE Connectors

The J2EE Connector (J2C) Architecture specification standardizes the interaction of J2EE application servers and enterprise information systems (EIS). Each EIS vendor provides a resource adapter (RA) which is plugged into a J2C-enabled application server. These resource adapters facilitate the communication between the application servers and EISs. The specification also defines a set of system-level contracts between the J2EE application server and the RAs for connection, transaction, and security management. The resource adapter provides an implementation of a standard client API called the Common Client Interface (CCI). Application programmers will use the CCI to write J2EE applications that communicate with the EIS through the resource adapter.

Common Client Interface

The CCI defines a set of interfaces for:

• Connection
• Transaction
• Interaction
• Data representation
• Meta data
• Exceptions and warnings.

The application programming model of a J2EE application component accessing an EIS through the resource adapter generally works as follows:

1. Obtain a handle to the ConnectionFactory instance by looking it up in the JNDI namespace.
2. Get a connection to the EIS by using the getConnection methods of the ConnectionFactory instance. You can specify the properties of the connection (such as, UserName and Password) by creating an implementation instance of ConnectionSpec (for example, ConnectionSpecImp) and passing it as an argument to the getConnection method.
3. If you wish to handle the transaction demarcation in the application component, then use the getLocalTransaction method of the Connection instance to obtain an instance of LocalTransaction. Use the begin, commit, and rollback methods on the LocalTransaction instance as appropriate.
4. Specify the properties of the interaction (such as, FunctionName, serverName, and so on) by creating an instance of the implementation of InteractionSpec (for example, InteractionSpecImpl) and set the properties using the appropriate setter methods.
5. Create an interaction by calling the createInteraction method of the Connection instance.
6. Create an input object of type Record and set the input parameters to the EIS function using the appropriate setter methods. Also create an output object of the same type.
7. Call the EIS function by invoking the execute method on the instance of Interaction. Pass the instance of InteractionSpec, created above, along with the input and output records.
8. Retrieve the result of the EIS function call by calling the appropriate getter methods on the output record.
9. Close the interaction and then the connection by the calling the close method on instances of Interaction and Connection.

The example in the Sample session bean section demonstrates this. See the J2EE Connector Architecture Specification for more information.

The DE-Light Gateway

Encina's J2EE Connector is built on top of the DE-Light Gateway, a separate server provided with Encina that resides on a DCE client machine. The gateway enables Java applications outside the DCE cell to communicate with DCE/Encina servers. DE-Light Java client applications can contact the DE-Light gateway(s) using HTTP/S or TCP/IP protocols. The gateway converts the Java client calls into DCE RPC/Encina TRPC calls, routes them to the appropriate DCE/Encina server, and returns the result to the Java clients. (See Figure 1.)

Encina Connector

Encina Connector is an outbound J2C resource adapter providing access to RPCs of Encina servers. Since the resource adapter is only outbound, only communication from J2EE clients to Encina servers (and not vice-versa) is possible. Encina Connector complies with the J2EE Connector Architecture Specification, Version 1.0. It is built on top of the DE-Light Java client library. The resource adapter serializes the data and sends it via TCP, HTTP, or HTTPS to the DE-Light Gateway, which uses RPCs to send and receive data from the Encina Servers. The gateway then passes the data back to the resource adapter. This means that you can now use the large installed base of proven applications on Encina within your J2EE components.

In this article, we discuss only the managed environment where Encina Connector is deployed in WebSphere Application Server. This environment enables Web applications to call the functions provided by Encina servers, and also leverage the transaction, security, and connection management provided by the J2EE application server. An overview of the non-managed environment, where the application clients directly use the resource adapter to access the Encina Servers is given in Appendix B.

Encina Connector is packaged as a resource archive (RAR) file called encconn.rar. This RAR file contains:

• encconn.jar -- archive file that provides classes implementing J2C functionality
• delight11.jar -- provides DE-Light classes
• ra.xml -- the deployment descriptor file.

Back to top

Developing the J2C application

This section describes how to develop J2EE applications using Encina's J2EE Connector and CCI, explaining the various aspects of programming that should be considered when writing an application using, for example, Encina Connector exception handling, transaction handling, and so on. A sample application illustrates the mechanisms discussed.

Encina Connector's CCI

Encina Connector supports the CCI of the J2C specification (with which J2EE clients can communicate with the Encina Connector). The Encina Connector, in turn, interacts with Encina servers. The only Encina Connector-specific classes from a programmer's perspective are DELConnConnectionSpec and DELConnInteractionSpec:

• com.ibm.transarc.connection.delight.DELConnConnectionSpec
  DELConnConnectionSpec specifies DCE authentication data and default parameters for RPCs issued on a connection. It is used when the client obtains a connection handle for an Encina Connector instance. With this class, the application specifies connection parameters. This class is usually used in a non-managed environment, when an application uses its own authentication mechanism, or when it needs to change transaction timeout or security used between DE-Light gateway and Encina servers from its default value. Some of the properties that you can set using this bean are: runUnathenticated, dceSecurityLevel, transactionTimeout, userName, password and traceLevel.
• com.ibm.transarc.connection.delight.DELConnInteractionSpec
  DELConnInteractionSpec specifies the RPC to be issued, the server where the RPC should be executed, and some other DCE-specific parameters of the issued RPC. The class also contains an RPC return value. Some of the properties that can be set using this bean are: rpcName, serverName, lastCall, rpcReturnValue and dceSecurityLevel.

The connector relies on the drpcidl compiler, a DE-Light utility, to create a Java bean class from the Encina TIDL/DCE IDL (Interface Definition Language) files. The bean implements a Record interface and is used as an argument to the execute method of the Interaction interface.

Sample Application

Having looked at the Encina Connector's CCI, let us now start developing a simple application that will demonstrate the various aspects of client programming. The example used here accesses an Encina Monitor Application Server (MAS) which inserts, updates, reads, and deletes employee information from data storage. (Since the focus of this article is only client programming, the MAS methods here do nothing but return an RPC success or failure status.) Part of the tidl interface of the MAS, simpleEmp.tidl, is shown in the listing below:

Listing 1

/* The empRecord structure is defined in this header file */
#include "simpEmp.h"

[transactional] void recordInsert (
            [in,out]   empRecord    *ptr);

[transactional] void recordUpdate (
            [in,out]   empRecord    *ptr);

[nontransactional] void recordRead (
            [in,out]   empRecord    *ptr);

[nontransactional] void recordDelete (
            [in,out]   empRecord    *ptr);

As the Encina connector is based on the DE-Light Java client API, only those IDL data types supported by DE-Light are supported by the connector. (See Resources for the Encina DE-Light Programming Guide, which contains a list of supported IDL data types.) We will see in the following sections how to develop a J2C application for the MAS which exports this interface.

Generating the Record structure

The J2C application exchanges data with the EIS using a data structure called Record. Encina provides a tool to generate the implementation of the Record interface (of CCI) from the IDL/TIDL interface called the drpcidl compiler. The beans generated by the drpcidl command follow the JavaBean specification. The compiler generates a method for each supported remote procedure defined in the interface and properties for the arguments of the RPCs. The method is named after the RPC it represents.

The drpcidl command also generates a class for each complex data type used in a procedure, such as structures and unions, with methods to get and set each field in the structure. For arrays, additional methods are also generated to store and retrieve single values in the array; these methods take an array index as an argument. Note that if you want to generate a Java String data type for char arrays, you should use the [string] qualifier when defining the data type in the TIDL interface. Otherwise, the generated class will treat it as a normal array of type "char".

Additionally, BeanInfo files are generated for all the class files generated that provide a mechanism for exposing information about the generated methods and structures. Using the BeanInfo file, development tools can determine the properties and behaviors (events and methods) of any Bean component, and enable the developer to establish relationships between components.

To generate the Record and the supporting classes for the TIDL interface of the sample application, you will first need to have a .tacf file for the tidl interface. The simpleEmp.tacf file is shown below. The TACF and TIDL files must all be in the same directory.

Listing 2

[implicit_handle (mon_handle_t handle)]

interface simpleEmp
{
}

The drpcidl command options used for the sample application are:

/opt/encina/bin/drpcidl -I /opt/encina/include -I . -stub jca -package com.ibm.EncConn.sample simpleEmp.tidl

where:

• -stub jca -- is used to generate a Record class for J2C applications.
• -package -- is used to specify the package name of the generated classes.

The classes generated by the drpcidl command, for the TIDL interface, simpleEmp.tidl are:

• simpleEmp.java
simpleEmpBeanInfo.java
  -- the Record class and its BeanInfo.
  
  
• simpleEmp_empRecord.java
simpleEmp_empRecordBeanInfo.java
  -- the class for the empRecord structure used in the TIDL interface and its BeanInfo.

Refer to the EmployeeSample.ear file in the download file for the complete listing of the generated classes.

Type the command /opt/encina/bin/drpcidl on the command prompt, to see details on other options of the drpcidl compiler.

Developing an enterprise application

Encina Connector's RAR file, encconn.rar, can be deployed into WebSphere Application Server and thus enable Web applications to use functions provided by Encina servers. Using Encina Connector's CCI (packaged in the RAR file) and the generated Record class, any Java artifact can communicate with TXSeries Encina. However, developing enterprise beans to use the CCI to communicate with Encina, and then developing Web clients or Java applications to invoke these enterprise beans, is a better approach; in this case, the EJB container will handle connection, transaction, and security management. You can also have remote methods corresponding to each of the procedures in the TIDL interface. Part of the remote interface of the session bean of the sample application is shown in the listing below:

Listing 3

/**
 * Remote interface for Enterprise Bean: EmployeeSession. Note that there is a method 
 * corresponding to each of the procedure in the TIDL interface.
 */
public interface EmployeeSession extends javax.ejb.EJBObject {
	public simpleEmp_empRecord recordInsert(simpleEmp_empRecord empRecord)
		throws java.rmi.RemoteException;
	public simpleEmp_empRecord recordUpdate(simpleEmp_empRecord empRecord)
		throws java.rmi.RemoteException;

Sample session bean

WebSphere Studio Application Developer Version 5.1 (hereafter referred to as Application Developer) was used for the development of the sample enterprise application and all the steps are in respect to this development environment.

Before we start coding our session bean in the WebSphere Studio environment, perform these steps:

1. Import the Encina J2C resource adapter, encconn.rar, into a connector project.
2. Create an enterprise application.
3. Create an EJB project within the enterprise application and create a session bean. The sample application has a stateful session bean.
4. Add the connector project created above to the Java build path of the EJB Module (in Application Developer, select Properties => Java build path => projects, and select the connector project).
5. Import the Java files generated by drpcidl command into the same project as the session bean.

You can now add the business logic to the session bean. The sample bean follows the model explained in the Common Client Interface section. A portion of the enterprise bean, along with explanatory comments, is shown in Listing 4. See the sample application in the download file for the complete code.

Listing 4

private DELConnInteractionSpec iSpec = null;
.....
private void initialize() throws NamingException {
		if(connectionFactory = null) {
			javax.naming.Context nc = new javax.naming.InitialContext();
			// Lookup the connection factory in the JNDI namespace
			connectionFactory =
				(ConnectionFactory) nc.lookup(
				"java:comp/env/Encina/ConnectionFactory");
.....
/* This method takes the employee record an input parameter and
 * returns another employee record with the data filled in by the MAS. */
public simpleEmp_empRecord recordInsert(simpleEmp_empRecord empRecord){
	Connection connection = null;
	Interaction interaction = null;
	//Create an instance of the Record class generated by drpcidl
	simpleEmp record = new simpleEmp();	
	try {
		//Get a connection
		connection = connectionFactory.getConnection();
		//Obtain an instance of interaction
		interaction = connection.createInteraction();
		//Set in the input parameter to the RPC, recordInsert
		record.set_recordInsert_ptr(empRecord);
		//Set the RPC name
		iSpec.setRpcName("recordInsert");
		//Execute the RPC. Here we have used the same instance of Record of 
		//input and output.
		interaction.execute(iSpec, record, record);
		//Retrieve the output of the RPC from the output Record instance
		empRecord = record.get_recordInsert_ptr();
	} catch (ResourceException e) {
			/*In case of any Resource expection, make sure the transaction
			* is rolled back */
			getSessionContext().setRollbackOnly();
			//Obtain the expection message
			setAbortReason("Error String : " + e.toString());
			empRecord.set_status(1);
	}
	finally {
			try {
				/*Close the connection. Note that the interaction is not
				* closed as it just an empty call in case of Encina 
				* connector */
				if (connection != null)
					connection.close();
			}catch (ResourceException e) {
				//Ignore exceptions during close calls.
			}
	} 
	return empRecord;
}

Once the actual bean is ready:

6. Promote the relevant methods to the remote interface.
7. Add a resource reference of type javax.resource.cci.ConnectionFactory to the EJB deployment descriptor.
8. Finally, generate the deployment code.

Transaction handling

The current implementation of Encina Connector only supports a local transaction management contract. This enables the J2EE application server to manage Encina's local transactions transparently to an application component. Encina notifies the J2EE application server of the local transaction-related events; namely, begin, commit, and rollback.

The implication of only local transaction support is that only a flat transaction model (one-phase commit) is supported. A scenario in which, for example, an EJB needs to interact with Encina plus another resource manager that does not support two-phase commit (2PC) within a single transactional context, is not supported. However, if an EJB component needs to interact with Encina and multiple other resource managers that do support 2PC (such as a DB2 database) within a single transactional context, WebSphere Application Server's last participant support can be used to handle such a scenario. Hence, you can make calls to Encina Connector and any number of other 2PC compliant resource managers within a single transactional context -- but not to multiple resource managers that do not support 2PC.

The RPCs defined in the TIDL interface can be transactional or non-transactional. For all the transactional RPCs, you can use either container-managed transaction demarcation or component-managed transaction demarcation. Using container-managed transactions is recommended, as the J2EE application server will handle the transaction management. Also, when you want to make connections to Encina and another XA compliant resource manager within a single transactional context, container-managed transactions must be used. In the sample application, container-managed transaction demarcations are used. The methods in the remote interface of the enterprise bean corresponding to the transactional RPCs of the MAS have been marked with container-managed transaction type REQUIRED in the deployment descriptor of the enterprise bean.

Exception handling

ResourceException is the root of the exception hierarchy for the system contracts and for CCI. Encina Connector's implementation of ResourceException provides a string describing the error and a reference to another exception, which may be the lower-level problem that caused the ResourceException.

The error message can be retrieved by using the getMessage() method of the exception. The toString() method will return the error message along with a reference to another exception. For a RPC, Encina specific error codes are translated internally and the corresponding error messages are returned as the message of the exception (error codes cannot be directly retrieved from the exception). In case of Encina application (MAS-specific) errors, the message of the exception will contain the abort format and the application specific error code as part of the error message, provided these are set in the MAS. These error codes are particularly helpful when the MAS interacts with other resource managers (such as SFS or DB2), in which case the MAS can obtain the abort code when a transaction aborts due to the resource managers. These abort codes can thus be propagated to the J2EE client through ResourceException. (See the sample application in the download file to see how to set the abort format and application-specific error codes.)

Example of an Encina system specific error:
When we try to make a RPC via the Encina Connector and the MAS exporting this interface has been stopped, a ResourceException will occur:

• The e.getMessage() method will return:

  A DE-Light exception occurred.: Gateway could not create binding for RPC

• The e.toString() method will return:

  javax.resource.spi.EISSystemException: A DE-Light exception occurred.: Gateway could not create binding for RPC

Example of an application specific error:
When a transaction gets aborted in the sample application for an application-specific reason, a ResourceException will occur:

• The e.getMessage() method will return:

  A DE-Light exception occurred.: Untranslated server abort reason: uuid 9c242f60-ecba-11d0-8681-00609731a847 code 999

• The e.toString() method will return:

  javax.resource.spi.EISSystemException: A DE-Light exception occurred.: Untranslated server abort reason: uuid 9c242f60-ecba-11d0-8681-00609731a847 code 999

  The uuid corresponds to the abort format UUID and the code corresponds to the application specific error code.

ResourceWarning is not supported by Encina Connector.

The client application

We have seen how to develop a session bean interface for an Encina server using Encina Connector. Based on your business requirements, you can now develop Web applications or Java client applications that access these session beans. The sample application contains a servlet that accesses the session bean. We create an object of type simpleEmp_empRecord in the servlet, and then invoke remote methods of the session bean, as shown Listing 5. (Refer to the sample application in the download file for the complete listing.)

Listing 5

simpleEmp_empRecord empRecord = createRecord(empNo, empName, job, manager, dept);
javax.naming.Context nc = new javax.naming.InitialContext();
Object result= nc.lookup("java:comp/env/ejb/EmployeeSession");
EmployeeSessionHome empHome= (EmployeeSessionHome) PortableRemoteObject.narrow(
result, EmployeeSessionHome.class);
EmployeeSession emp = empHome.create();
							
switch(function){
case 1 : empRecord = emp.recordInsert(empRecord);
			  operation = "recordInsert";
			  break;

Back to top

Configuration and deployment

This section presents details on securing applications using various security mechanisms, including how to deploy the application in WebSphere Application Server V5.1, and configuring WebSphere Application Server to use various user registries when run in secured mode. Since the J2EE connector uses the underlying DE-Light Gateway, and the performance of the connector is influenced by the gateway's performance, pointers regarding configuration and performance tuning of the DE-Light Gateway are also included, along with information on problem determination and tracing.

Securing the application: Authentication

Authentication is performed to verify the identity of the user or principal. The sign-on to Encina can either be component-managed or container-managed. You will have to set the deployment descriptor element appropriately. For EJB components, for example, you can set res-auth to either "Application" or "Container".

• In the case of component-managed sign-on, the application component performs a programmatic sign-on by explicitly setting security parameters (userName and password) of the DELConnConnectionSpec, which is then used as an argument to getConnection.
• In container-managed sign-on, the application depends on the application server to manage the sign-on. In case of WebSphere Application Server, the application server obtains the authentication data from the J2C authentication alias (on the admin console, select Security => JAAS configuration => J2C Authentication Data) configured during deployment. The J2C authentication data provides the required security information. The application server always uses this authentication data for obtaining a connection to Encina.

The only authentication mechanism currently supported by Encina Connector is BASIC PASSWORD. As an implication, the userName and password (described above) will be sent in clear text from WebSphere Application Server to the DE-Light Gateway, unless Encina Connector and DE-Light Gateway are configured to use SSL and Encina Connector's security level is other than SEC NONE (1 in digital representation).

If you want to use container managed authentication, WebSphere Application Server supports the JAAS authentication framework, which is based on Pluggable Authentication Module (PAM) framework. It therefore lets you to plug in the appropriate authentication service to meet your security requirements. You can also choose to use the default Login Modules provided by WebSphere Application Server.

Encina applications typically use the DCE security registry to store user accounts and groups, and the DCE security service for authentication. The users of enterprise applications accessing Encina servers will be authenticated by the J2EE application server. You can either have a separate user registry for the application server, or a common user registry shared by both the J2EE application server and Encina (DCE). WebSphere Application Server supports LocalOS, LDAP and Custom user registries. (See Resources for WebSphere documentation on configuration of user registries.)

If you are using the DCE security registry and wish to share this user registry with WebSphere Application Server, DCE provides an option to migrate the user registry to IBM Directory Server (IBM's implementation of a standardized LDAP directory), which can then be accessed by both Encina (via DCE security service) and WebSphere Application Server. During the migration, a copy of the DCE registry database is stored and maintained in the LDAP directory where it is available to other services for providing authentication and authorization services. The DCE Security Registry and LDAP Integration Guide (see Resources) explains how DCE-related objects from the registry database are stored in the LDAP directory; user-defined Extended Registry Attributes (ERA) are stored in the LDAP directory as binary objects in a separate ERA structural object.

Securing the application: Authorization

Authorization checking is performed to ensure that a user or principal has access to a resource. Authorization checking can be performed by Encina or by the J2EE application server or both. Encina relies on DCE security services for authorization checking. Access Control List (ACL) is set for the Encina servers and users/groups are given permissions accordingly.

Authorization checking can also be done at the J2EE application server. For example, an application server can let a user create a connection to Encina only if the principal is authorized to do so. Component developers can use either programmatic or declarative security to define authorization policies. Refer to the respective component specifications for details.

You can also choose to do authorization checking at both Encina and the J2EE application server. For example, in case of MAS and DCE servers, users are either given execute permission on all the methods in the interface or none at all. When you develop an enterprise bean for the TIDL/IDL interface, the access to the methods can be controlled at a more granular level. You can specify if a user has access to a particular method or not, either declaratively or programmatically. Of course, the finer authorization granularity can still be controlled in the server implementation of the RPCs, but it is essentially programmatic.

Using declarative security, you can define security roles in the assembly descriptor of the EJB Module and assign method permissions to each role. Users or groups can be associated with each security role during deployment. In the sample application, two security roles have been defined: manager and employee:

• Users/groups associated with the manager role are given access to all the methods of the session bean, namely, recordInsert, recordDelete, recordUpdate and recordRead.
• Users/groups associated with the employee role are given access only to recordRead and recordUpdate methods.

On the Encina end, you can check if that particular user/group is authorized to execute the methods of a given interface.

Securing the application: Secured communication

The communication between a J2EE client and WebSphere Application Server can be secured using SSL. The communication between the Encina Connector deployed in WebSphere Application Server and the DE-Light gateway can also be secured using SSL. During the deployment of the Encina Connector, you can specify the minimum security level that needs to be used for the connection between the connector and DE-Light Gateway. Note that if the DE-Light Gateway is not configured for HTTPS, the only valid DE-Light security levels are SEC_NONE (which uses no DE-Light security) or SEC_BEST. SEC_BEST resolves to SEC_NONE in this case. Using any other DE-Light security level without HTTPS and SSL results in an exception.

Secured RPC can be used between DE-Light gateway and Encina/DCE servers. The RPC protection level can be programmatically set for a connection or for an interaction using the setDceSecurityLevel(int) method of the DELConnConnectionSpec and DELConnInteractionSpec classes, respectively. Optionally, you can also set the DCE delegation level using the setDceDelegationType(int) method. To know what DCE security level and delegation constants are available, refer to Appendix A.

(See Resources for the DE-Light Programming Guide, which contains details on the available security levels and how to secure communication.)

Configuring the DE-Light gateway

You should prepare the DE-Light Gateway to receive requests from the Encina Connector, route the request to the appropriate Encina Server, and return the result back to the connector. You can either configure the DE-Light Gateway as an Encina toolkit server, or start it from a command line. On Windows®, there are graphical utilities available to aid in the creation and maintenance of the gateways. The drpcgwy command is used to start the gateway, the syntax of which is:

Listing 6

drpcgwy -n gateway_name -e protocol:[network_address][endpoint[,secure_endpoint]] 
-K SSL_keyring_file \ -m keyring_pasword -k keytab_file -p DCE_principal -A 
exclusive_authority -Z authorization -c Monitor_cell

The gateway can either be authenticated or unauthenticated. An authenticated gateway communicates with DCE and Encina servers as an authenticated principal. For Encina Connector to use SSL for secure communications with the DE-Light Gateway, the gateway must be protected with DE-Light security (which uses SSL). The gateway must have a public-private key pair and a signed certificate.

The gateway is told about the RPC/TRPC functions that are used by the clients through the IDL/TIDL files that must be explicitly loaded into a gateway. You can load these files at gateway startup or at any point during gateway operation. An administration utility called drpcadmin is provided to monitor the operations of the gateway, administer the IDL/TIDL interfaces, and to monitor the DE-Light gateway clients.

(See Resources for references to Encina documentation.

Deploying the application

The EJB Module, along with the Web application or the J2EE application client that you develop (packaged as an EAR), needs to be deployed on WebSphere Application Server. Application Developer provides a WebSphere Test Environment for deploying and testing your application before actually deploying it on a live WebSphere Application Server. The following steps outline how to deploy your application to WebSphere Application Server.

1. Enable security in WebSphere Application Server
   1. Configure the User Registry.
   2. Create the J2C Authentication alias. This is the information that will be sent to the Encina Connector as authentication information. Specify the alias name for userid and password. This is the user name and password that will be passed to the DE-Light Gateway for authentication, and therefore should be the DCE account information of a principal with "x" permission on the interface. In other words, on the Encina server side, you should have created a user account and modified the ACL of the interface to add execute permissions to this user.
   3. Enable WebSphere Application Server security. Select the appropriate authentication mechanism and user registry. Configure SSL if applicable.
   4. Save all the changes into the master configuration and restart WebSphere Application Server in secured mode.
   
   
2. Deploy the Encina Connector
   1. Start WebSphere Application Server and open the browser-based administrative console.
   2. Navigate to Resources => Resource Adapters and install the Encina Connector RAR file, encconn.rar. Accept the defaults during the resource adapter installation.
   3. Create a J2C connection factory by selecting Additional Properties of the connector created above:
      • Enter the JNDI name.
      • Set Authentication Preference to BASIC PASSWORD.
      • Select the appropriate J2C Authentication alias for Container/Component managed authentication alias.
      • Finally, select the appropriate Mapping-Configuration alias. DefaultPrincipalMapping maps all authenticated users into the user name/password pairs specified in the selected alias, and puts it into the Subject object, which is passed to the Encina Connector for authentication.
   4. In the connection factory that is created, navigate to Custom Properties and enter the security level and the DE-Light Gateway specification in the gatewaySpec field. (See Resources for DE-Light documentation containing details on security levels.) The format of gatewaySpec is :

      protocol:hostname[port_spec]
      where:

      • protocol is "tcp" or "http", depending on the protocol that the DE-Light gateway started with.
      • hostname is the name of the machine that the DE-Light gateway is started on.
      • port_spec is a port number.

      If secured http is used, specify http for the protocol, but specify two port numbers separated by a comma, one for unsecured communication and one for SSL secured communication. Usage of those two communication channels will depend on the security level selected. For example, http:machine.ibm.com[4913,4914].

   5. Optionally, change the connection pool properties of the J2C connection factory.
   6. Save the changes to the master configuration.
3. Deploy the Enterprise application
   See Resources for references on deploying an enterprise application to WebSphere Application Server. While deploying the application, make sure the following steps have been completed:
   1. Specify the path to both JAR files contained in Encina Connector's RAR in the Deploy EJBs Option Classpath field. Failure to enter the values correctly will result in a ClassNotFound error message during deployment.

      Resource Adapters are installed in the installedConnectors subdirectory, so if WebSphere Application Server was installed in the default directory, the entry will look something like this on Windows:
      C:\Program Files\WebSphere\AppServer\installedConnectors\encconn.rar\encconn.jar
C:\Program Files\WebSphere\AppServer\installedConnectors\encconn.rar\delight11.jar.

   2. If you have any security roles defined in your enterprise application, map security roles to users/groups.

Load balance and fail-over

In a managed environment, load balancing and performance tuning will have to be addressed for:

• The client application residing on WebSphere Application Server. (See Resources for WebSphere documentation.)
• The Encina servers. (See Resources. for the Encina Administration Guide Volume 1: Basic Administration.)
• The DE-Light Gateway (explained below).

Factors such as timeout values, thread pool specifications, and the number of client connections can affect the performance of a DE-Light Gateway. You can tune the DE-Light Gateway's performance by using environment variables and options with the drpcadmin and drpcgwy commands. The DRPC_GATEWAY_TUNING environment variable can be used to set some of the parameters for a DE-Light Gateway, such as thread pool size, maximum client connections, timeouts, and so on.

A good option for significantly enhancing performance is to define multiple gateway servers and load the interface(s) on all the gateway servers. The Encina Connector rotates among gateways specified in the gateway list (gatewaySpec property of the connection factory of the connector) to obtain connections. The first gateway in the list will be used to make the first connection. The next time a new connection is requested, the second gateway in the list is used, and so on, until connections have been created to all the gateways. Once this happens, the connector starts over from the first gateway server in the list. This mechanism also aids fail-over. If one gateway server goes down for some reason, you can still continue to make connections and, hence, transactions with the Encina servers via the remaining gateway servers.

If you are using multiple interfaces, another option is to distribute the interfaces on multiple gateway servers and define multiple connection factories for an instance of the Encina Connector in WebSphere Application Server. The gatewaySpec property of each connection factory will have a different value. In this case, the client will have to make sure it uses the right connection factory, depending on the IDL/TIDL it uses. You can use a combination of these two options to achieve both performance improvement and fail-over.

Tracing and debugging

It is possible to unearth problems with the application and the configuration by appropriately turning on the trace for Encina, WebSphere Application Server, and any programmatically set debug levels in the J2EE application.

Server side tracing
To enable tracing on a gateway server, you can use the drpcadmin command (or tkadmin). Some of the useful drpcadmin commands for tracing are :

• list trace -- to display the current trace specification for each component.
• trace specification -- to add a trace specification.
• query trace -- to display a component's trace mask.
• dump ringbuffer -- to dump the trace ring buffer to a file.

Client side tracing
To programmatically enable the DE-Light Java client trace, we can use the static method, setTraceLevel(int) of the DELConnConnectionSpec or DELConnInteractionSpec class to set the trace level at the connection or the interaction level. The table below describes what each trace level value corresponds to. The debug information is logged to stderr, which is redirected by WebSphere Application Server to the SystemErr.log file.

Back to top

Appendix A : Encina Connector interfaces and classes

The following is a list of the interfaces and classes that an Encina Connector application can use. The interfaces are not Encina Connector specific, but are implementations of the J2C specification of CCI. The only Encina specific classes from a programmer's perspective are DELConnConnectionSpec and DELConnInteractionSpec.

1. javax.resource.cci.ConnectionFactory

   Description: This is a J2C interface through which an application accesses an instance of Encina Connector. It should be used in a managed environment.

   Note on some of the methods :

   • Connection getConnection() throws ResourceException
     
     
   • Connection getConnection(DELConnConnectionSpec) throws ResourceException
     
     
   • ResourceAdapterMetaData getMetaData() throws ResourceException
     
     
   • RecordFactory getRecordFactory() throws ResourceException
     Current implementation of Encina Connector does not use RecordFactories, and therefore a call to this method will always throw a NotSupportedException.
   
   
2. javax.resource.cci.ResourceAdapterMetaData

   Description: This is a J2C interface which provides details of the current implementation of the Encina Connector resource adapter. This information is usually used by application build tools, not by the client applications themselves.

   Methods :

   • String getAdapterVersion()
     
     
   • String getAdapterVendorName()
     
     
   • String getAdapterName()
     
     
   • String getAdapterShortDescription()
     
     
   • String getSpecVersion()
     
     
   • String[] getInteractionSpecsSupported()
     Encina Connector returns an array with just one element, DELConnInteractionSpec.
     
     
   • boolean supportsExecuteWithInputAndOutputRecord()
     Current implementation of Encina Connector returns true.
     
     
   • boolean supportsExecuteWithInputRecordOnly()
     Current implementation of Encina Connector returns false.
     
     
   • boolean supportsLocalTransactionDemarcation()
     Current implementation of Encina Connector returns true.
   
   
3. javax.resource.cci.Connection

   Description: This is a J2C interface representing a connection handle to the Encina/DCE servers. It can be used in both managed and non-managed environments.

   Methods :

   • Interaction createInteraction() throws ResourceException
     
     
   • LocalTransaction getLocalTransaction() throws ResourceException
     
     
   • ConnectionMetaData getMetaData() throws ResourceException
     Current implementation of Encina Connector does not support this, and therefore a call to this method will always throw a NotSupportedException.
     
     
   • ResultSetInfo getResultSetInfo() throws ResourceException
     Current implementation of Encina Connector does not support this, and therefore a call to this method will always throw a NotSupportedException.
   
   
4. javax.resource.cci.LocalTransaction

   Description: This is a J2C interface for transaction demarcation on a corresponding connection. It can be used in both managed and non-managed environments.

   Methods :

   • void begin() throws ResourceException
     
     
   • void commit() throws ResourceException
     
     
   • void rollback() throws ResourceException
   
   
5. javax.resource.cci.Interaction

   Description: This is a J2C interface representing a handle for issuing RPCs. It can be used in both managed and non-managed environments.

   Methods :

   • void close() throws ResourceException
     Current Encina Connector implementation does not keep any local data, and therefore a call to close() method is an empty call.
     
     
   • Connection getConnection()
     
     
   • boolean execute(DELConnInteractionSpec, Record, Record) throws ResourceException
     
     
   • Record execute(DELConnInteractionSpec, Record) throws ResourceException
     Current Encina Connector implementation does not support this method.
     
     
   • ResourceWarning getWarnings() throws ResourceException
     Current implementation does not use Warnings(), and as a result this method is an empty call.
     
     
   • void clearWarnings() throws ResourceException
     Current implementation does not use Warnings(), and as a result this method is an empty call.
   
   
6. com.ibm.transarc.connection.delight.DELConnConnectionSpec

   Description: This class is the Encina implementation of the ConnectionSpec interface and an application uses it to specify connection parameters. It is usually used in a non-managed environment.

   Methods :

   • void setRunUnauthenticated(boolean)
boolean getRunUnauthenticated()
     Use these methods to make all calls on this connection unauthenticated. This means that all calls on this connection will be unauthenticated even if the application server has authenticated context for them. Note that these calls will be unauthenticated from the DE-Light gateway point of view; the authentication context which the gateway will use to access DCE/Encina servers will depend on the configuration of the gateway. When the DE-Light gateway is started with the -d option, such calls are passed to DCE/Encina servers in a security context of the gateway principal; otherwise, they are passed in unauthenticated security context.
     
     
   • void setDceSecurityLevel(int)
int getDceSecurityLevel()
     Use these methods to set/get DCE security level used between DE-Light gateway and Encina/DCE servers. The default value is DRPC_DCE_PROTECT_DEFAULT (digital value 0) and is usually good enough. But, depending on the reliability of the connection between the gateway and the server, the application may change its value.
     
     
   • void setDceDelegationType(int)
int getDceDelegationType()
     Use these methods to set/get DCE Delegation type used between DE-Light gateway and Encina/DCE servers. It should be used along with dceSecurityLevel property.
     
     
   • void setTransactionTimeout(int)
int getTransactionTimeout()
     Use these methods to set/get transaction timeout on DE-Light gateway for transactions started on this connection. Note that Transaction timeout is set up on the DE-Light gateway and there are no callbacks from the gateway back into the application server. This means that the application will notice transaction timeout only during a call to an Encina/DCE server in the timed out transaction context, or during this transaction resolution.
     
     
   • void setUserName(String)
     Use this method to set the user name (DCE credentials) that is used for RPC calls to Encina/DCE servers.
     
     
   • void setPassword()
     Use this method to set the password (DCE credentials) that is used for RPC calls to Encina/DCE servers.
     
     
   • static void setTraceLevel(int)
     Use this method to cause the DE-Light Java client trace to be turned on immediately with the corresponding trace level.
     
     

   Constants : The following are the integer constants defined.

   • DRPC_DCE_PROTECT_DEFAULT -- Use the rpc_c_protect_level_default DCE security level for communications between the gateway and the server.
   • DRPC_DCE_PROTECT_NONE -- Equivalent to rpc_c_protect_level_none.
   • DRPC_DCE_PROTECT_CONNECT -- Equivalent to rpc_c_protect_level_connect.
   • DRPC_DCE_PROTECT_CALL -- Equivalent to rpc_c_protect_level_call.
   • DRPC_DCE_PROTECT_PACKET -- Equivalent to rpc_c_protect_level_packet.
   • DRPC_DCE_PROTECT_PKT_INTEG -- Equivalent to rpc_c_protect_level_pkt_integ.
   • DRPC_DCE_PROTECT_PKT_PRIVACY -- Equivalent to rpc_c_protect_level_pkt_privacy.
   • DRPC_DCE_PROTECT_MAX_VALUE -- Use the highest DCE security level that is defined for communications between the gateway and the server. Currently, the maximum is packet privacy.
   • DRPC_DCE_DELEGATION_DEFAULT -- None, or the same delegation level as at the DE-Light Gateway.
   • DRPC_DCE_DELEGATION_NONE -- No delegation.
   • DRPC_DCE_DELEGATION_SIMPLE -- Impersonation delegation, or simple delegation.
   • DRPC_DCE_DELEGATION_TRACED -- Trace delegation.
   
   
7. com.ibm.transarc.connection.delight.DELConnInteractionSpec

   Description: This class is the Encina implementation of the InteractionSpec interface, and an application uses it to specify the RPC all to make. It is used in both managed and non-managed environments.

   Methods:

   • void setRpcName(String)
String getRpcName()
     Use these methods to set/get the RPC to be issued.
     
     
   • void setServerName(String)
String getServerName()
     Use these methods to set/get the server name, if explicit binding is used. This is always the case for plain DCE servers.
     
     
   • void setLastCall(boolean)
boolean getLastCall()
     Use these methods to specify if the RPC will commit the transaction in the same context in which this call is made.
     
     
   • Object getRpcReturnValue()
setRpcReturnValue(Object)
     Use this method to obtain the return value of the RPC when RPC is declared with return value.
     
     
   • void setDceSecurityLevel(int)
int getDceSecurityLevel()
     Use this method to set the DCE security level for this RPC call.
     
     
   • void setDceDelegationType(int)
int getDceDelegationType()
     Use these methods to set/get DCE Delegation type for this RPC all. It should be used along with dceSecurityLevel property.
     
     
   • void setTraceLevel(int)
     Use this method to cause DE-Light Java client trace to be turned on immediately with the corresponding trace level for this RPC.
     
     

   Constants:
   The constants available are the same as that of DELConnInteractionSpec but apply at the interaction level and not at the connection level.

   
   
8. com.ibm.transarc.connection.delight.DELConnManagedConnectionFactory

   Description: This class is the Encina implementation of the ManagedConnectionFactory interface. It is used only in non-managed environment.

   Methods:

   • Object createConnectionFactory() throws ResourceException
     
     
   • Object createConnectionFactory(ConnectionManager) throws ResourceException
     
     
   • void setGatewaySpec(String)
getGatewaySpec() - Use these methods to set/get the DE-Light gateway specification.
     
     
   • void setSecurity(int)
int getSecurity() - Use this method to set/get the security level between Encina Connector and DE-Light gateway.

   Constants:

   • SEC_NONE -- Use no DE-Light security.
   • SEC_BEST -- Use the highest DE-Light security level available, even if that means no security.
   • SEC_INHERIT -- Continuously inherit the DE-Light security level based on the DCE security level in use between the gateway and the server.
   • SEC_CIRCUIT_AUTH -- Use SSL security for privacy and integrity protection only on the initial request (while establishing the connection).
   • SEC_PACKET_INTEGRITY -- Use SSL security for privacy and integrity protection on the initial request (while establishing the connection) and for integrity protection on all other requests.
   • SEC_PACKET_PRIVACY -- Use SSL security with a cipher key that is 40 bits or greater.
   • SEC_ENCRYPT -- Identical to SEC_PACKET_PRIVACY.
   • SEC_PACKET_PRIVACY_WORLD -- Use SSL security in the same way as SEC_PACKET_PRIVACY, using only ciphers exportable from the U.S.
   • SEC_PACKET_PRIVACY_US -- Use SSL security with a cipher key that is greater than 40 bits.
   • SEC_PACKET_PRIVACY_US_128 -- Use SSL security with a cipher key that is 128 bits or greater.
   • SEC_MAX_VALUE -- Use the highest SSL security level that is defined (currently this is 128 bits).
   
   

Back to top

Appendix B: Non-managed environment

Encina connector supports access to Encina from application clients inside or outside a J2EE application server. In a non-managed environment, the application client is responsible for managing connection pooling, authentication, and transaction demarcation.

To obtain connections in a non-managed environment, the application client must create and initialize an instance of DELConnManagedConnectionFactory class. It must then use this instance to retrieve an instance of a ConnectionFactory. For example:

Listing 7

DELConnManagedConnectionFactory mcf = new DELConnManagedConnectionFactory();
mcf.setGatewaySpec("http://hostname.com[4321]");
mcf.setSecurity(4);
javax.resource.cci.ConnectionFactory cf = mcf.createConnectionFactory();

For authentication, the authentication data is encapsulated in an instance of DELConnConnectionSpec. Other information like DCE security level and transaction timeout can also be specified using this class. For example,

Listing 8

DELConnConnectionSpec cSpec = new DELConnConnectionSpec();
cSpec.setUserName("username");
cSpec.setPassword("password");
cSpec.setDceSecurityLevel(DELConnConnectionSpec.DRPC_DCE_PROTECT_DEFAULT);
javax.resource.cci.Connection conn = cf.getConnection(cSpec);

For transaction demarcation in a non-managed environment, bean managed transactions are used. If we were to use bean managed transactions in the sample application, the remote methods would look like this:

Listing 9

LocalTransaction transaction = null;
.....
try {
	connection = connectionFactory.getConnection();
	transaction = connection.getLocalTransaction();
	transaction.begin();
	interaction = connection.createInteraction();
	.....
	transaction.commit();
	} catch (Exception e) {
		try{
				transaction.rollback();
		}
		catch (Exception ex){} 
		.....
	} finally {
	.....
	}

In a non-managed environment, Encina connector is not deployed in WebSphere Application Server. Instead, the clients use the resource adapter libraries directly. Since these libraries are archived in the encconn.rar file, you have to extract the encconn.jar and delight11.jar files from the RAR file before using them.

Back to top

Conclusion

In this article, we have seen how to connect to TXSeries Encina using the J2EE resource adapter, Encina Connector, provided with the product. We started with an overview of the connector and saw how to use the Common Client Interface (CCI) to develop J2EE applications, with special considerations for transaction management, exception handling, and security. We also saw how to deploy Encina Connector and the application in WebSphere Application Server, how to configure the DE-Light Gateway for better performance and fail-over, and how to trace and debug problems.

With this information, along with the additional Resources provided, you will be able to begin developing enterprise applications as clients for your Encina Servers.

Back to top

Download

Description	Name	Size	Download method
Sample application	EmpSample.zip	95 KB	FTP|HTTP

Information about download methods

Resources

• Download the most recent version of J2EE (including JCA) from Sun Microsystems.
  
  
• J2EE Connector Architecture Specification
  
  
• Introduction to the J2EE Connector Architecture, a developerWorks tutorial
  
  
• The Java Series Book, J2EE Connector Architecture and Enterprise Application Integration, is a guide that shows enterprise developers how to use the connector architecture to incorporate existing enterprise infrastructure and applications into a Web-based environment.
  
  
• The developerWorks article, Understanding JCA transactions, explains how the J2C transaction contract helps implement transactional behavior in e-business applications.
  
  
• Encina Connector and other Encina related documentation is available in the TXSeries Library. Particularly relevant to this article are:
  • Encina DE-Light Programming Guide -- For details on programming using CCI of Encina Connector and some samples.
  • DE-Light Java Programming Pages -- For details on some of the classes of Encina Connector.
  • drpcadmin Command Pages -- For details on administering the DE-Light gateway using drpcadmin.
  • Encina Administration Guide Volume 1: Basic Administration -- For detailed instructions on tuning the DE-Light Gateway.
  • Encina Administration Guide Volume 2: Server Administration -- For introduction to DE-Light Gateway Model and administration of DE-Light Gateways, and for detailed instructions on deploying the Encina J2EE Connector into WebSphere Application Server.
  • Encina Administration Guide Volume 3: Advanced Administration -- For details on starting a DE-Light Gateway.
  
  
  
• For details on how to migrate DCE user registry to LDAP, see IBM Distributed Computing Environment Version 3.2 for AIX and Solaris: DCE Security Registry and LDAP Integration Guide.
  
  
• WebSphere Application Server product documentation
  
  
• WebSphere Studio Application Developer product documentation
  
  
• To learn more about WebSphere Application Server, visit the developerWorks WebSphere Application Server zone. You'll find technical documentation, how-to articles, education, downloads, product information, technical support resources, and more.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• J2EE and Encina
• Developing the J2C application
• Configuration and deployment
• Appendix A : Encina Connector interfaces and classes
• Appendix B: Non-managed environment
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: TXSeries for Multiplatforms
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: TXSeries for Multiplatforms

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers