JCAAbstract This article talks about how to build a JCA Connector based on JCA specifications, JCA framework, features and deployment strategies for Weblogic Server. Introduction Prior to introduction to JCA, the J2EE platform did not address the integration of java based of Java based enterprise application with Enterprise Information System (EIS) like ERP, CRM, Mainframe, and Legacy Systems etc. As such vendor specific, tightly coupled, non-portable solutions were developed to achieve the connectivity to EIS. Now JCA defines a uniform way to integrate J2EE application servers with EIS by which the application server vendors implement the Connector Framework only once and EIS vendors develop one standard resource adapter based on this architecture. Thus a JCA compliant resource adapter can be deployed in any JCA compliant Application Server like WebLogic Server. Resource Adapter The resource adapter plays a central role in integration and connectivity between an Application Components, Application and EIS. To enable seamless integration the resource adapter must implement System Contracts, EIS specific Contracts and Application Component contracts (Client API). These contracts are defined in terms of interfaces that the adapter must implement. The various packages that contain these interfaces are: javax.resource.spi - Adapter Interfaces to encapsulate EIS javax.resource.cci - Client API Interface javax.transaction.xa - XA Transactions Support Interface javax.security.auth - Authentication and Authorization Interface System Contracts The system contract defines the interactions between Resource Adapter and the Application Server. There are 3 types of system contracts some of which are optional: 1. Connection Management (required) This contract describes the understanding, a J2EE container has with the adapter regarding connection establishment, pooling and tearing down of connections to the EIS. The underlying protocol an adapter uses connect to EIS is outside the scope of JCA specification. Connection Management Interfaces to Implement ConnectionManager Provides Connection ManagementIn case of non-managed environment>/td> ManagedConnection - Represents the physical connection to EIS ManagedConnectionFactory - Represents a Factory For Managed Connections ManagedConnectionMetaData - Provides information about the managed connections ConnectionRequestInfo - Encapsulates the client credentials to obtain a connection to EIS Connection - Represents the CCI Connection after a JNDI Lookup from the CCI Connection Factory. Each CCI Connection is associated with the Managed Connection ConnectionFactory - Represents a Factory for CCI Connections. 2.Transaction Management (optional) This contract allows the application to manage and propagate transaction Context from the J2EE container to the EIS. These further are of two types: a. Local Transactions When only one system (EIS) is involved in an interaction, transactions are internally managed by the EIS system, thus they are called Local Transactions. b. Distributed Transactions When multiple systems (EIS) are involved, a transaction manager (from J2EE container) external to each EIS controls and coordinates the overall transaction (i.e. ensures a two phase commit). These transactions across multiple resources are referred as XA and are defined in the Java Transaction API (JTA) specification. * The resource adapter can support local transactions, or both type of transactions and neither type of transaction. Transaction Management Interfaces to Implement LocalTransaction - Provides methods for Local Transaction demarcation XAResource - Provides methods for distributed XA Transaction demarcation 3. Security Contracts (optional) These security contracts define a secure way to access EIS. Java Authentication and Authorization Service (JAAS) interfaces like Subject, Principal, and Generic Credential etc. are used with the Connection Management Interfaces of the Resource Adapter to achieve this. The Application server can use two methods to authenticate to an EIS system (via a resource adapter) a. Container Managed Sign On In this method the resource credentials are defined in the resource adapter deployment descriptor and the application server uses those credentials to connect to EIS b. Component Managed Sign On In this method the application provides the required security credentials each time a connection is acquired from the resource adapter. Security Management Interfaces to Implement GenericCredential -Provides methods to access the security credentials of the user EIS specific Contracts The resource adapter communicates with the EIS using the EIS specific protocol. The J2EE Connector does not specify a protocol or an interface between a resource adapter and EIS. The adapter can use CORBA, SOAP, XML and RMI etc. as supported by EIS to access it. The resource adapter also has to handle marshalling and un-marshalling between EIS and Java Data Types. Application Component Contracts Application uses the client API to access the EIS. A resource adapter can either implement the Common Client Interface (CCI) or it can implement an API specific to EIS or itself. The CCI interfaces are divided into four sections: a. Connection Interfaces API encapsulates interfaces for establishing a connection to an EIS b. Interaction Interfaces API encapsulates interfaces for sending command or queries to EIS c. Record / ResultSet Interfaces API encapsulates interfaces to retrieve command or query results as returned from EIS d. Meta Data Interfaces API encapsulates interfaces to query EIS's metadata. Packing Resource Adapter The packing of resource adapter includes packing the resource adapter implementation classes, client API implementation classes, dependent external libraries (optional) and a resource adapter deployment descriptor into Resource Archive (RAR) file using the Java Archive (JAR) format. The way to deploy of the .rar file depends on application server. Example: The resources adapter adapter.rar might include the following files: META-INF/ra.xml - Deployment Descriptor AdapterImpl.jar - Adapter Implementation ClientAPI.jar - Client API Implementation DependentAPI.jar - Dependent API The resource adapter includes an XML deployment descriptor file. The application server relies uses this information to properly deploy and interact with the resource adapter. The deployment descriptor contains information about: a. General Information about Resource Adapter b. Interface and Implementation Classes c. Transaction support level d. Authentication Information e. Configuration Properties Sample ra.xml Deploying Resource Adapter The resource adapter can be deployed to the WebLogic Server via the Weblogic Server Administration Console. Step 0: Launch and Sign in into Weblogic Sever Console Expand the Domain Leaflets where you want to deploy the adapter. Expand the Deployment Leaf under that Domain Click on the Connector Leaf and the deployment wizard appears on the right frame. Click on Configure New Connector component to launch the wizard. Step 1: Manually Copy or Upload the .rar file via console to an appropriate directory. Generally all these application go under directory $domainHome/applications Step 2: Select the .rar file which was uploaded or copied in Step1 that you would like to configure and deploy Step 3: Select the Servers to which the connector has to be deployed Step 4: Give the name for the application connector Step 5: Click on Configure and Deploy button to start the process. If there is some problem with the deployment, the Weblogic Server throws the exception, which can be analyzed and fixed and finally the above steps can be repeated again for deployment. If there are no errors, Weblogic Server gives confirmation about proper deployment of the connector. Sample Code This sample code describes Application Component code to Connection Lookup, creating Interaction and getting results using the CCI Interface. // connection and interaction javax.resource.cci.Connection con = null; AdapterInteraction intr = null; String exception = null; String min = null; // retrieve initial context InitialContext ctx = new InitialContext(); __log.debug("Retrieve the Initial Context"); // get the connection factory Object obj = ctx.lookup(IJNDINames.ADAPTER_CONNECTION_FACTORY); __log.debug("Lookup Connection Factory JNDI..."); //type cast AdapterConnectionFactory fact = (AdapterConnectionFactory)obj; __log.debug("Object type casted into Connection Factory..."); //create adapter connection spec AdapterConnectionSpec spec = new AdapterConnectionSpec(); spec.setUser("adapter-username "); spec.setUser("adapter-password "); // get the adapter connection Object objConn = fact.getConnection(spec); // type cast __log.debug("Type cast object into cci connection"); con = (javax.resource.cci.Connection)objConn; //create the interaction __log.debug("Create a new Interaction from the connection"); intr = (AdapterInteraction)con.createInteraction(); // create interaction spec __log.debug("Create a new Interaction Spec"); AdapterInteractionSpec specInt = new AdapterInteractionSpec(); specInt.setServiceType(ISAInteractionSpec.SERVICE_TYPE); // create input record __log.debug("Create a new ISA Record"); ISARecord recIn = new ISARecord(); recIn.setRecordName(name); recIn.setParameter(param); // execute the interaction __log.debug("Execute the Interaction Service"); AdapterRecord recOut = (AdapterRecord)intr.execute(specInt,recIn); __log.debug("Retrieved the ISA Record trying to get min"); // get results param = recOut.getParameter(); Conclusion JCA connector provides portable solutions for system integration with EIS that can be seamlessly plugged into the BEA application server providing transactional, security and connection management features with ease deployment and maintenance.