Creating and Using Custom Java EE Connector Architecture Adapters

by Ronald van Luttikhuizen

Creating a custom adapter for integrating your apps is sometimes necessary, so it pays to understand the considerations involved.

One major technology-oriented focus of Service-Oriented Architecture (SOA) is the interoperability of heterogeneous systems and technologies. Interoperability is a condition for successful SOA-adoption since it enables the reuse of existing IT assets and therefore increases their ROI.

The Oracle Fusion Middleware product family offers a complete portfolio of products to enable development, deployment, and management of SOA. One of those products is Oracle Integration Adapters. This product provides a range of adapters that enable integration with a plethora of technologies, protocols, legacy systems, and packaged applications. Other components in the Oracle Fusion Middleware portfolio–such as Oracle BPEL Process Manager and Oracle Enterprise Service Bus (ESB)–use these adapters to integrate services and processes with existing IT assets. Examples include the JMS Adapter, Database Adapter, E-Business Suite Adapter, and Tuxedo Adapter.

Figure 1: The Oracle SOA Platform

However, the provided set of adapters does not always suffice for every integration scenario. In such cases you’ll either need to implement your own adapter or buy a third-party adapter. A list of such vendors and their offerings can be found on the Oracle Integration Adapters page on OTN.

This article includes a step-by-step tutorial for building your own adapter and using it in Oracle SOA Suite 10g, based on a real-world customer use case. An overview of the involved frameworks and components is provided alongside the hands-on tutorial. This article also briefly discusses adapter support, offerings, and convergence in future Oracle Fusion Middleware releases that incorporate former BEA products.

Architectural Overview

This section provides an architectural overview of Oracle Integration Adapters and its main components before diving into its specifics. The main components of Oracle Integration Adapters are:

Adapter offering
Adapter Framework
Design-time support

These components – together with their relation to SOA Suite components and EIS systems – are shown in the following figure.

High-level overview of the design-time and run-time components that participate in the integration between SOA Suite components and EIS systems

Figure 2: High-level overview of the design-time and run-time components that participate in the integration between SOA Suite components and EIS systems.

Introduction to JCA

Oracle’s adapters are implemented as Java EE Connector Architecture (JCA) resource adapters. JCA is a Java standard that provides a generic architecture to connect JEE-compliant application servers to Enterprise Information Systems (EIS). The current JCA standard supports bidirectional communication and can be deployed on any JEE-compliant application server – including Oracle WebLogic Server and Oracle Application Server. You can use the uniform JCA APIs and contracts to programmatically connect to legacy systems instead of having to learn and use each EIS’s API or other interface mechanism.

As shown in Figure 3, a resource adapter in JCA encapsulates the logic to connect to a single EIS or technology. Client components can invoke the adapter to connect to the underlying EIS. By using these adapters, developers are alleviated of diving into all APIs and interface mechanisms of EIS and technologies that need to be integrated. Instead, developers only need to know the generic JCA APIs and contracts.

Figure 3: Overview of JCA

There are two versions of JCA, version 1.0 (JSR-16) and version 1.5 (JSR-112). JCA version 1.0 defines:

A set of system-level contracts between an application server and EIS. These contracts are implemented by a resource adapter and support connection management, transaction management, and security mechanisms. This enables resource adapters to be robust, scalable, and to participate in global transactions that span multiple components including adapters.
The Common Client Interface (CCI) that defines an API client components can use to interact with the EIS through a JCA resource adapter.
A deployment and packaging mechanism for resource adapters.

Important enhancements made in version 1.5 include:

An expanded set of system-level contracts adding lifecycle management and thread – or work – management.
Transaction and message inflow capabilities enabling asynchronous inbound communication with an EIS. A resource adapter either subscribes to events generated by an EIS or uses polling to implement inbound communication. Inbound messages to other components are delivered through JMS or a similar messaging infrastructure.

The following interaction patterns between application components and EIS are possible using JCA 1.5:

JCA 2-way outbound interactions: Synchronous request/response from resource adapter to EIS
JCA 1-way outbound interactions: Asynchronous subscription or fire-and-forget from resource adapter to EIS
JCA 1-way inbound interactions: Asynchronous event-publishing from EIS to resource adapter through polling or firing events

Both Oracle WebLogic Server 10g R3 and Oracle Application Server 10g R3 support JCA version 1.5.

The Oracle Adapter Framework is a layer on top of the JCA resource adapters. It uses Web service technologies to expose its adapters and APIs. The advantage is that non-Java applications can access these adapters. Another advantage is that no coding is required, only configuration.

Oracle JDeveloper offers design-time support to configure adapters and use them from JEE applications and Oracle Fusion Middleware products. Note that other design-time tools – Application Explorer and Oracle Studio – are available for several packaged-application and mainframe adapters.

Use Case

This tutorial is based on a customer case in which Oracle SOA Suite is used to implement a SOA environment. One of the project’s requirements specifies that processes can be activated through received mail messages, transforming and passing the message as payload to the process.

The project uses the following model to determine the assignment of functionalities and responsibilities to service layers:

Figure 4: Layers in a SOA environment

