IronJacamar 1.2 User's Guide

The Java Connector Architecture (JCA) defines a standard architecture for connecting the Java EE platform to heterogeneous Enterprise Information Systems (EIS). Examples of EISs include Enterprise Resource Planning (ERP), mainframe transaction processing (TP), databases and messaging systems.

The connector architecture defines a set of scalable, secure, and transactional mechanisms that enable the integration of EISs with application servers and enterprise applications.

The connector architecture also defines a Common Client Interface (CCI) for EIS access. The CCI defines a client API for interacting with heterogeneous EISs.

The connector architecture enables an EIS vendor to provide a standard resource adapter for its EIS. A resource adapter is a system-level software driver that is used by a Java application to connect to an EIS. The resource adapter plugs into an application server and provides connectivity between the EIS, the application server, and the enterprise application. The resource adapter serves as a protocol adapter that allows any arbitrary EIS communication protocol to be used for connectivity. An application server vendor extends its system once to support the connector architecture and is then assured of seamless connectivity to multiple EISs. Likewise, an EIS vendor provides one standard resource adapter which has the capability to plug in to any application server that supports the connector architecture.

1.2. Overview

The Java EE Connector Architecture features three different types of resource adapters

• Outbound: The resource adapter allows the application to communicate to the Enterprise Information System (EIS).
• Inbound: The resource adapter allows messages to flow from the Enterprise Information System (EIS) to the application.
• Bi-directional: The resource adapter features both an outbound and an inbound part.

For more information about Java EE Connector Architecture see the specification.

1.2.1. Outbound resource adapter

The Java Connector Architecture specification consists of a number of outbound components:

The application uses the

• ConnectionFactory: The connection factory is looked up in Java Naming and Directory Interface (JNDI) and is used to create a connection.
• Connection: The connection contains the Enterprise Information System (EIS) specific operations.

The resource adapter contains

• ManagedConnectionFactory: The managed connection factory creates managed connections.
• ManagedConnection: The managed connection represents a physical connection to the target Enterprise Information System (EIS). The managed connection notifies the application server of events such as connection closed and connection error.

IronJacamar - the application server - contains

• ConnectionManager: The connection manager handles all managed connections in regards to pooling, transaction and security.
• ConnectionEventListener: The connection event listener allows the connection manager to know the status of each managed connection.

1.2.2. Inbound resource adapter

The Java Connector Architecture specification consists of a number of inbound components:

The application uses the

• ActivationSpec: The activation specification specifies the different properties that the application is looking for from the resource adapter and hence the Enterprise Information System (EIS). This specification can be hidden from the user by a facade provided by the application server.

The resource adapter contains

• ResourceAdapter: The resource adapter provides the activation point for inbound communication.
• Resource adapter specific: The resource adapter specific code handles communication with the Enterprise Information System (EIS) and deliver messages through the MessageEndpointFactory.

IronJacamar - the application server - contains

• MessageEndpointFactory: The MessageEndpointFactory is registered with the ResourceAdapter instance and creates the MessageEndpoint instances.
• MessageEndpoint: The MessageEndpoint contains the actual message from the Enterprise Information System (EIS) which the application uses. This could for example be a message driven Enterprise JavaBean (EJB/MDB).

The official IronJacamar project page is http://www.ironjacamar.org/ where you can download the software.

ironjacamar-<major>.<minor>.<patch>.<identifier>
      

ironjacamar-1.2.0.Final.tar.gz
      

http://github.com/ironjacamar/ironjacamar
      

Once you have downloaded the distribution you need to install it in a location of your choice.

tar xzf ironjacamar-1.2.0.Final.tar.gz
     

ironjacamar-1.2.0.Final
     

unzip ironjacamar-1.2.0.Final.zip
     

ironjacamar-1.2.0.Final
     

./as-upgrader.sh 1.2.0.Final /path/to/wildfly/installation
     

The configuration for the IronJacamar container is mainly located under the config/ directory.

remote.access=true
remote.port=1302
        

org.jboss.jca.core.connectionmanager.pool.mcp.LeakDumperManagedConnectionPool
        

-Dironjacamar.mcp=org.jboss.jca.core.connectionmanager.pool.mcp.LeakDumperManagedConnectionPool
-Dironjacamar.leaklog=leaks.txt
        

config/logging.properties
      

config/transaction.xml
      

config/bootstrap/jca.xml
        

