| Developer & Architect: SOA |
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.
Published March 2009
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.
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:
These components – together with their relation to SOA Suite components and EIS systems – are shown in the following figure.
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:
Important enhancements made in version 1.5 include:
The following interaction patterns between application components and EIS are possible using JCA 1.5:
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.
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:
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:
The next section includes diagrams that illustrate the relationships and interactions between the JCA interfaces and our custom resource adapter implementation.
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:
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:
This section provides instructions for all three environments.
The sample JDeveloper application workspace – regardless of the chosen environment – contains the following projects:
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
Deploy and test the JCA resource adapter for Oracle Application Server 10g
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
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.
We’ll perform the following tasks to use our custom adapter from Oracle ESB through the Adapter Framework:
XML Record Converter
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.
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.
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.
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.
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.
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.
Now we can start defining our custom adapter!
For simplicity we’ll output the mail message as an XML file to the local file system using an outbound file adapter.
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.
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
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:
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.
Read more about Oracle’s go-forward strategy for the Service Bus product in its Statement of Direction (SOD).
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:
Read more about Oracle Adapters and the Adapter Framework at:
Read more about Oracle Service Bus (OSB) at OTN.
Read more about Oracle Enterprise Service Bus (OESB) at OTN.
Ronald van Luttikhuizen ( email@example.com) 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.