As illustrated in Figure 4, the role of the enterprise service bus (ESB) is to connect the service layers and to integrate the various backend technologies and applications – and their elementary services – into the SOA environment. Based on this model, the integration scenario for receiving mail messages and passing them to processes is implemented in the ESB layer. Since Oracle ESB provides no out-of-the-box support for mail connectivity, a custom inbound mail adapter is implemented.

Figure 5: Integration scenario for this article

This task is broken down into the following steps:

Create, deploy, and test a simplified inbound JCA resource adapter that polls for mail messages.
Create the required Adapter Framework artifacts.
Use the adapter from Oracle ESB. Note that although this case focuses on Oracle ESB, the exact same steps apply for Oracle BPEL Process Manager.

Read and complete the steps in the accompanying setup guide before you continue the steps below.

Step 1: Implement JCA Interfaces

You’ll need to implement several Java interfaces in order to create a resource adapter. Some of these are generic, while others are specific for either inbound or outbound interactions. The most important of these interfaces are:

javax.resource.spi.ResourceAdapter - This represents a resource adapter instance and contains operations for lifecycle management and message endpoint setup such as start(BootStrapContext) and stop().
javax.resource.cci.Record - Defines the payload of the messages that are exchanged between the resource adapter and client components.
javax.resource.spi.ActivationSpec - Contains the configuration information that is required to activate a resource adapter endpoint.
javax.resource.spi.work.Work, javax.resource.spi.work.WorkManager - Lifecycle management interfaces for thread creation, scheduling, pooling, and execution by the application.
javax.resource.spi.ManagedConnectionFactory, javax.resource.spi.ManagedConnection - Connection management interfaces used to create connections to an EIS. These classes support connection pooling.

The next section includes diagrams that illustrate the relationships and interactions between the JCA interfaces and our custom resource adapter implementation.

Use Case

We’ll implement a simple non-transactional inbound JCA resource adapter that polls for new mail messages and deletes them after delivery. Its design is shown is the following UML diagrams:

UML Class Diagram showing the relevant JCA interfaces for inbound adapters in the left hand package. The right hand package shows the implementation of the required interfaces by the custom JCA mail resource adapter

Figure 6: UML Class Diagram showing the relevant JCA interfaces for inbound adapters in the left hand package. The right hand package shows the implementation of the required interfaces by the custom JCA mail resource adapter.

Figure 7: UML Sequence Diagram showing the order of invocations for the custom JCA inbound mail resource adapter.

As explained in the setup guide you can choose between the following environments to deploy the JCA resource adapter and test it using a JMS client:

Oracle JDeveloper 10g and Oracle WebLogic 9.2 MP3
Oracle JDeveloper 10g and Oracle Application Server 10g
Oracle JDeveloper 11g and Oracle WebLogic 10g Release 3

This section provides instructions for all three environments.

The sample JDeveloper application workspace – regardless of the chosen environment – contains the following projects:

MailResourceAdapter
Contains the implementation for an inbound JCA 1.5 resource adapter that polls for new mail messages. The messages generated by the JCA resource adapter are published to any client that subscribes to it and implements the MessageListener interface as declared in the deployment descriptors.

Note that you can ignore the package nl.approachalliance.otn.jca.soasuite and its contents for now. These classes are part of the Adapter Framework artifacts and are discussed later on.
MailResourceAdapterDeployment

Contains the generic JCA deployment descriptor (ra.xml), target runtime application server JCA deployment descriptor (weblogic-ra.xml for Oracle WebLogic Server or oc4j-ra.xml for Oracle Application Server), and resource adapter archive (RAR) deployment profile for the target runtime application server.

Copy



<connector
    xmlns="http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    version="1.5"               
    xmlns:schemaLocation="http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html
 http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html http://bit.ly/10DnufR">
  <display-name>Mail JCA Resource Adapter</display-name>
  <vendor-name>Oracle Technology Network</vendor-name>
  <eis-type>Mail Server</eis-type>
  <resourceadapter-version>1.0</resourceadapter-version>
  <resourceadapter>
    <resourceadapter-class>nl.approachalliance.otn.jca.MailResourceAdapter<
    /resourceadapter-class>
    <inbound-resourceadapter>
      <messageadapter>
        <messagelistener>
          <messagelistener-type>javax.resource.cci.MessageListener</messagelistener-type>
          <activationspec>
            <activationspec-class>nl.approachalliance.otn.jca.MailActivationSpec
            </activationspec-class>
            <required-config-property>
              <config-property-name>host</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>username</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>password</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>provider</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>pollingInterval</config-property-name>
            </required-config-property>
            <required-config-property>
              <config-property-name>folder</config-property-name>
            </required-config-property>
          </activationspec>
        </messagelistener>
      </messageadapter>
    </inbound-resourceadapter>
  </resourceadapter>
</connector>

Listing 1: Generic JCA deployment descriptor ra.xml. It specifies adapter metadata such as vendor and version, the type of adapter (inbound in our case), and several settings (listener interface, activation-spec properties, and resource adapter implementation in our case). The activation spec properties define the information that is required by our adapter to connect to the mail server.

The resource adapter is started after successful deployment or when the application server is started in case the adapter was already deployed.