<bean name="RAConfiguration"

      class="org.jboss.jca.deployers.fungal.RAConfiguration">

  <property name="ArchiveValidation">true</property>

  <property name="ArchiveValidationFailOnWarn">false</property>

  <property name="ArchiveValidationFailOnError">true</property>

  <property name="BeanValidation">true</property>

  <property name="PrintStream">

    <inject bean="JBossStdioContext" property="Out"/>

  </property>

  <property name="DefaultBootstrapContext">

    <inject bean="DefaultBootstrapContext"/>

  </property>

  <property name="JndiStrategy"><inject bean="JndiStrategy"/></property>

  <property name="TransactionManager">

    <inject bean="RealTransactionManager"/>

  </property>

  <property name="MetadataRepository"><inject bean="MDR"/></property>

</bean>

 

          

<bean name="RADeployer"

      interface="com.github.fungal.spi.deployers.Deployer" 

      class="org.jboss.jca.deployers.fungal.RADeployer">

  <property name="Configuration"><inject bean="RAConfiguration"/></property>

  <depends>BeanValidation</depends>

  <depends>JBossStdioContextSelector</depends>

</bean>

 

          

<bean name="RaXmlDeployer"

      interface="com.github.fungal.spi.deployers.Deployer" 

      class="org.jboss.jca.deployers.fungal.RaXmlDeployer">

  <property name="Configuration"><inject bean="DeployerConfiguration"/></property>

  <property name="Kernel"><inject bean="Kernel"/></property>

  <depends>BeanValidation</depends>

  <depends>JBossStdioContextSelector</depends>

</bean>

 

          

<bean name="RAActivator" 

      class="org.jboss.jca.deployers.fungal.RAActivator">

  <property name="Configuration"><inject bean="RAConfiguration"/></property>

  <property name="Kernel"><inject bean="Kernel"/></property>

  <property name="ExcludeArchives">

    <set elementClass="java.lang.String">

      <value>jdbc-local.rar</value>

      <value>jdbc-xa.rar</value>

    </set>

  </property>

  <depends>BeanValidation</depends>

  <depends>JBossStdioContextSelector</depends>

</bean>

 

          

<deployment>



  <!-- DistributedWorkManagerThreadGroupSocket -->

  <bean name="DistributedWorkManagerThreadGroupSocket"

        class="java.lang.ThreadGroup">

    <constructor>

      <parameter>dwm</parameter>

    </constructor>

    <ignoreStop/>

    <ignoreDestroy/>

  </bean>



  <!-- DistributedWorkManagerThreadFactorySocket -->

  <bean name="DistributedWorkManagerThreadFactorySocket"

        interface="java.util.concurrent.ThreadFactory"

        class="org.jboss.threads.JBossThreadFactory">

    <constructor>

      <parameter><inject bean="DistributedWorkManagerThreadGroupSocket"/></parameter>

      <parameter>false</parameter>

      <parameter>5</parameter>

      <parameter>work</parameter>

      <parameter><null/></parameter>

      <parameter><null/></parameter>

    </constructor>

  </bean>



  <!-- DistributedWorkManagerShortRunningThreadPoolSocket -->

  <bean name="DistributedWorkManagerShortRunningThreadPoolSocket"

        class="org.jboss.threads.QueueExecutor">

    <constructor>

      <!-- Core threads -->

      <parameter>20</parameter>

      <!-- Max threads -->

      <parameter>100</parameter>

      <!-- 60 seconds keepalive -->

      <parameter>60</parameter>

      <parameter><inject bean="KeepAliveTimeUnit"/></parameter>

      <!-- Queue size -->

      <parameter>1024</parameter>

      <!-- Thread factory -->

      <parameter><inject bean="DistributedWorkManagerThreadFactorySocket"/></parameter>

      <!-- Blocking -->

      <parameter>true</parameter>

      <!-- Handoff executor -->

      <parameter><inject bean="RejectingExecutor"/></parameter>

    </constructor>

    <destroy method="shutdown"/>

  </bean>



  <!-- DistributedWorkManagerPolicySocket -->

  <bean name="DistributedWorkManagerPolicySocket"

        class="org.jboss.jca.core.workmanager.policy.Always">

  </bean>



  <!-- DistributedWorkManagerSelectorSocket -->

  <bean name="DistributedWorkManagerSelectorSocket"

        class="org.jboss.jca.core.workmanager.selector.FirstAvailable">

  </bean>



  <!-- DistributedWorkManagerTransportSocket -->

  <bean name="DistributedWorkManagerTransportSocket"

        class="org.jboss.jca.core.workmanager.transport.remote.socket.SocketTransport">

    <!-- The id -->

    <property name="Id">1</property>



    <!-- The executor -->

    <property name="ExecutorService">

      <inject bean="Kernel" property="ExecutorService"/>

    </property>

    

    <!-- The host -->

    <property name="Host">127.0.0.1</property>

    

    <!-- The port -->

    <property name="Port">1299</property>

    

    <!-- The peers -->

    <property name="Peers">

      <set class="java.util.HashSet" 

           elementClass="java.lang.String">

        <value>localhost:1300</value>

      </set>

    </property>



    <start method="startup"/>

    <stop method="shutdown"/>

  </bean>



  <!-- PicketBox -->

  <bean name="PicketBoxSocket"

        class="org.jboss.jca.core.security.picketbox.PicketBoxSecurityIntegration">

  </bean> 



  <!-- DistributedWorkManagerSocket -->

  <bean name="DistributedWorkManagerSocket"

        interface="org.jboss.jca.core.api.workmanager.DistributedWorkManager"

        class="org.jboss.jca.core.workmanager.DistributedWorkManagerImpl">



    <!-- The name -->

    <property name="Name">DWM-Socket</property>



    <!-- The short running thread pool -->

    <property name="ShortRunningThreadPool">

       <inject bean="DistributedWorkManagerShortRunningThreadPoolSocket"/>

    </property>



    <!-- The XA terminator -->

    <property name="XATerminator">

       <inject bean="TransactionIntegration" property="XATerminator"/>

    </property>



    <!-- The callback security module -->

    <property name="CallbackSecurity">

       <inject bean="Callback"/>

    </property>



    <!-- The security integration module -->

    <property name="SecurityIntegration">

       <inject bean="PicketBoxSocket"/>

    </property>



    <!-- The policy -->

    <property name="Policy">

       <inject bean="DistributedWorkManagerPolicySocket"/>

    </property>



    <!-- The selector -->

    <property name="Selector">

       <inject bean="DistributedWorkManagerSelectorSocket"/>

    </property>



    <!-- The transport -->

    <property name="Transport">

       <inject bean="DistributedWorkManagerTransportSocket"/>

    </property>



    <!-- <destroy method="shutdown"/> -->

  </bean>



  <!-- DistributedBootstrapContextSocket -->

  <bean name="DistributedBootstrapContextSocket"

        interface="org.jboss.jca.core.api.bootstrap.CloneableBootstrapContext"

        class="org.jboss.jca.core.bootstrapcontext.BaseCloneableBootstrapContext">

    <property name="Name">DWMBC-Socket</property>

    <property name="TransactionSynchronizationRegistry">

       <inject bean="TransactionSynchronizationRegistry"/>

    </property>

    <property name="WorkManagerName">

       <inject bean="DistributedWorkManagerSocket" property="Name"/>

    </property>

    <property name="XATerminator">

       <inject bean="TransactionIntegration" property="XATerminator"/>

    </property>

  </bean>



