Configure resource adapters

We can configure resource adapters that comply with the Java EE Connector Architecture (JCA) specification versions 1.6, 1.5, or 1.0.

Steps

1. Edit...
   /path/to/liberty\wlp\usr\servers\server_name/server.xml

   ...and add add the jca-1.6 feature under the featureManager tag.

    <featureManager>
     <feature>jca-1.6</feature>
    </featureManager>

   Stabilized feature: The jca-1.6 feature is stabilized. We can continue to use the jca-1.6 feature. However, consider using a later JCA feature.

2. (Optional) Enable the following additional features based on the needs of the system:

   • If the resource adapter provides JMS specification interfaces, enable the jms-1.1 feature.
     <feature>jms-1.1</feature>

   • To look up connection factories and administered objects from the application, enable the jndi-1.0 feature.
     <feature>jndi-1.0</feature>

   • If the resource adapter provides activation specifications for message driven beans, enable the mdb-3.1 feature.
     <feature>mdb-3.1</feature>

   • If the resource adapter supports inbound security, enable the jcaInboundSecurity-1.0 feature.
     <feature>jcaInboundSecurity-1.0</feature>

   • If the resource adapter supports bean validation, we can enable a bean validation feature to validate the beans.
     <feature>beanValidation-1.1</feature>

3. Configure one or more resource adapters in the server.

   • Configure a standalone resource adapter by editing server.xml file.

     <resourceAdapter location="C:/adapters/MyAdapter.rar"/>

   • Configure an embedded resource adapter by editing server.xml to install an application that embeds one or more resource adapter modules. The following example assumes that the app1.ear file contains one or more embedded RAR files:
     <application location="C:/applications/app1.ear"/>

   • Allow the server to automatically configure a standalone resource adapter by dropping the RAR file in the server drop-ins folder.
     wlp/usr/servers/server-name/dropins/MyDropinAdapter.rar

   • Allow the server to automatically configure an application containing one or more embedded resource adapters by dropping the EAR file in the server drop-ins folder. The following example assumes that the app2.ear file contains one or more embedded RAR files:
     wlp/usr/servers/server-name/dropins/app2.ear

4. Start the application server. After the server is started, messages such as the following are displayed in the console.log file:
   [AUDIT ] J2CA7001I: Resource adapter MyAdapter installed in 0.495 seconds.
   [AUDIT ] J2CA7001I: Resource adapter MyDropinAdapter installed in 0.311 seconds.
   [AUDIT ] J2CA7001I: Resource adapter app1.MyEmbeddedAdapter installed in 0.247 seconds.
   [AUDIT ] J2CA7001I: Resource adapter app2.anotherEmbeddedAdapter installed in 0.518 seconds.

Example

A unique identifier for a resource adapter is necessary to identify configured instances of connection factories, administered objects, and activation specifications as being associated with an installed resource adapter. For stand-alone resource adapters, the module name is used as the identifier. For resource adapters embedded in applications, the combination of the application name plus the module name (delimited by the period character) are used as the identifier.

• Specify properties for a stand-alone resource adapter using a properties.MyAdapter subelement that includes the resource adapter identifier, MyAdapter:

  <resourceAdapter location="C:/adapters/MyAdapter.rar">
    <properties.MyAdapter logFile="${server.output.dir}/logs/myAdapter.log"/>
  </resourceAdapter>

• Associate a connection factory with a stand-alone resource adapter using a properties.MyAdapter subelement that includes the resource adapter identifier, MyAdapter:

  <resourceAdapter location="C:/adapters/MyAdapter.rar"/>
  <connectionFactory jndiName="eis/cf">
   <properties.MyAdapter serverName="localhost" portNumber="1234"/>
  </connectionFactory>

• Associate a connection factory with a resource adapter MyEmbeddedAdapter, which is enabled in the app1 application, using a properties.app1.MyEmbeddedAdapter subelement:

  <application location="C:/applications/app1.ear"/>
  <connectionFactory jndiName="eis/cf">
   <properties.app1.MyEmbeddedAdapter serverName="localhost" portNumber="1234"/>
  </connectionFactory>

• In some cases, the module name is not sufficiently unique to serve as the identifier. This might happen, for example, if we install two different versions of the same resource adapter.

  Alternately, the module name might be unique, but undesirable for use in configuration because it is lengthy or contains non-alphanumeric characters. We can override the resource adapter identifier by specifying the id attribute.

  The following example demonstrates how to override the identifier for stand-alone resource adapters:

  <resourceAdapter id="MyAdapterV1" location="C:/adapters/version-1.0/MyAdapter.rar"/>
  <resourceAdapter id="MyAdapterV2" location="C:/adapters/version-2.0/MyAdapter.rar"/>
  <connectionFactory jndiName="eis/cf1">
   <properties.MyAdapterV1 serverName="localhost" portNumber="1234"/>
  </connectionFactory>
  <connectionFactory jndiName="eis/cf2">
   <properties.MyAdapterV2 serverName="localhost" portNumber="1234"/>
  </connectionFactory>

• The following example demonstrates how to override the identifier for a resource adapter that is embedded in an application. The example changes the identifier to MyEmbeddedRA:

  <application location="C:/applications/app1.ear">
   <resourceAdapter id="MyEmbeddedAdapter" alias="MyEmbeddedRA"/>
  </application>
  <connectionFactory jndiName="eis/cf">
   <properties.app1.MyEmbeddedRA serverName="localhost" portNumber="1234"/>
  </connectionFactory>

• Compute the module name for embedded resource adapters, the<module-name> entry in the resource adapter deployment descriptor (ra.xml) takes precedence as the module name. For example, given the following definition in ra.xml:

  <connector ...> 
      <module-name>MyRARModule</module-name> 
  </connector>

  ...the module name would be set to "MyRARModule".

  If the module name is absent from the connector deployment descriptor, the short form of the URI referring to the resource adapter module in the application deployment descriptor (application.xml) is used. For example, given the following module definition in application.xml:

  <module>         
      <connector>connectors/MyRARModule.rar</connector>     
  </module>

  the module name would be computed as "MyRARModule".

  If multiple resource adapters are embedded in an application and define the same <module-name> value, the first one listed in application.xml uses that module name. The module names of the other connectors with that same conflicting name are calculated from the full form of the URI with all / (forward slash) characters converted to a period (.). For example, if two connectors were embedded in an application both containing the following definition in ra.xml:

  <connector ...> 
      <module-name>MyRARModule</module-name> 
  </connector>

  and the following definitions in application.xml:

  <module>         
      <connector>subfolder1/connector1.rar</connector>     
  </module>     
  <module>         
      <connector>subfolder2/connector2.rar</connector>     
  </module>

  The module name for the first connector would be "MyRARModule" and the module name for the second would be "subfolder2.connector2.rar"