Copy



 <weblogic-connector 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.bea.com/ns/weblogic/90/weblogic-ra.xsd"
    xmlns="http://www.bea.com/ns/weblogic/weblogic-connector">
 <jndi-name>jca/MailResourceAdapter</jndi-name> 
 <enable-access-outside-app>true</enable-access-outside-app>
 </weblogic-connector>

Listing 2: Oracle WebLogic deployment descriptor weblogic-ra.xml. Most important is the JNDI configuration to enable lookup of the adapter.

MailResourceAdapterClient

Contains an EJB Message-Driven Bean (MDB) that acts as client to the JCA resource adapter, a generic EJB deployment descriptor (ejb-jar.xml), and deployment profile and deployment descriptors (weblogic-ejb-jar.xml) for the target runtime application server. This MDB subscribes to the resource adapter. For every email that is polled by the adapter the onMessage() method of the MDB is invoked.

As determined by respective support for Java standards, the client is an EJB 2.1 MDB when using Oracle WebLogic Server 9.2 and an EJB 3 MDB when using Oracle WebLogic Server 10g R3 and Oracle Application Server 10g R3.

Copy



<ejb-jar  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html
    http://bit.ly/11nl5G2"
  version="3.0"  xmlns="http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html">
 <enterprise-beans>
  <message-driven>
   <description>EJB 3.0 Message  Driven Bean (MDB) that acts as client
    for the Mail JCA Resource  Adapter</description>
   <display-name>MailResourceAdapterClientMDBBean</display-name>
   <ejb-name>MailResourceAdapterClientMDBBean</ejb-name>
   <ejb-class>nl.approachalliance.otn.jca.MailResourceAdapterClientMDBBean</ejb-class>
   <messaging-type>javax.resource.cci.MessageListener</messaging-type>
   <transaction-type>Container</transaction-type>
   <activation-config>
     <activation-config-property>
      <activation-config-property-name>host</activation-config-property-name>
      <activation-config-property-value>localhost</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>username</activation-config-property-name>
      <activation-config-property-value>otn</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>password</activation-config-property-name>
      <activation-config-property-value>welcome1</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>provider</activation-config-property-name>
      <activation-config-property-value>pop3</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>pollingInterval</activation-config-property-name>
      <activation-config-property-value>5</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
      <activation-config-property-name>folder</activation-config-property-name>
      <activation-config-property-value>INBOX</activation-config-property-value>
     </activation-config-property>
   </activation-config>
  </message-driven>
 </enterprise-beans>
</ejb-jar>

Listing 3: Generic EJB deployment descriptor ejb-jar.xml. It defines the MDB and provides values for the adapter’s activation spec. The MDB class itself and application server deployment descriptors contain settings to subscribe the bean to the JCA resource adapter.

Copy



 <weblogic-ejb-jar 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-ejb-jar.xsd"
   xmlns="http://www.bea.com/ns/weblogic/weblogic-ejb-jar">
  <weblogic-enterprise-bean>
   <ejb-name>MailResourceAdapterClientMDBBean</ejb-name>
   <message-driven-descriptor>
    <resource-adapter-jndi-name>jca/MailResourceAdapter</resource-adapter-jndi-name>
   </message-driven-descriptor>
  </weblogic-enterprise-bean>
 </weblogic-ejb-jar>

Listing 4: Oracle WebLogic EJB deployment descriptor weblogic-ejb-jar.xml linking the MDB to the JCA resource adapter.

Before deploying and testing the JCA resource adapter make sure that the Apache JAMES mail server is started by running <JAMES home>/bin/run.bat.

Deploy and test the JCA resource adapter for Oracle WebLogic 9.2 MP3

In Oracle JDeveloper 10g, open the JCA resource adapter application workspace from the projects zip file. Select Open Application from the Applications Navigator. Browse to JDeveloper_10g/Oracle_WebLogic_Server_92/JCA_ResourceAdapter/JCA_ResourceAdapter.jws and select Open.
Copy connector15.jar, orabpel.jar, and orabpel-thirdparty.jar from the <SOA Suite home>/bpel/lib directory to the lib directory of the MailResourceAdapter project. These JAR files among others include the required JCA and XML Record Converter interfaces. Also copy connector15.jar to the lib directory of the MailResourceAdapterClient project.
Start the Oracle WebLogic Server 9.2 domain and server on which Oracle SOA Suite runs if it is not already started.
Deploy the custom resource adapter to Oracle WebLogic Server. Open the Resources folder of the MailResourceAdapterDeployment project in the Applications Navigator. Right-click the MailResourceAdapter.deploy file and select Deploy to RAR file.
Log in to the Oracle WebLogic Server Administration Console – the default is http://localhost:8001/console – using “weblogic” as username and password. Select Lock & Edit. Select Deployments → Install. Browse to the deploy directory of the MailResourceAdapterDeployment project, select the MailResourceAdapter.rar file, and click Next. Select Install this deployment as an application and click Next. Select OracleSOAServer in the server list and click Next. Accept all other defaults.

Select Activate Changes to deploy the resource adapter.