</deployment>



          

javax.resource.spi.work.WorkContextProvider
        

          

<!-- SubjectFactory -->

<bean name="DefaultSecurityDomain"

      interface="org.jboss.jca.core.spi.security.SubjectFactory"

      class="org.jboss.jca.core.security.DefaultSubjectFactory">

  <property name="SecurityDomain">DefaultSecurityDomain</property>

  <property name="UserName">user</property>

  <property name="Password">password</property>

</bean>

           

        

config/bootstrap/ds.xml
      

config/bootstrap/
      

system/web.xml
      

<bean name="WebServer" class="org.jboss.jca.web.WebServer">

  <property name="Host">${iron.jacamar.bindaddress:localhost}</property>

  <property name="Port">8080</property>

  <property name="ExecutorService"><inject bean="Kernel" property="ExecutorService"/></property>

</bean>



      

system/
      

lib/jetty
      

The IronJacamar distribution contains a deploy/ directory where all deployments should be deployed to.

[jpederse@localhost]$ jar tf ra.rar
META-INF/ra.xml
readme.html
ra.jar
images/icon.jpg
win.dll
linux.so
 
      

cp example.rar ironjacamar-1.2.0.Final/deploy
     

copy example.rar ironjacamar-1.2.0.Final\deploy
     

<resource-adapters>

  <resource-adapter>

    <archive>example.rar</archive>

    <connection-definitions>

      <connection-definition jndi-name="java:/eis/example" class-name="com.example.ra.MCF"/>

    </connection-definitions>

  </resource-adapter>

</resource-adapters>



     

java:/eis/<deploymentName>
     

java:/eis/ao/<deploymentName>
     

public boolean isValid(Object c) throws ResourceException;
            

public void close(Object c) throws ResourceException;
            

<recovery>
   <recovery-plugin>com.mycompany.myproject.RecoveryPluginImpl</recovery-plugin>
</recovery>
            

