Migrating Resource Adapters from OC4J to WebLogic, Part 1 Outbound

Both OC4J and WebLogic server support Connector 1.5 specification. If customer's resource adapters were developed based on SPEC and don't depend on OC4J proprietary extensions or features, it would be relatively easy to migrate the adapters from OC4J to WebLogic. During migration, one of the key steps is mapping OC4J's proprietary descriptors to WebLogic's descriptors. Here in this article we will show you how to migrate the descriptors for standalone adapters.

Resource adapters can be classified into three categories: outbound, inbound or bi-directional. This article will show you how to deal with outbound case. Inbound case will be shown in next article. It would be easy to understand how to deal with bi-directional case after reading outbound case and inbound case.

l Overview of Descriptors

Many adapters may just support outbound communication from application server to EIS. The descriptor used in this scenario is oc4j-ra.xml. It contains OC4J specific configuration for outbound communication such as connection factories/pools, and should be mapped to weblogic-ra.xml.

If an adapter also supports inbound communication from EIS to application server, there is another descriptor for adapter: oc4j-connectors.xml. It defines admin objects for inbound communication, and also should be mapped to weblogic-ra.xml.

So there is just one single descriptor file used on WebLogic: weblogic-ra.xml for all types of adapters: outbound, inbound, and bidirectional.

For inbound, MDB should be used as message endpoint in standard Java EE environment. In this case, orion-ejb-jar.xml is required for the MDB (note: this file is packaged inside MDB jar, not adapter). It associates MDB with adapter, and should be mapped to weblogic-ejb-jar.xml in the MDB jar.

l Mapping for Outbound Case

Here is a sample descriptor of OC4J which show a typical configuration for outbound connection factory. It should be packaged as META-INF\oc4j-ra.xml in the RAR file.

<?xml version="1.0"?>

<oc4j-connector-factories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.oracle.com/technology/oracleas/schema/oc4j-connector-factories-10_0.xsd" schema-major-version="10" schema-minor-version="0" >

<connector-factory location="eis/fooConnectionFactory" connector-name="fooConnector">

<config-property name="serverName" value="localhost"/>

<config-property name="port" value="80"/>

<connection-pooling use="private">

<property name="minConnections" value="1" />

<property name="initial-capacity" value="1" />

<property name="maxConnections" value="10" />

</connection-pooling>

<connectionfactory-interface>foo.bar.MyConnectionFactory</connectionfactory-interface>

</connector-factory>

</oc4j-connector-factories>

One big difference is that an adapter instance is uniquely identified by connector-name on OC4J; but on WebLogic, the adapter java bean instance will be bound to JNDI and uniquely identified by its JNDI name. So, the connector-name="fooConnector" on OC4J should be mapped to <jndi-name>fooConnector</jndi-name> on WebLogic. Please note that enable-global-access-to-classes should be enabled on WebLogic in general so as to let other deployed applications to access this standalone adapter. You will see later that connector-name on OC4J and corresponding jndi-name on WebLogic is also used when associating MDB with adapter in inbound case.

On OC4J, each connection factory instance is defined by one connector-factory element. It should be mapped to outbound-resource-adapter\connection-definition-group\connection-instance element on WebLogic. There might be multiple connector-factory elements on OC4J. Correspondingly, they can be mapped to multiple connection-instance elements on WebLogic.

Each connection factory instance must have a connectionfactory-interface element. This is same for both OC4J and WebLogic. So it is just needed to map connector-factory\connectionfactory-interface on OC4J to outbound-resource-adapter\connection-definition-group\onnection-factory-interface on WebLogic.

It is same for OC4J and WebLogic that connection factory should be bind to JNDI, and the mapping is quite straightforward. The location="eis/fooConnectionFactory" defines the JNDI name for the connector-factory on OC4J and should be mapped directly to <jndi-name> element under connection-instance on WebLogic.

The mapping for config-property is also straightforward. Each property should be mapped to connection-instance\connection-properties\properties\property on WebLogic.

The mapping for connection-pooling is a little complex, since OC4J and WebLogic have different set of configurations for the connection pool and each has some options that are hard to be mapped to the options of the other. One difference is that OC4J support "shared connection pool" concept that several connection factory instances can share a single connection pool; whereas on WebLogic each connection factory instance has its own connection pool. If, for example, 2 connection factory instances on OC4J share one connection pool, it would be required to define two separate connection-instance elements on WebLogic and each connection-instance will maintain its own connection pool internally. The maxConnections can be directly mapped to max-capacity on WebLogic and keep same effect. But the minConnections and initial-capacity are a little confusing and both can be mapped to initial-capacity on WebLogic. Other configurations may not be directly mapped to WebLogic straightforwardly. The detail description of all available configuration options for WebLogic's pool can be found at " Configuring Connection Pool Parameters" http://download.oracle.com/docs/cd/E12839_01/web.1111/e13732/connect.htm#i1251021

Here is the result after performing above mapping, and the result file should be packaged as META-INF\weblogic-ra.xml in the RAR file.

<?xml version = "1.0"?>

<weblogic-connector xmlns="http://www.bea.com/ns/weblogic/90">

<jndi-name>fooConnector</jndi-name>

<enable-global-access-to-classes>true</enable-global-access-to-classes>

<outbound-resource-adapter>

<connection-definition-group>

<connection-factory-interface>foo.bar.MyConnectionFactory</connection-factory-interface>

<connection-instance>

<jndi-name>eis/fooConnectionFactory</jndi-name>

<connection-properties>

<pool-params>

<initial-capacity>1</initial-capacity>

<max-capacity>10</initial-capacity>

</pool-params>

<transaction-support>NoTransaction</transaction-support>

<properties>
<property>
<name>serverName</name>
<value>localhost</value>
</property>
<property>
<name>port</name>
<value>80</value>
</property>
</properties>
</connection-properties>

</connection-instance>

</connection-definition-group>

</outbound-resource-adapter>

</weblogic-connector>

You may have noted that WebLogic allows overriding transaction-support in weblogic-ra.xml while this is not allowed on OC4J. This allows extra useful flexibility in some cases. For example, if you have 1 connection-definition in ra.xml which supports LocalTransaction but some times you want to configure a connection factory instance and don't want it to participate in any global transaction, you can configure 2 connection-instances in weblogic-ra.xml and one as LocalTransaction while the other as NoTransaction.

l Reference

Detailed information on configuring and developing resource adapters on WebLogic is available at Programming Resource Adapters for Oracle WebLogic Server. You can find detail explanation for weblogic-ra.xml schema in appendix "A. weblogic-ra.xml Schema"