Check the state of the MailResourceAdapter application in Oracle WebLogic Server Administration Console. Start the application if the state is “Prepared”.
Deploy the client to Oracle WebLogic Server. Open the Resources folder of the MailResourceAdapterClient project in the Applications Navigator. Right-click the MailResourceAdapterClient.deploy file and select Deploy to JAR file.
Log in to Oracle WebLogic Server Administration Console. Select Lock & Edit. Select Deployments → Install. Browse to the deploy directory of the MailResourceAdapterClient project, select the MailResourceAdapterClient.jar file, and click Next. Select Install this deployment as an application and click Next. Select OracleSOAServer in the server list and click Next. Accept all other defaults.

Select Activate Changes to deploy the MDB.

Check the state of the MailResourceAdapterClient application in Oracle WebLogic Server Administration Console. Start the application if the state is “Prepared”.
Log in to Oracle WebLogic Server Administration Console. Select Deployments. The resource adapter and MDB client are visible in the deployments table; both with “State” Active and “Health” OK.
Figure 8: Oracle WebLogic Server Administration Console showing resource adapter and MDB client in the deployments table.
Test the resource adapter and its client by sending a mail message to jca@localhost using a mail client such as Mozilla Thunderbird.
Check the number of messages that are dequeued by the client Message-Driven Bean. Log in to Oracle WebLogic Server Administration Console and navigate to Deployments → MailResourceAdapterClient → MailResourceAdapterClientMDBBean (by expanding the MailResourceAdapterClient application) → Monitoring. In the Running tab, add the column “Processed Message Count” if this column is not yet shown in the table. The console shows the number of processed messages (there should be one message).
Figure 9: Oracle WebLogic Administration Console showing monitoring information for the MDB client.

Deploy and test the JCA resource adapter for Oracle Application Server 10g

In Oracle JDeveloper 10g, open the JCA resource adapter application workspace from the projects zip file. Select Open Application from the Applications Navigator. Browse to JDeveloper_10g/Oracle_Application_Server_10g/JCA_ResourceAdapter/JCA_ResourceAdapter.jws and select Open.
Copy connector15.jar, orabpel.jar, and orabpel-thirdparty.jar from the <SOA Suite home>/bpel/lib directory to the lib directory of the MailResourceAdapter project. These JAR files among others include the required JCA and XML Record Converter interfaces. Also copy connector15.jar to the lib directory of the MailResourceAdapterClient project.
Start Oracle Application Server 10g on which Oracle SOA Suite runs if it is not already started.
Deploy the custom resource adapter to Oracle Application Server. Open the Resources folder of the MailResourceAdapterDeployment project in the Applications Navigator. Right-click the MailResourceAdapter.deploy file and select Deploy to → OAS_SOA_Suite_10g (the name of the Application Server connection as specified in the guide).
Deploy the client to Oracle Application Server. Open the Resources folder of the MailResourceAdapterClient project in the Applications Navigator. Right-click the MailResourceAdapterClient.deploy file and select Deploy to → OAS_SOA_Suite_10g.
Test the resource adapter and its client by sending a mail message to jca@localhost using a mail client such as Mozilla Thunderbird.
Check the number of messages that are dequeued by the client Message-Driven Bean. Log in to Oracle Application Server Enterprise Manager and navigate to Cluster Topology → oc4j_soa → Applications → MailResourceAdapterClient → MailResourceAdapterClient (EJB Module) → MailResourceAdapterClientMDBBean. The console shows the number of dequeued messages (there should be one message) and the values for the resource adapter activation spec.

Enterprise Manager showing information of the client MDB. The console shows values for the JCA activation spec and tells us that one message is received

Figure 10: Enterprise Manager showing information of the client MDB. The console shows values for the JCA activation spec and tells us that one message is received.

Deploy and test the JCA resource adapter for JDeveloper 11g with Integrated WebLogic Server 10g R3

In Oracle JDeveloper 11g, open the JCA resource adapter application workspace from the projects zip file. Select Open Application from the Applications Navigator. Browse to JDeveloper_11g/JCA_ResourceAdapter/JCA_ResourceAdapter.jws and select Open.
Copy orabpel.jar and orabpel-thirdparty.jar from the <SOA Suite home>/bpel/lib directory to the lib directory of the MailResourceAdapter project. These JAR files among others include the required XML Record Converter interfaces. Verify that the WebLogic 10.3 Remote-Client library is listed in the Libraries and Classpath of the MailResourceAdapter and MailResourceAdapterClient projects. This library includes the required JCA interfaces.
Start the JDeveloper Integrated WebLogic Server by selecting Run → Start Server Instance.
Deploy the JCA resource adapter to the Integrated WebLogic Server. Right-click the MailResourceAdapterDeployment project in the Applications Navigator and select Deploy → MailResourceAdapter → to IntegratedWLSConnection.
Deploy the client to the Integrated WebLogic Server. Right-click the MailResourceAdapterClient project in the Applications Navigator and select Deploy → MailResourceAdapterClient → to IntegratedWLSConnection.
Log in to Oracle WebLogic Server Administration Console–the default is http://localhost:7101/console—using “weblogic” as username and password. Select Deployments. The resource adapter and MDB client are visible in the deployments table; both with “State” Active and “Health” OK.
Figure 11: Oracle WebLogic Server Administration Console showing resource adapter and MDB client in the deployments table.
Test the resource adapter and its client by sending a mail message to jca@localhost using a mail client such as Mozilla Thunderbird.
Check the number of messages that are dequeued by the client Message-Driven Bean. Log in to Oracle WebLogic Server Administration Console and navigate to Deployments → MailResourceAdapterClient → MailResourceAdapterClientMDBBean (by expanding the MailResourceAdapterClient application) → Monitoring. In the Running tab, add the column “Processed Message Count” if this column is not yet shown in the table. The console shows the number of processed messages (there should be one message).
Figure 12: Oracle WebLogic Administration Console showing monitoring information for the MDB client.