cp postgres-xa-ds.xml ironjacamar-1.2.0.Final/deploy
      

copy postgres-xa-ds.xml ironjacamar-1.2.0.Final\deploy
      

The IronJacamar Eclipse plugin features development tools used for developing resource adapter applications for the IronJacamar standalone distribution, WildFly or JBoss Enterprise Application Platform 6+.

The plugin allows you to

cp ironjacamar-eclipse.jar $ECLIPSE_HOME/plugins
    

copy ironjacamar-eclipse.jar %ECLIPSE_HOME%\plugins
    

9.2. Configuration of the plugin

Open "Window->Preferences" and select the IronJacamar category.

The IronJacamar home setting must point to the root directory of the IronJacamar installation, like

/opt/ironjacamar-1.2.0.Final
    

in order to configure the plugin.

The IronJacamar Eclipse plugin can deploy to a remote IronJacamar instance, by specifying the host and port settings.

9.3. The toolbar

The IronJacamar Eclipse plugin provides a toolbar with deployment functionality.

9.4. The menu

The IronJacamar Eclipse plugin provides a menu with validation and deployment functionality.

9.5. Creating a new IronJacamar project

A new IronJacamar project can be created by selecting File->New->Project... and go to the IronJacamar category.

Choose "IronJacamar 1.1 project" and follow the instructions to generate your resource adapter.

9.5.1. Project and package name

Sepcify the project name and package name for the project. You can also select the JCA specification version, the type of the resource adapter (Outbound/Inbound/Bidirectional), the transaction support level, if the resource adapter will support reauthentication and if annotations used be used for a JCA 1.6+ based resource adapter.

9.5.2. Creating a ResourceAdapter

You can choose to include a ResourceAdapter class if the JCA profile version is 1.5, 1.6 or 1.7

9.5.3. Creating a ManagedConnectionFactory

If the project is Outbound or Bidirectional then you can fill in the information for the outbound components.

9.5.4. Creating a MessageListener

If the project is Inbound or Bidirectional then you can fill in the information for the message listener and activation specification components.

9.5.5. Creating an AdminObject

This wizard creates an AdminObject for the project.

9.5.6. Selecting the build environment

This wizard will let you choose the build environment to use for your project. Currently IronJacamar supports the Apache Ant, Apache Ant + Apache Ivy or Maven build environments. If Apache Ant is selected, all library files will be copied from your IronJacamar installation.

Note

Please make sure you have installed the Eclipse M2E plugin if you select Apache Maven as your build environment.

9.7. Deploying an IronJacamar project

The IronJacamar Eclipse plugin provides a way to deploy files to an IronJacamar server.

Note

Before any deploy operation, the IronJacamar server needs to be started, otherwise it will lead to an error dialog. Please refer to this for detail on how to start the IronJacamar server

9.7.1. Deploying a RAR file to an IronJacamar server

Select the IronJacamar project you just created. The Deploy drop down command in the toolbar will be enabled. Click on the command and select 'Deploy rar'.

Another way to deploy the RAR file is to right click on the project, and select IronJacamar->Deploy->Deploy rar from context menu

The command will build the RAR file first if it doesn't exist, then try to connect the IronJacamar server to deploy it.

9.7.2. Generate the -ra.xml and deploy it to IronJacamar server

Select the IronJacamar project you just created. The Deploy drop down command in the toolbar will be enabled. Click on the command and select 'Deploy -ra.xml'.

Another way to generate the -ra.xml file is to right click on the project, and select IronJacamar->Deploy->Deploy -ra.xml from context menu.

The command will build the RAR file first if it does not exist, then pop up a wizard to generate the -ra.xml according to the RAR file.

In the first wizard page, selects version of the resource adapter. Some configurations may not be available when version is changed.

In the general information page, set up the transaction support, bootstrap context, bean validation groups and id if the version is 1.1+.

From IronJacamar 1.1, a workmanager tab is added to configure workmanager security mappings.

There is a wizard page for each ManagedConnectionFactory if the resource adapter is outbound or bidirectional.

The ManagedConnectionFactory can be activated by selecting the 'Activate' checkbox.

Configure connection pool in the 'pool configuration' tab.

Configure XA connection pool in the 'XA pool' sub tab.

From IronJacamar 1.1 on, a capacity sub tab is added in 'pool configuration' tab to configure policy of connection pool

There is a wizard page for each AdminObject if the resource adapter includes one or more instances.

The AdminObject can be activated by selecting the 'Activate' checkbox.

There is a miscellaneous page also.

If the Deploy RAR first option is selected, the plugin will try to deploy the RAR file to the IronJacamar server first, then deploy the generated -ra.xml file.