You now have deployed a custom JCA resource adapter, deployed a JMS client, and tested the adapter by sending mail messages and then receiving those messages in the MDB! Now let’s continue by integrating the adapter with Oracle SOA Suite components using the Adapter Framework.

Step 2: Hook Up the Adapter Framework

The Oracle Adapter Framework (the Adapter SDK) is a lightweight framework that exposes JCA 1.0 and 1.5 resource adapters using XML and Web service technologies.

At runtime SOA Suite components invoke resource adapters using Web Service Invocation Framework (WSIF) calls. The Adapter Framework translates these WSIF invocations into JCA calls according to the JCA CCI contract and its API.

(Note: WSIF is a Java API maintained by Apache. Read the OTN article ” Using WSIF for Integration” to learn how WSIF can influence performance and transaction propagation. WSIF can be used instead of pure SOAP to enable other, more proprietary but faster protocols such as local Java calls or RMI to be used under the hood while defining a component in standard web service artifacts like WSDL. Evaluation of the binding protocol to be used is performed at runtime. This may result in better performance.)

A WSDL stores the information that is required by client components to invoke the adapter, and for the Adapter Framework to translate the WSIF invocations to appropriate JCA adapter calls. The WSDL contains JCA-specific extensions to store adapter-related information. Vice versa, the same mechanism – in opposite direction – is used for inbound JCA interactions.

Oracle JDeveloper offers wizards in the BPEL PM designer and ESB designer to define and generate adapter WSDLs and XML payloads at design-time. The Adapter Framework also offers design-time functionality for extracting EIS metadata, including business services and objects.

Use Case

We’ll perform the following tasks to use our custom adapter from Oracle ESB through the Adapter Framework:

Create a mapping to transform between JCA records and Oracle XML records. This mapping is called the Oracle XML Record Converter. The mapping consists of the implementation of Java interfaces.
Create an adapter definition that specifies the resource adapter, its configuration, and the XML Record Converter implementation. This definition consists of a WSDL file with JCA-specific extensions. For prepackaged adapters this is normally done through wizards in JDeveloper.
Publish all required runtime Java artifacts, such as the resource adapter and XML Record Converter classes, as an application server library.

XML Record Converter

Open and view the XML Schema MailAdapter.xsd that defines the XML payload that will be used by our Oracle ESB project. This file is in the Adapter_Framework directory of the projects zip file. The XSD is simple and straightforward.
Open and view the XML Record Converter implementation in Oracle JDeveloper. These classes are in the nl.approachalliance.otn.jca.soasuite package of the MailResourceAdapter project. There are two classes in this package:
1. MailXMLRecord.java – Class representing a mail message. Besides the actual payload you can also specify attachments, header information, record name, priority, and other attributes..
2. MailRecordElement.java – Class representing the payload of a mail message as DOM source. Other possible sources are SAX sources and Stream sources. This class also contains convenience methods for getting mail subject, from addresses, and other attributes.
3. MailXMLRecordConverter.java – Class containing the logic to transform a MailRecord instance into MailXMLRecord instance and vice versa.

WSDL

The Adapter Framework requires a standard WSDL to be enriched with JCA- and XML Record Converter-specific information in order to be able to connect to the JCA resource adapter at runtime and to convert JCA records into XML.

The following figure shows the structure of such a WSDL.

Figure 13: Standard WSDL enriched with Adapter Framework and JCA-specific information.

The WSDL for the custom resource adapter is shown in Listing 5.

Copy



<definitions  name="MailAdapter"             
       targetNamespace="http://www.approachalliance.nl/otn/adapter/mail"                 
       xmlns="http://schemas.xmlsoap.org/wsdl/"             
       xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"             
       xmlns:tns="http://www.approachalliance.nl/otn/adapter/mail"             
       xmlns:pc="http://xmlns.oracle.com/pcbpel/"             
       xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"             
       xmlns:adapter="http://www.approachalliance.nl/otn/adapter/mail">
     <types>
       <schema xmlns="http://www.w3.org/2001/XMLSchema">
         <import namespace=http://www.approachalliance.nl/otn/adapter/mail  
schemaLocation="MailAdapter.xsd"/>
       </schema>
     </types>
     <message name="Read_msg">
       <part name="Mail" element="adapter:Mail"/>
     </message>
     <portType name="Read_ptt">
       <operation name="Read">
        <input message="tns:Read_msg"/>
       </operation>
     </portType>
     <binding name="Read_binding"  type="tns:Read_ptt">
       <pc:inbound_binding  XMLRecordConverterCallout=
"nl.approachalliance.otn.soasuite.adapter.MailXMLRecordConverter"/>
       <operation name="Read">
        <jca:operation 
              ActivationSpec="nl.approachalliance.otn.jca.MailActivationSpec"
             host="localhost" 
             username="jca"
             password="welcome1" 
             provider="pop3"
             pollingInterval="5"
             folder="INBOX">
        </jca:operation>
       </operation>
     </binding>
     <service name="MailAdapter">
       <port name="Read_pt"  binding="tns:Read_binding">
        <jca:address  ResourceAdapterClassName=
"nl.approachalliance.otn.jca.MailResourceAdapter"/>
       </port>
     </service>
     <plt:partnerLinkType name="Read_plt">
       <plt:role name="Read_role">
        <plt:portType name="tns:Read_ptt"/>
       </plt:role>
     </plt:partnerLinkType>
</definitions>

Listing 5: MailAdapter.wsdl. WSDL that the Adapter Framework uses to connect to the JCA resource adapter. It almost defines the same information–resource adapter implementation class and activation spec values–as the MDB deployment descriptor from the previous section. It furthermore defines the XML payload and the converter implementation to translate between JCA records and XML payload.

Publish library

In order for SOA Suite products to use the custom adapter at runtime the adapter must be published to the application server on which SOA Suite is running.

Complete Step 3 if you run SOA Suite on Oracle WebLogic Server 9.2. Complete Step 4 if you run SOA Suite on Oracle Application Server 10g.

Publish the custom adapter artifacts to Oracle WebLogic Server 9.2:
1. Undeploy the client MDB that we used in the previous section. Log in to Oracle WebLogic Server Administration Console and navigate to SOADomain → Deployments → Applications. Click Lock & Edit to modify, add, or delete items in this domain. Select the MailResourceAdapterClient application and click Delete. Select Yes and click Activate Changes.
2. Publish the library. Copy MailResourceAdapter.jar from the MailResourceAdapter/deploy directory to the <BEA Home>/user_projects/domains/SOADomain/lib directory.
3. Restart Oracle WebLogic Server.
Publish the custom adapter artifacts to Oracle Application Server 10g:
1. Undeploy the client MDB that we used in the previous section. Log in to Oracle Application Server Enterprise Manager and navigate to Cluster Topology → oc4j_soa → Applications. Select the MailResourceAdapterClient application and click Undeploy.
2. Publish the library. In Oracle Application Server Enterprise Manager navigate to the Oracle BPEL shared library by selecting Cluster Topology → oc4j_soa → Administration → Shared Libraries → oracle.bpel.common → Edit (in the Archives section).
3. Add the JAR file from the first step by selecting Add and selecting MailResourceAdapter.jar from the MailResourceAdapter/deploy directory.
4. Select OK and restart Oracle Application Server.

Now that we have created the required Adapter Framework artifacts we can start using the custom adapter in an integration scenario.

Step 3: Build the Enterprise Service Bus Flow

A service bus facilitates implementation of more low-level services within an SOA and EDA and is preferably based on open standards (XPath, XSLT, SOAP, JMS, JCA, and so on). ESBs are particularly well suited for virtualization, routing, and data transformation, thereby separating these concerns from the design, implementation, and execution of business logic and processes, which in the Oracle stack is typically done with BPA, BPM, and BPEL tooling. In this use case, we primarily need adapter, transformation, and routing capabilities rather than business and process logic. The integration scenario is therefore implemented as an Oracle ESB project, though the same steps apply for Oracle BPEL Process Manager.

Use Case

We will build an ESB flow that uses our mail adapter to receive incoming mail messages and for simplicity uses an outbound file adapter to output the messages as XML files on the file system.

In Oracle JDeveloper, create a new application workspace to hold your ESB application. Right-click Applications in the Applications Navigator.Select New Application… and enter ESB_CustomAdapter as the application name. Accept the defaults and click OK to create the application. Select Cancel in the Create Project dialog box.
Figure 14: Creating a new application in Oracle JDeveloper
In the Applications Navigator, right-click the newly created application and select New Project…. Select General → Projects → ESB Project from the New Gallery dialog box. Enter ESB_CustomAdapter as the project name, accept all other defaults, and click OK. Oracle JDeveloper will create a new ESB project containing a jpr and an esb file. The esb file, named ESB_CustomAdapter.esb, is automatically opened in the ESB Designer.
Figure 15: Creating a new ESB project in Oracle JDeveloper

The next steps involve structuring the services in your ESB project. For this purpose, systems and service groups are used. Systems are mandatory top-level organizational units, and service groups are optional sub-organizational units. This means that a service is either part of another service group or that a service directly belongs to a system.

Click the Create System/Group icon in the top of the ESB Designer. This will open the Create ESB System or Service Group dialog box. Select System, enter “OTN” as the name (a description is optional). Click OK to create the new ESB system definition.
Figure 16: The Create System/Service Group option in Oracle JDeveloper's ESB Designer

Figure 17: Creating the ESB System “OTN” in Oracle JDeveloper
Again, open the Create ESB System or Service Group dialog box. This time, select Service Group. This will show an additional option that allows you to select the system of which the new service group will be part. If the containing system is not yet set to OTN, do so by clicking the flashlight icon. This opens the ESB Service Group Browser.
Select the OTN system created in the previous step and click OK. Back in the Create ESB System or Service Group dialog box, enter CustomAdapter as name (a description is optional), and click OK to create the new service group.
Figure 18: The ESB Service Group Browser in Oracle JDeveloper

Figure 19: Creating the “CustomAdapter” service group in Oracle JDeveloper as part of the “OTN” system

Now we can start defining our custom adapter!

Copy MailAdapter.wsdl and MailAdapter.xsd (located in the ESB directory of the projects zip file) to the ESB project’s root directory. These are the adapter definition and message payload as described in the Adapter Framework section.
Create a custom adapter that will poll for new mail messages. Make sure the ESB Designer is open. From the Component Palette on the right, select ESB Services and drag the Custom Adapter onto the ESB Designer window. This will open the Create Adapter Service dialog box.
Figure 20: Creating a custom adapter

Enter Receive_Mail as the service name (a description is optional). Make sure that OTN.CustomAdapter is selected as containing System/Group. If it is not already selected, use the flashlight icon to open the ESB Systems/Groups browser and select OTN → CustomAdapter.
Click the Browse WSDL Files From Local File System... and select the MailAdapter.wsdl file. Note that the correct port type Read_ptt as previously defined in the WSDL is already provided. Click OK to create the custom adapter.
Figure 21: Creating a custom adapter

A routing service for this inbound file adapter, called Receive_Mail_RS, is automatically added to the project when the file adapter wizard is completed. This adapter provides routing and transformation capabilities.

Figure 22: The ESB Designer after creating the inbound custom mail adapter service

For simplicity we’ll output the mail message as an XML file to the local file system using an outbound file adapter.

Create an outbound file adapter that will poll for new Acme invoice files. Make sure the ESB Designer is open. From the Component Palette on the right, select Adapter Services and drag the File Adapter onto the ESB Designer window. This will open the Create File Adapter Service dialog box.
Figure 23: Creating a file adapter

Enter Publish_Mail as the service name and optionally add a description. Make sure that OTN.CustomAdapter is selected as containing System/Group. If it is not already selected, use the flashlight icon to open the ESB Systems/Groups browser and select OTN → CustomAdapter.
Click the Configure adapter service wsdl icon, next to WSDL File, to open the Adapter Configuration Wizard and continue with the adapter service configuration.
Figure 24: Step 2 of the File Adapter Configuration Wizard

Figure 25: Step 3 of the File Adapter Configuration Wizard

In this wizard, use the following settings:
1. Step 1: Accept the defaults.
2. Step 2: Operation Type: Write File.
3. Step 2: Operation Name: Publish_Mail.
4. Step 3: Directory Names are Specified as: Physical Path.
5. Step 3: Directory for Outgoing Files (physical path): an existing directory on the machine on which ESB runs, for example C:/temp.
6. Step 3: File Naming Convention: mail_%yyMMddHHmmssSS%.xml.
7. Step 3: Write to new file when existing file meets any of these conditions – Number of Messages Equals: 1.
8. Step 6: Click browse and select Project Schema Files → MailAdapter.xsd → Mail. Note that this is the same schema as the one for the custom adapter.
Figure 26: The ESB Designer after creating the outbound file adapter service

Now we only need to link the inbound custom mail adapter to the outbound file adapter. As mentioned, Oracle JDeveloper automatically created a routing service for the inbound custom mail adapter. However, this routing service does not contain any routing or transformation logic yet. Let’s create the necessary functionality to connect the inbound custom mail adapter to the outbound file adapter.

Open the Receive_Mail_RS routing service by double-clicking it in the ESB Designer. The routing service has a single operation, Read, with no routing rules. (Note that the option Invocable from an external service is selected by default. This means that during deployment of the ESB project a Web service will be created that, if executed, invokes this routing service. This feature can be used for testing purposes. If you do not require the routing service to be externally invocable you can deselect the Invocable from an external service option.)
Add a routing rule by clicking the green + icon to the right of the Receive_Mail operation. The Browse Target Service Operation dialog box opens.
Figure 27: The routing service with no routing rules for the Read operation
Select the Publish_Mail service of the file adapter we created earlier as the target.
Figure 28: Selecting the Publish_Mail service of the outbound file adapter as the target service

The Routing Service window shows that the insert is synchronously invoked after a mail message received by the custom mail adapter.

Figure 29: The routing service including a routing rule for the Read operation

You will need to create a transformation rule because the XML format of the inbound invoice files differs from the XML format expected by the database adapter.
Click on the XSL mapping icon next to <<Transformation Map>> to create a transformation (XSL) file. In the dialog box, select Create New Mapper File, accept the default name Mail_To_Mail.xsl, and click OK. This will open the XSLT Mapper tool. You’ll see the mail XML structure on both-hand sides of the XSLT Mapper.
Figure 30: The XSLT mapper tool in Oracle JDeveloper

The XSLT mapper enables you to visually define mappings from input elements to output elements by allowing drag-and-drop actions. The mapper also provides auto-complete functionality for input and output elements that have similar names.
Try the auto-complete functionality by dragging the imp1:Mail element from the left onto the imp1:Mail element on the right. The Auto Map Preferences dialog box appears.
Figure 31: Auto-mapping input and output XML files by using the XSLT mapper tool in Oracle JDeveloper

Leave the defaults of the mapper unchanged and click OK. All elements are mapped. The resulting mapping should look like this:

Figure 32: Final mapping
Save all files in the ESB project by clicking Save All.

The project is finished and ready to be deployed to the ESB server and taken for a spin! Let’s deploy and test the ESB flow and its custom adapter. These steps are the same for Oracle ESB running on Oracle WebLogic 9.2 and Oracle ESB running on Oracle Application Server 10g.

Deploy and test the ESB project

Start Apache JAMES mail server if not already started.
In Oracle JDeveloper 10g, either open the ESB project created in the previous step or the complete ESB project from the projects zip file.
Deploy the ESB project to Oracle Application Server by right-clicking the project in the Applications Navigator and selecting Register with ESB. Oracle JDeveloper will inform you that the OTN system, CustomAdapter service group, and adapters and routing services are created on the server.
Figure 33: Registering the ESB project with Oracle ESB

Figure 34: Registration successful
Open the ESB console in a browser window to view the registered ESB flow. The ESB console URL is http://host:port/esb. For example http://localhost:9700/esb for ESB running on Oracle WebLogic Server 9.2 and http://localhost:80/esb for ESB running on Oracle Application Server 10g.
Figure 35: Oracle ESB Console

In the Services overview, drill down to view the OTN system, the CustomAdapter service group, and the services that you have just created and deployed.

Check the settings –such as virtual host and port– of the OTN system and if needed correct these to reflect your environment configuration.
Initiate and test the ESB flow by sending a mail message to jca@localhost using a mail client such as Mozilla Thunderbird.
As a result, the mail message is published as an XML file to the directory specified in the outbound file adapter configuration.

Also view the completed instance in the ESB console.

Figure 36: A successfully completed ESB instance using the custom JCA resource adapter to receive inbound mail messages.

Congratulations, you have now designed, implemented, and tested a real-life integration scenario using your own custom mail adapter!

Oracle’s Go-Forward Strategy for its Service Bus Portfolio

At the time of this writing, Oracle has two service buses in its product portfolio: Oracle Enterprise Service Bus and Oracle Service Bus (the product formerly known as BEA AquaLogic Service). The former includes its own set of native adapters and uses its own framework, Transport SDK, to enable the creation of custom adapters. The two buses will be consolidated and merged in later releases.

Oracle Service Bus will be the foundation for Oracle's go-forward Service Bus strategy and is being enriched with Oracle ESB features such Domain-Value Maps (DMV), XSLT support, and the JCA framework and resource adapter support. While the current OSB release (10g Release 3 at the time of writing) does not yet support custom JCA resource adapters, Oracle will rationalize all external connectivity options in its future SOA platform. That means:

Support for JCA adapters and the JCA framework
Consolidation of overlapping functions, such as the file transport in Service Bus and the file adapter in Enterprise Service Bus, and the development of a best-of-breed single option for any single target system

The current adapter offering in Oracle Enterprise Service Bus and Oracle Service Bus can be seen in the following table. The adapters are categorized by adapter type.

Adapter type	Oracle Enterprise Service Bus	Oracle Service Bus
Partner connectivity	Oracle B2B	-
Apps connectivity	EBS, PSFT, SEBL, JDE (iWay)	SmartConnect, iWay WLS Adapters
Technology adapters	Database, Oracle AQ, Socket/TCP-IP, File, FTP, JMS, MQ Series	REST/HTTP, EJB and Java callout, Email (SMTP, IMAP, POP), File, FTP, JMS, MQ Series, .NET, COM Adapters (ALBPM)
Mainframe	Oracle Mainframe Adapters (Attunity)	Tuxedo Adapters for Mainframe

Read more about Oracle’s go-forward strategy for the Service Bus product in its Statement of Direction (SOD).

Conclusion

Although Oracle Fusion Middleware ships with several adapters, those adapters might not always suffice for all your integration scenarios.

Investigate the adapter offerings by third-party vendors before building one yourself. It is also important to realize that you need to have an understanding of at least three different frameworks and how they cooperate in order to create and use a custom adapter: JCA, Adapter Framework, and the product in which you’re using the adapter. This is especially true for addressing non-functional requirements such as scalability, high-availability, security, and support for global transactions. This can be a challenging task.

The bottom line is to address these non-functional requirements as a whole before building your adapter.

Additional Information and References

Read more about Java EE Connector Architecture (JCA) at:

JSR-16 Java EE Connector Architecture 1.0 specification http://jcp.org/en/jsr/detail?id=16
JSR-112 Java EE Connector Architecture 1.5 specification http://jcp.org/en/jsr/detail?id=112

Read more about Oracle Adapters and the Adapter Framework at:

Read more about Oracle Service Bus (OSB) at OTN.

Ronald van Luttikhuizen ( ronald.vanluttikhuizen@approach-alliance.nl) is an Oracle ACE and architect at Approach Alliance ( www.approach-alliance.com), a Netherlands-based information and communications technology consultancy focusing on SOA and BI.