IronJacamar 1.1 User's Guide

The Java Connector Architecture 1.7 specification adds the following areas:

1.1. What's New

1.1.1. Java Connector Architecture 1.7
1.1.2. Java Connector Architecture 1.6

1.2. Overview

1.2.1. Outbound resource adapter
1.2.2. Inbound resource adapter

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.1. What's New

1.1.1. Java Connector Architecture 1.7

Adds an activation name for message endpoints to uniquely identify them
Deployment annotations for connection factories and administration objects

Note

The deployment annotations are only meant for developer usage, and should not be used in test or production environments.

The IronJacamar standalone and embedded distributions doesn't support these annotations.

1.1.2. Java Connector Architecture 1.6

The Java Connector Architecture 1.6 specification adds the following major areas:

Ease of Development: The use of annotations reduces or completely eliminates the need to deal with a deployment descriptor in many cases. The use of annotations also reduces the need to keep the deployment descriptor synchronized with changes to source code.
Generic work context contract: A generic contract that enables a resource adapter to control the execution context of a Work instance that it has submitted to the application server for execution.
Security work context: A standard contract that enables a resource adapter to establish security information while submitting a Work instance for execution to a WorkManager and while delivering messages to message endpoints residing in the application server.
Standalone Container Environment: A defined set of services that makes up a standalone execution environment for resource adapters.

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).

Chapter 2. Download

The download location is: http://www.ironjacamar.org/downloads/

2.1. Download
2.2. Maven repository
2.3. Git Access

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

2.1. Download

Each release is labelled with a version number and an identifier.

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

where

Major: The major version number. Signifies major changes in the implementation.
Minor: The minor version number. Signifies functional changes to a major version.
Patch: The patch version number. Signifies a binary compatible change to a minor version.
Identifier: The identifier. Identifies the level of the quality of the release.
- Final: Stable release
- CR: Candidate for Release quality. The implementation is functional complete.
- Beta: Beta quality. The implementation is almost functional complete.
- Alpha: Alpha quality. The implementation is a snapshot of the development.

An example

ironjacamar-1.1.0.Final.tar.gz

which is a stable release of the project.

2.2. Maven repository

The IronJacamar distribution is deployed to the JBoss Nexus repository.

Repository: http://repository.jboss.org/nexus/content/groups/public/

Group id: org.jboss.ironjacamar

Table 2.1. Maven artifacts

Artifact	Description
`ironjacamar-arquillian-embedded`	The Arquillian extension for the embedded module
`ironjacamar-arquillian-embedded-byteman`	The Arquillian/Byteman extension for the embedded module
`ironjacamar-as`	WildFly integration tools
`ironjacamar-codegenerator`	The code generator
`ironjacamar-common-api`	The API for the common module
`ironjacamar-common-impl`	The implementation for the common module
`ironjacamar-common-spi`	The SPI for the common module
`ironjacamar-core-api`	The API / SPI for the core module
`ironjacamar-core-impl`	The implementation for the core module
`ironjacamar-depchain`	The dependency chain for the IronJacamar container
`ironjacamar-deployers-common`	The common classes for the deployer chains
`ironjacamar-deployers-fungal`	The deployers for the Fungal kernel based setup
`ironjacamar-embedded`	The embedded module
`ironjacamar-jdbc`	The core library for the JDBC resource adapters
`ironjacamar-spec-api`	The Java EE Connector Architecture 1.7 API
`ironjacamar-test-eis`	The Enterprise Information System test server
`ironjacamar-validator`	The validator module
`ironjacamar-validator-ant`	The Apache Ant tasks for the validator module
`ironjacamar-validator-cli`	The command line interface for the validator module
`jdbc-local`	A JDBC resource adapter backing standard datasources
`jdbc-xa`	A JDBC resource adapter backing XA datasources

2.3. Git Access

If you want to experiment with the latest developments you may checkout the latest code from Git. Be aware that the information provided in this manual might then not be accurate.

The Git repository is located at:

http://github.com/ironjacamar/ironjacamar

You can find additional information about this in the developer guide.

Chapter 3. Installation

Extract the distribution using

3.1. Compressed Tape Archive (.tar.gz)
3.2. Zip Archive (.zip)
3.3. Directory structure
3.4. WildFly

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

3.1. Compressed Tape Archive (.tar.gz)

tar xzf ironjacamar-1.1.0.Final.tar.gz

The distribution will be located in a directory named

ironjacamar-1.1.0.Final

3.2. Zip Archive (.zip)

Extract the distribution using

unzip ironjacamar-1.1.0.Final.zip

or any program capable of handling Zip archives such as WinZip and WinRar.

The distribution will be located in a directory named

ironjacamar-1.1.0.Final

3.3. Directory structure

The IronJacamar container has the following directory structure:

bin: Contains the scripts that starts the container.
config: Contains the configuration of the container.
deploy: Contains user deployments.
doc: Contains the documentation.
lib: Contains all the libraries needed by the container.
log: Contains the log files for the container.
system: Contains system deployments.
tmp: Contains temporary files.

3.4. WildFly

The IronJacamar provides the Java EE Connector Architecture (JCA) container for WildFly 8 and future versions.

The container can be updated in WildFly by using the as-upgrader.sh script in the doc/as directory. This will allow an easy installation of IronJacamar patch releases to fix bugs in the application server environment.

The script can be used, like:

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

where 1.1.0.Final is the version identifier of the IronJacamar container and the path points to the top-level directory of the WildFly installation. You can also use 1.1.1-SNAPSHOT in order to upgrade to a patch snapshot build.

You can get an overview of all IronJacamar releases by searching our Nexus repository.

Warning

Make sure that you understand the version policies specified in the developer guide before upgrading

Chapter 4. Configuration

4.1. IronJacamar server

4.1.1. Using the leak detector pool
4.1.2. Allow obtaining connections during MARKED_FOR_ROLLBACK
4.1.3. Disable enlistment trace
4.1.4. Disable delistResource calls

4.2. Logging service

4.3. Transaction service

4.4. JCA

4.4.1. Deployer
4.4.2. Work manager
4.4.3. Security

4.5. Datasources

4.6. Web server

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

4.1. IronJacamar server

The IronJacamar server can be configured by including an ironjacamar.properties file next to the ironjacamar-sjc.jar in the bin/ directory.

This file will allow to override the core options given to the kernel environment, if multiple instances of the IronJacamar container are going to run on the same machine, and network interface.

The options available

Table 4.1. IronJacamar options

Property	Type	Description
`name`	`String`	The name of the IronJacamar configuration
`management`	`boolean`	Should management be enabled
`parallel.deploy`	`boolean`	Should parallel deployment be enabled
`remote.access`	`boolean`	Should remote access be enabled
`remote.port`	`int`	The port for remote access
`remote.jmx.access`	`boolean`	Should remote access via JMX be enabled
`use.platform.mbeanserver`	`boolean`	Should the platform MBeanServer be used for management
`bean.management`	`boolean`	Should management for all beans be enabled

An example of an ironjacamar.properties file:

remote.access=true
remote.port=1302

4.1.1. Using the leak detector pool

IronJacamar features a connection pool implementation, which keeps track of connection allocations, and their release in order to provide feedback if a connection is obtained, but never released by the application. This will cause leaks, and lead to applications not being able to obtain any connections.

The leak detector pool provides a stack trace of the leaked connection allocation either during shutdown of the pool, or once the pool is flush using a flush strategy which kills all active connections.

The leak detector pool is configured using the ironjacamar.mcp system property with a value of

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

This configuration applies to all connection pools used by IronJacamar.

The system property ironjacamar.leaklog can be used to have the leaks dumped out into a special file separate from the logging setup.

An example

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

4.1.2. Allow obtaining connections during MARKED_FOR_ROLLBACK

IronJacamar doesn't allow to obtain a connection once a transaction is in MARKED_FOR_ROLLBACK mode. This allows the container to fail eagerly, since any work after that point is wasted anyway.

However, certain applications depends on getting a connection to perform work.

IronJacamar has a system property called ironjacamar.allow_marked_for_rollback which can be set to true to enable this scenario.

Warning

This should not be considered best practice, and the application in question should be fixed by checking the transaction status.

4.1.3. Disable enlistment trace

IronJacamar records transaction enlistment traces in order to help to locate error situations that happens during enlistment of XAResource instances.

This has a performance overhead of course, so in certain situations you may want to disable these traces.

IronJacamar has a system property called ironjacamar.disable_enlistment_trace which can be set to true which does this.

Warning

By disabling the enlistment trace tracking down errors during transaction enlistment will become much more difficult. So, only add this system property if you know what you are doing.

4.1.4. Disable `delistResource` calls

IronJacamar calls transaction.enlistResource(xaResource) for the ManagedConnection when it is enlisting in the transaction.

IronJacamar will also call transaction.delistResource(xaResource, flag) once the ManagedConnection should be disassociated with the transaction. This typically happens on the transaction boundary (beforeCompletion) before the connection is returned to the pool (afterCompletion). This is done as part of the transaction specification contract.

However, in certain scenarios you may want to disable this call, as other Synchronization objects may still want the connection enlisted in the transaction, and hence it depends on the ordering of these objects.

IronJacamar has a system property called ironjacamar.no_delist_resource which is a ',' separated list of pool names where delistResource shouldn't be called. Disabling the delistResource call for all pools can be done by defining ironjacamar.no_delist_resource_all.

Warning

By disabling the delistResource call it is up to the resource manager and transaction manager to make sure that the connection is delisted from the transaction in all cases.

4.2. Logging service

The IronJacamar container uses JBoss Logging framework as the implementation.

The configuration is done in the

config/logging.properties

The IronJacamar container uses Narayana its transaction implementation.

Consult the JBoss Logging documentation on how the service can be configured.

4.3. Transaction service

The configuration is done in the

config/transaction.xml

Consult the Narayana documentation on how the service can be configured.

4.4. JCA

4.4.1. Deployer

The IronJacamar deployer is configured in the

config/bootstrap/jca.xml

The configuration of the resource adapter deployer chain is handled by a org.jboss.jca.deployers.fungal.RAConfiguration bean.

4.4.1.1. Configuration






<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>

Table 4.2. Resource adapter deployer configuration

Property	Type	Description
`ArchiveValidation`	`boolean`	Toggle archive validation for the deployment units. Default: `true`
`ArchiveValidationFailOnWarn`	`boolean`	Should an archive validation warning report fail the deployment. Default: `false`
`ArchiveValidationFailOnError`	`boolean`	Should an archive validation error report fail the deployment. Default: `true`
`BeanValidation`	`boolean`	Toggle bean validation (JSR-303) for the deployment units. Default: `true`
`DefaultBootstrapContext`	`org.jboss.jca.core.api.bootstrap.CloneableBootstrapContext`	Specifies the default bootstrap context for resource adapters
`BootstrapContexts`	`Map<String, org.jboss.jca.core.api.bootstrap.CloneableBootstrapContext>`	Bootstrap context map (unique name to a cloneable bootstrap context) which allows developers to bind (through `ironjacamar.xml`) their resource adapter to a specific bootstrap context instance.
`PrintStream`	`java.io.PrintStream`	Specifies which print stream that should be used to handle the `LogWriter`s
`MetadataRepository`	`org.jboss.jca.core.spi.mdr.MetadataRepository`	The metadata repository
`ResourceAdapterRepository`	`org.jboss.jca.core.spi.rar.ResourceAdapterRepository`	The resource adapter repository
`ScopeDeployment`	`boolean`	Should each deployment be scoped (isolated) from the container. This feature allows deployment of libraries of a different version than used in the container environment. Default: `false`
`JndiStrategy`	`org.jboss.jca.core.spi.naming.JndiStrategy`	Specifies the JNDI strategy policy for binding the connection factories into the naming environment The JNDI strategies are located in the `org.jboss.jca.core.naming` package `NoopJndiStrategy`: A no operation JNDI strategy which doesn't bind/unbind any objects `SimpleJndiStrategy`: A simple JNDI strategy which can bind/unbind a single connection factory `ExplicitJndiStrategy`: A JNDI strategy which can requires explicit JNDI names to bind/unbind a connection factory

4.4.1.2. Resource adapter deployer

The initial deployer for resource adapter archives is handled by a org.jboss.jca.deployers.fungal.RADeployer 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>

This deployer will register the resource adapters with the metadata repository in the system.

Table 4.3. Resource adapter deployer

Property	Type	Description
`Configuration`	`org.jboss.jca.deployers.fungal.RAConfiguration`	The configuration for the deployer

4.4.1.3. Resource adapter metadata deployer

The deployer for deploying our -ra.xml deployment descriptor is handled by a org.jboss.jca.deployers.fungal.RaXmlDeployer bean.

The deployment descriptor is defined by the resource-adapters-1_0.xsd and resource-adapters-1_1.xsd schemas.






<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>

This deployer will activate resource adapters based on the deployment information.

Table 4.4. Resource adapter metadata deployer

Property	Type	Description
`Configuration`	`org.jboss.jca.deployers.fungal.RAConfiguration`	The configuration for the deployer

4.4.1.4. Resource adapter activator

The deployer chain features an activator for resource adapter archives is handled by the org.jboss.jca.deployers.fungal.RAActivator 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>

This activator will activate any resource adapters which hasn't been activated yet unless they are in the excluded list.

Table 4.5. Resource adapter activator

Property	Type	Description
`Configuration`	`org.jboss.jca.deployers.fungal.RAConfiguration`	The configuration for the deployer
`Enabled`	`boolean`	Should the activator be enabled. Default is `true`
`Kernel`	`com.github.fungal.api.Kernel`	The kernel instance
`ExcludeArchives`	`java.util.Set`	A set of resource adapter archives which should be excluded from activation

4.4.2. Work manager

IronJacamar features a standard work manager on its default setup using one thread pool for short running jobs, and one thread pool for long running jobs identified by the HintsContext.LONGRUNNING_HINT with a value of true.

The configuration of the work manager and the necessary components can be viewed in the jca.xml file.

4.4.2.1. Distributed work manager

A distributed work manager is a work manager instance, which is able to reschedule work execution on another work manager instance on the network.

The distributed work manager has three additional components

Policy -- When to distribute the work instance
Selector -- To which work manager instance
Transport -- How the work instance is transferred

to control the distribution process.

Supported policies

Never -- org.jboss.jca.core.workmanager.policy.Never
Never the distribute the Work instance to another node.
Always -- org.jboss.jca.core.workmanager.policy.Always
Always the distribute the Work instance to another node.
WaterMark -- org.jboss.jca.core.workmanager.policy.WaterMark
Distribute the Work instance to another node based on how many free worker threads the current node has available.

Supported selectors

FirstAvailable -- org.jboss.jca.core.workmanager.selector.FirstAvailable
Select the first available node in the list
PingTime -- org.jboss.jca.core.workmanager.selector.PingTime
Select the node with the lowest ping time
MaxFreeThreads -- org.jboss.jca.core.workmanager.selector.MaxFreeThreads
Select the node with highest number of free worker threads

Supported transports

Socket -- org.jboss.jca.core.workmanager.transport.remote.socket.SocketTransport
Communication based on java.net.Socket, and hence TCP/IP
JGroups -- org.jboss.jca.core.workmanager.transport.remote.jgroups.JGroupsTransport
Communication based on the JGroups framework, and hence UDP (by default)

Below is an example of a socket based configuration where two instances localhost:1299 and localhost:1300 communicates, taken from the IronJacamar test suite.




<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>



  <!-- 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 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>

4.4.3. Security

The Java EE Connector Architecture 1.6 specification allows units of javax.resource.spi.Work to be executed in a specific security context.

This is done through the use of Java Authentication Service Provider Interface for Containers (JSR-196) call backs using the javax.security.auth.callback.Callback interface.

The support is activated by letting the work instance implement the

javax.resource.spi.work.WorkContextProvider

interface and returning an instance of javax.resource.spi.work.SecurityContext.

The security callback is configured through the >workmanager< element for the deployment, either in ironjacamar.xml or in the -ra.xml file. See the schema definitions for further details.

There is support for creating a basic security domain which can provide a javax.security.auth.Subject instance to deployments that are using <security-domain> or <security-domain-and-application> in their setup.

A security domain can be configured through




          

<!-- SubjectFactory -->

<bean name="DefaultSecurityDomain"

      interface="org.jboss.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>

beans.

4.5. Datasources

The IronJacamar project can deploy datasources using the datasources-1_0.xsd, datasources-1_1.xsd or datasources-1_2.xsd schemas.

The configuration is done in the

config/bootstrap/ds.xml

The IronJacamar project features a web server which is used to serve web archive deployments. More information about Jetty can be found at the homepage.

Table 4.6. DsXmlDeployer

Property	Type	Description
`JDBCLocal`	`String`	The name of the `jdbc-local.rar` deployment
`JDBCXA`	`String`	The name of the `jdbc-xa.rar` deployment
`TransactionManager`	`javax.transaction.TransactionManager`	The transaction manager
`MetadataRepository`	`org.jboss.jca.core.spi.mdr.MetadataRepository`	The metadata repository
`Kernel`	`com.github.fungal.api.Kernel`	The kernel

The datasource deployer can be removed from the environment by removing the ds.xml file in

config/bootstrap/

as well as the reference in config/bootstrap/bootstrap.xml to the file.

Furthermore all jdbc-*.rar files in the system/ directory should be removed too.

4.6. Web server

The configuration is done in the

system/web.xml

file.






<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>

Table 4.7. Web server

Property	Type	Description
`Host`	`String`	Set the bind address for the web server Default: `localhost`
`Port`	`int`	Set the port for the web server Default: `8080`
`AcceptQueueSize`	`int`	Set the accept queue size for the Jetty connector Default: `64`
`ExecutorService`	`java.util.concurrent.ExecutorService`	The thread pool for the web server Default: The kernel thread pool

The web server can be removed from the environment by removing the web.xml file in

system/

Furthermore all .war files in the same directory should be removed too.

All the Jetty libraries can be removed by deleting the

lib/jetty

directory.

Chapter 5. Deployment

5.1. Packaging requirements

5.2. Deploying resource adapters

5.2.1. Resource adapter descriptor
5.2.2. Resource adapter extensions
5.2.3. Resource adapter statistics

5.3. Deploying datasources

5.3.1. Datasource descriptor
5.3.2. Datasource extensions
5.3.3. Datasource statistics

5.4. General deployment settings

5.4.1. Flush strategies
5.4.2. Capacity policies

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

5.1. Packaging requirements

A resource adapter archive is a structured Java Archive (JAR) file, which bundles all Java classes in JAR files, and optionally contains metadata, resources and native libraries.

A resource adapter archive name ends in the .rar extension.

An example of a resource adapter archive could look like


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

See the Java EE Connector Architecture 1.7 specification chapter 20 for further requirements.

5.2. Deploying resource adapters

Resource adapters (.rar) are deployed by copying the resource adapter into the deploy/ directory

cp example.rar ironjacamar-1.1.0.Final/deploy

on a Un*x based system or

copy example.rar ironjacamar-1.1.0.Final\deploy

The resource adapter can be configured and activated through a META-INF/ironjacamar.xml file in the archive. The format of the XML document is defined by the ironjacamar_1_0.xsd or ironjacamar_1_1.xsd schemas.

A resource adapter can also be configured and activated through deployment of a -ra.xml file in the deploy/ directory - f.ex. deploy/example-ra.xml. The format of the XML document is defined by the resource-adapters_1_0.xsd or resource-adapters_1_1.xsd schemas - f.ex






<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>

to bind the connection factory from com.example.ra.MCF under java:/eis/example.

See the schema appendix for additional details about the format.

Alternative the resource adapter deployments will be picked up by the RAActivator bean which bind a single connection factory under

java:/eis/<deploymentName>

- f.ex. java:/eis/example and a single admin object under

java:/eis/ao/<deploymentName>

- f.ex. java:/eis/ao/example.

5.2.1. Resource adapter descriptor

A resource adapter can be configured using two different ways

META-INF/ironjacamar.xml for internal configuration
-ra.xml for external configuration

to the resource adapter archive. Both formats share the same layout to ease configuration - only the top-level elements differ.

Table 5.1. Main elements

Element	Desciption
`bean-validation-groups`	Specifies bean validation group that should be used
`bootstrap-context`	Specifies the unique name of the bootstrap context that should be used
`config-property`	The config-property specifies resource adapter configuration properties.
`transaction-support`	Define the type of transaction supported by this resource adapter. Valid values are: NoTransaction, LocalTransaction, XATransaction
`connection-definitions`	Specifies the connection definitions
`admin-objects`	Specifies the administration objects

Table 5.2. Bean validation groups elements

Element	Desciption
`bean-validation-group`	Specifies the fully qualified class name for a bean validation group that should be used for validation

Table 5.3. Connection definition / admin object attributes

Attribute	Desciption
`class-name`	Specifies the the fully qualified class name of a managed connection factory or admin object
`jndi-name`	Specifies the JNDI name
`enabled`	Should the object in question be activated
`use-java-context`	Specifies if a java:/ JNDI context should be used
`pool-name`	Specifies the pool name for the object
`use-ccm`	Enable the cache connection manager
`sharable`	Defines the connection as sharable (lazy association) (1.1)
`enlistment`	Defines if the connection should use lazy enlistment if supported (1.1)

Table 5.4. Connection definition elements

Element	Desciption
`config-property`	The config-property specifies managed connection factory configuration properties.
`pool`	Specifies pooling settings
`xa-pool`	Specifies XA pooling settings
`security`	Specifies security settings
`timeout`	Specifies time out settings
`validation`	Specifies validation settings
`recovery`	Specifies the XA recovery settings

Table 5.5. Pool elements

Element	Desciption
`min-pool-size`	The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
`initial-pool-size`	The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.1)
`max-pool-size`	The max-pool-size element indicates the maximum number of connections for a pool. No more than max-pool-size connections will be created in each sub-pool. This defaults to 20.
`prefill`	Whether to attempt to prefill the connection pool. Default is false
`use-strict-min`	Specifies if the min-pool-size should be considered strictly. Default false
`flush-strategy`	Specifies how the pool should be flush in case of an error. Valid values are: `FailingConnectionOnly` (default), `InvalidIdleConnections` (1.1), `IdleConnections`, `Gracefully` (1.1), `EntirePool`, `AllInvalidIdleConnections` (1.1), `AllIdleConnections` (1.1), `AllGracefully` (1.1), `AllConnections` (1.1)
`capacity`	Specifies the capacity policies (1.1)

Table 5.6. XA pool elements

Element	Desciption
`min-pool-size`	The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
`initial-pool-size`	The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.1)
`max-pool-size`	The max-pool-size element indicates the maximum number of connections for a pool. No more than max-pool-size connections will be created in each sub-pool. This defaults to 20.
`prefill`	Whether to attempt to prefill the connection pool. Default is false
`use-strict-min`	Specifies if the min-pool-size should be considered strictly. Default false
`flush-strategy`	Specifies how the pool should be flush in case of an error. Valid values are: `FailingConnectionOnly` (default), `InvalidIdleConnections` (1.1), `IdleConnections`, `Gracefully` (1.1), `EntirePool`, `AllInvalidIdleConnections` (1.1), `AllIdleConnections` (1.1), `AllGracefully` (1.1), `AllConnections` (1.1)
`capacity`	Specifies the capacity policies (1.1)
`is-same-rm-override`	The is-same-rm-override element allows one to unconditionally set whether the javax.transaction.xa.XAResource.isSameRM(XAResource) returns true or false
`interleaving`	An element to enable interleaving for XA connection factories
`no-tx-separate-pools`	Oracle does not like XA connections getting used both inside and outside a JTA transaction. To workaround the problem you can create separate sub-pools for the different contexts
`pad-xid`	Should the Xid be padded
`wrap-xa-resource`	Should the XAResource instances be wrapped in an org.jboss.jca.core.spi.transaction.xa.XAResourceWrapper instance

Table 5.7. Security elements

Element	Desciption
`application`	Indicates that application supplied parameters (such as from getConnection(user, pw)) are used to distinguish connections in the pool.
`security-domain`	Indicates Subject (from security domain) are used to distinguish connections in the pool. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute.
`security-domain-and-application`	Indicates that either application supplied parameters (such as from getConnection(user, pw)) or Subject (from security domain) are used to distinguish connections in the pool. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute.

Table 5.8. Time out elements

Element	Desciption
`blocking-timeout-millis`	The blocking-timeout-millis element indicates the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is 30000 (30 seconds).
`idle-timeout-minutes`	The idle-timeout-minutes elements indicates the maximum time in minutes a connection may be idle before being closed. The actual maximum time depends also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes of any pool.
`allocation-retry`	The allocation retry element indicates the number of times that allocating a connection should be tried before throwing an exception. The default is 0.
`allocation-retry-wait-millis`	The allocation retry wait millis element indicates the time in milliseconds to wait between retrying to allocate a connection. The default is 5000 (5 seconds).
`xa-resource-timeout`	Passed to XAResource.setTransactionTimeout(). Default is zero which does not invoke the setter. Specified in seconds

Table 5.9. Validation elements

Element	Desciption
`background-validation`	An element to specify that connections should be validated on a background thread versus being validated prior to use
`background-validation-millis`	The background-validation-millis element specifies the amount of time, in milliseconds, that background validation will run.
`use-fast-fail`	Whether fail a connection allocation on the first connection if it is invalid (true) or keep trying until the pool is exhausted of all potential connections (false). Default is false

Table 5.10. Admin object elements

Element	Desciption
`config-property`	Specifies an administration object configuration property.

Table 5.11. Recovery elements

Element	Desciption
`recover-credential`	Specifies the user name / password pair or security domain that should be used for recovery.
`recover-plugin`	Specifies an implementation of the org.jboss.jca.core.spi.recovery.RecoveryPlugin class.

The deployment schemas are defined in doc/ironjacamar_1_0.xsd, doc/ironjacamar_1_1.xsd, doc/resource-adapters_1_0.xsd and doc/resource-adapters_1_1.xsd.

5.2.2. Resource adapter extensions

A resource adapter can make use of a couple of Java EE Connector Architecture extensions in the IronJacamar container in order to improve the integration.

The extensions include

org.jboss.jca.core.spi.recovery.RecoveryPlugin: Plugin to provide feedback to the recovery module inside IronJacamar.
org.jboss.jca.core.spi.statistics.Statistics: Plugin to identify a resource adapter component (ResourceAdapter, ManagedConnectionFactory and admin object) that provides statistics.

The following sections will describe these extensions points.

5.2.2.1. Recovery extension

The IronJacamar recovery extension allows the resource adapter deployment to give feedback to the container if a ManagedConnection can be used for recovery. This extension is used as part of XA recovery in the environment, and should therefore be implemented by all resource adapters capable of working in an XATransaction semantics.

The interface org.jboss.core.spi.recovery.RecoveryPlugin located in the ironjacamar-core-api artifact makes up the SPI for the extension.

The interface contains two methods that should be implemented in a resource adapter specific manner.

The method

public boolean isValid(Object c) throws ResourceException;

will return true if the connection can be used for recovery.

The method

public void close(Object c) throws ResourceException;

will close a connection that was used for recovery.

The recovery extension is activated by adding a recovery element to the deployment

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

The following recovery plugins are provided by IronJacamar

org.jboss.jca.core.recovery.DefaultRecoveryPlugin: Default recovery plugin that tries to call a close() method on the underlying object
org.jboss.jca.core.recovery.ConfigurableRecoveryPlugin: A recovery plugin where the results of the isValid and close can be specified
org.jboss.jca.core.recovery.ValidatingManagedConnectionFactoryRecoveryPlugin: A recovery plugin that uses the javax.resource.spi.ValidatingManagedConnectionFactory interface to verify the connection

Note

The IronJacamar container will use a default implementation of the recovery SPI if an implementation isn't specified by the deployment.

5.2.2.2. Statistics extension

The IronJacamar statistics extension allows a resource adapter to expose statistics to the container and hence to the environment where IronJacamar is running. Statistics can be enabled for ResourceAdapter, ManagedConnectionFactory and admin object instances.

The extension include two interfaces org.jboss.core.spi.statistics.Statistics and org.jboss.core.spi.statistics.StatisticsPlugin. Both these interfaces are located in the ironjacamar-core-api artifact.

The Statistics interface will mark a resource adapter component as statistics capable and return the statistics plugin implementation instance.

The StatisticsPlugin interface contains methods to expose and describe each statistic that the plugin makes available. This information will then be made available to the environment where the IronJacamar container is running using the environment's prefered mechanism.

Note

The IronJacamar container will only expose core statistics for a deployment if no implementation of this extension is available.

5.2.3. Resource adapter statistics

Resource adapter deployments has the following core statistics values

Table 5.12. Core statistics

Name	Desciption
`ActiveCount`	The number of active connections. Each of the connections is either in use by an application or available in the pool
`AvailableCount`	The number of available connections in the pool
`AverageBlockingTime`	The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds
`AverageCreationTime`	The average time spent creating a connection. The value is in milliseconds
`AverageGetTime`	The average time spent obtaining a connection. The value is in milliseconds
`BlockingFailureCount`	The number of times where there was a time out getting an exclusive lock on the pool
`CreatedCount`	The number of connections created
`DestroyedCount`	The number of connections destroyed
`IdleCount`	The number of connections currently idle
`InUseCount`	The number of connections currently in use
`MaxCreationTime`	The maximum time it took to create a connection. The value is in milliseconds
`MaxGetTime`	The maximum time it took to obtain a connection. The value is in milliseconds
`MaxUsedCount`	The maximum number of connections used
`MaxWaitCount`	The maximum number of requests waiting for a connection at the same time
`MaxWaitTime`	The maximum time spent waiting for an exclusive lock on the pool
`TimedOut`	The number of timed out connections
`TotalBlockingTime`	The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds
`TotalCreationTime`	The total time spent creating connections. The value is in milliseconds
`TotalGetTime`	The total time spent obtaining connections. The value is in milliseconds
`WaitCount`	The number of requests that had to wait for a connection

5.3. Deploying datasources

Datasources (-ds.xml) are deployed by copying the definition into the deploy/ directory

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

on a Un*x based system or

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

You will need to install the database JDBC driver into the lib/ directory.

You can find examples of datasource definitions in the doc/datasources directory and the schemas: doc/datasources_1_0.xsd, doc/datasources_1_1.xsd and doc/datasources_1_1.xsd.

5.3.1. Datasource descriptor

Datasource descriptors are divided into

<datasource> for a standard datasource
<xa-datasource> for an XA capable datasource

definitions.

A datasource descriptor supports the following parameters.

Table 5.13. Common datasource attributes

Attribute	Desciption
`jndi-name`	Specifies the JNDI name for the datasource
`pool-name`	Specifies the pool name for the datasource used for management
`enabled`	Specifies if the datasource should be enabled
`use-java-context`	Setting this to false will bind the DataSource into global JNDI
`spy`	Enable spy functionality on the JDBC layer - e.g. log all JDBC traffic to the datasource. The logging category `jboss.jdbc.spy` must be enabled too.
`use-ccm`	Enable the cached connection manager
`jta`	Enable JTA integration (only `<datasource>`)

Table 5.14. datasource elements

Element	Desciption
`connection-url`	The JDBC driver connection URL
`driver-class`	The fully qualifed name of the JDBC driver class
`datasource-class`	The fully qualifed name of the JDBC datasource class
`driver`	An unique name for the JDBC driver specified in the drivers section. Or the name of the .jar file if deployed as standalone deployment This element is mandatory when deploying in WildFly
`connection-property`	The connection-property element allows you to pass in arbitrary connection properties to the Driver.connect(url, props) method. Each connection-property specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content
`new-connection-sql`	Specify an SQL statement to execute whenever a connection is added to the connection pool
`transaction-isolation`	Set java.sql.Connection transaction isolation level to use. The constants defined by transaction-isolation-values are the possible transaction isolation levels and include: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
`url-delimiter`	Specifies the delimeter for URLs in connection-url for HA datasources
`url-selector-strategy-class-name`	A class that implements org.jboss.jca.adapters.jdbc.spi.URLSelectorStrategy
`pool`	Specifies the pooling settings
`security`	Specifies the security settings
`validation`	Specifies the validation settings
`timeout`	Specifies the time out settings
`statement`	Specifies the statement settings

Table 5.15. xa-datasource elements

Element	Desciption
`xa-datasource-property`	Specifies a property to assign to the XADataSource implementation class. Each property is identified by the name attribute and the property value is given by the xa-datasource-property element content. The property is mapped onto the XADataSource implementation by looking for a JavaBeans style getter method for the property name. If found, the value of the property is set using the JavaBeans setter with the element text translated to the true property type using the java.beans.PropertyEditor for the type
`xa-datasource-class`	The fully qualifed name of the javax.sql.XADataSource implementation class
`driver`	An unique name for the JDBC driver specified in the drivers section. Or the name of the .jar file if deployed as standalone deployment. This element is mandatory when deploying in WildFly
`url-delimiter`	Specifies the delimeter for URLs in the connection url for HA datasources
`url-property`	Specifies the property for the URL property in the xa-datasource-property values (1.2)
`url-selector-strategy-class-name`	A class that implements org.jboss.jca.adapters.jdbc.spi.URLXASelectorStrategy
`new-connection-sql`	Specifies an SQL statement to execute whenever a connection is added to the connection pool
`transaction-isolation`	Set java.sql.Connection transaction isolation level to use. The constants defined by transaction-isolation-values are the possible transaction isolation levels and include: TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE
`xa-pool`	Specifies the pooling settings
`security`	Specifies the security settings
`validation`	Specifies the validation settings
`timeout`	Specifies the time out settings
`statement`	Specifies the statement settings
`recovery`	Specifies the recovery settings

Table 5.16. Pool settings

Element	Desciption
`min-pool-size`	The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
`initial-pool-size`	The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.2)
`max-pool-size`	The max-pool-size element indicates the maximum number of connections for a pool. No more connections will be created in each sub-pool. This defaults to 20
`prefill`	Whether to attempt to prefill the connection pool. Empty element denotes a true value. Default is false
`use-strict-min`	Define if the min-pool-size should be considered a strictly. Default false
`flush-strategy`	Specifies how the pool should be flush in case of an error. Valid values are: `FailingConnectionOnly` (default), `InvalidIdleConnections` (1.2), `IdleConnections`, `Gracefully` (1.2), `EntirePool`, `AllInvalidIdleConnections` (1.2), `AllIdleConnections` (1.2), `AllGracefully` (1.2), `AllConnections` (1.2)
`allow-multiple-users`	Specifies if multiple users will access the datasource through the getConnection(user, password) method and hence if the internal pool type should account for that (1.1)
`capacity`	Specifies the capacity policies (1.2)
`connection-listener`	An org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener that provides a possible to listen for connection activation and passivation in order to perform actions before the connection is returned to the application or returned to the pool (1.2)

Table 5.17. XA pool settings

Element	Desciption
`min-pool-size`	The min-pool-size element indicates the minimum number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0
`initial-pool-size`	The initial-pool-size element indicates the initial number of connections a pool should hold. These are not created until a Subject is known from a request for a connection. This default to 0 (1.2)
`max-pool-size`	The max-pool-size element indicates the maximum number of connections for a pool. No more connections will be created in each sub-pool. This defaults to 20
`prefill`	Whether to attempt to prefill the connection pool. Empty element denotes a true value. Default is false
`use-strict-min`	Define if the min-pool-size should be considered a strictly. Default false
`flush-strategy`	Specifies how the pool should be flush in case of an error. Valid values are: `FailingConnectionOnly` (default), `InvalidIdleConnections` (1.2), `IdleConnections`, `Gracefully` (1.2), `EntirePool`, `AllInvalidIdleConnections` (1.2), `AllIdleConnections` (1.2), `AllGracefully` (1.2), `AllConnections` (1.2)
`allow-multiple-users`	Specifies if multiple users will access the datasource through the getConnection(user, password) method and hence if the internal pool type should account for that (1.1)
`capacity`	Specifies the capacity policies (1.2)
`connection-listener`	An org.jboss.jca.adapters.jdbc.spi.listener.ConnectionListener that provides a possible to listen for connection activation and passivation in order to perform actions before the connection is returned to the application or returned to the pool (1.2)
`is-same-rm-override`	The is-same-rm-override element allows one to unconditionally set whether the javax.transaction.xa.XAResource.isSameRM(XAResource) returns true or false
`interleaving`	An element to enable interleaving for XA connection factories
`no-tx-separate-pools`	Oracle does not like XA connections getting used both inside and outside a JTA transaction. To workaround the problem you can create separate sub-pools for the different contexts
`pad-xid`	Should the Xid be padded
`wrap-xa-resource`	Should the XAResource instances be wrapped in an org.jboss.jca.core.spi.transaction.xa.XAResourceWrapper instance

Table 5.18. Security settings

Element	Desciption
`user-name`	Specify the username used when creating a new connection.
`password`	Specify the password used when creating a new connection.
`security-domain`	Indicates Subject (from security domain) are used to distinguish connections in the pool. The content of the security-domain is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS login-config.xml descriptor application-policy/name attribute.
`reauth-plugin`	Defines a reauthentication plugin that can be used for reauthentication of physical connections.

Table 5.19. Validation settings

Element	Desciption
`valid-connection-checker`	An org.jboss.jca.adapters.jdbc.spi.ValidConnectionChecker that provides a SQLException isValidConnection(Connection e) method to validate is a connection is valid. An exception means the connection is destroyed. This overrides the check-valid-connection-sql when present
`check-valid-connection-sql`	Specify an SQL statement to check validity of a pool connection. This may be called when managed connection is taken from pool for use.
`validate-on-match`	The validate-on-match element indicates whether or not connection level validation should be done when a connection factory attempts to match a managed connection for a given set. This is typically exclusive to the use of background validation
`background-validation`	An element to specify that connections should be validated on a background thread versus being validated prior to use
`background-validation-millis`	The background-validation-millis element specifies the amount of time, in milliseconds, that background validation will run
`use-fast-fail`	Whether fail a connection allocation on the first connection if it is invalid (true) or keep trying until the pool is exhausted of all potential connections (false) default false
`stale-connection-checker`	An org.jboss.jca.adapters.jdbc.spi.StaleConnectionChecker that provides a boolean isStaleConnection(SQLException e) method which if it it returns true will wrap the exception in an org.jboss.jca.adapters.jdbc.StaleConnectionException which is a subclass of SQLException
`exception-sorter`	An org.jboss.jca.adapters.jdbc.spi.ExceptionSorter that provides a boolean isExceptionFatal(SQLException e) method to validate is an exception should be broadcast to all javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message

Table 5.20. Time out settings

Element	Desciption
`blocking-timeout-millis`	The blocking-timeout-millis element indicates the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is 30000 (30 seconds).
`idle-timeout-minutes`	The idle-timeout-minutes elements indicates the maximum time in minutes a connection may be idle before being closed. The actual maximum time depends also on the IdleRemover scan time, which is 1/2 the smallest idle-timeout-minutes of any pool.
`set-tx-query-timeout`	Whether to set the query timeout based on the time remaining until transaction timeout, any configured query timeout will be used if there is no transaction. The default is false
`query-timeout`	Any configured query timeout in seconds The default is no timeout
`use-try-lock`	Any configured timeout for internal locks on the resource adapter objects in seconds The default is a 60 second timeout
`allocation-retry`	The allocation retry element indicates the number of times that allocating a connection should be tried before throwing an exception. The default is 0.
`allocation-retry-wait-millis`	The allocation retry wait millis element indicates the time in milliseconds to wait between retrying to allocate a connection. The default is 5000 (5 seconds).
`xa-resource-timeout`	Passed to XAResource.setTransactionTimeout() Default is zero which does not invoke the setter. In seconds

Table 5.21. Statement settings

Element	Desciption
`track-statements`	Whether to check for unclosed statements when a connection is returned to the pool and result sets are closed when a statement is closed/return to the prepared statement cache. valid values are: `false` - do not track statements and results; `true` - track statements and result sets and warn when they are not closed; `nowarn` - track statements but do no warn about them being unclosed (the default)
`prepared-statement-cache-size`	The number of prepared statements per connection in an LRU cache
`share-prepared-statements`	Whether to share prepare statements, i.e. whether asking for same statement twice without closing uses the same underlying prepared statement. The default is false

Table 5.22. Recovery elements

Element	Desciption
`recover-credential`	Specifies the user name / password pair or security domain that should be used for recovery.
`recover-plugin`	Specifies an implementation of the org.jboss.jca.core.spi.recovery.RecoveryPlugin class.

Table 5.23. Driver attributes

Attribute	Desciption
`name`	An unique name for the JDBC driver
`module`	The module definition for the JDBC driver. The format of a module inside WildFly 8+ is `com.h2database.h2` which will map to the H2 installation under `modules/com/h2database/h2/main`. A ':' can be used to identify the slot - f.ex `com.h2database.h2:1.3.159`. The format for IronJacamar Standalone/Embedded is the name of the .jar file
`major-version`	The major version of the driver
`minor-version`	The minor version of the driver

Table 5.24. Driver elements

Element	Desciption
`driver-class`	The fully qualified class name of the driver class
`datasource-class`	The fully qualified class name of the datasource class
`xa-datasource-class`	The fully qualified class name of the XA datasource class

The datasource deployment schema is defined in doc/datasources_1_0.xsd and doc/datasources_1_1.xsd.

5.3.2. Datasource extensions

The datasource deployments can make use of a couple of extensions in the JDBC resource adapter to improve the connection validation and checking if an exception should reestablish the connection in question.

The extensions include

org.jboss.jca.adapters.jdbc.spi.ExceptionSorter: Plugin to check if a SQLException is fatal for the connection on which it was thrown.
org.jboss.jca.adapters.jdbc.spi.StaleConnection: Plugin to wrap stale SQLException's in a org.jboss.jca.adapters.jdbc.StaleConnectionException.
org.jboss.jca.adapters.jdbc.spi.ValidConnection: Plugin to Check if a connection is valid for use by the application.

Configuration of the extensions are done by using

The <exception-sorter> tag for an ExceptionSorter
The <stale-connection-checker> tag for a StaleConnection
The <valid-connection-checker> tag for a ValidConnection

IronJacamar features implementations of these extensions for a couple of popular databases. Contributions in this area are most welcome either generic solutions or for a specific database.

Informix:

org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter

Microsoft SQLServer:

org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker

PostgreSQL:

org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker

MySQL:

org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker

IBM DB2:

org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker

Generic:

org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker

Sybase:

org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker

Oracle:

org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker

5.3.3. Datasource statistics

Datasources has the following core statistics values

Table 5.25. Core statistics

Name	Desciption
`ActiveCount`	The number of active connections. Each of the connections is either in use by an application or available in the pool
`AvailableCount`	The number of available connections in the pool
`AverageBlockingTime`	The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds
`AverageCreationTime`	The average time spent creating a connection. The value is in milliseconds
`AverageGetTime`	The average time spent obtaining a connection. The value is in milliseconds
`BlockingFailureCount`	The number of times where there was a time out getting an exclusive lock on the pool
`CreatedCount`	The number of connections created
`DestroyedCount`	The number of connections destroyed
`IdleCount`	The number of connections currently idle
`InUseCount`	The number of connections currently in use
`MaxCreationTime`	The maximum time it took to create a connection. The value is in milliseconds
`MaxGetTime`	The maximum time it took to obtain a connection. The value is in milliseconds
`MaxUsedCount`	The maximum number of connections used
`MaxWaitCount`	The maximum number of requests waiting for a connection at the same time
`MaxWaitTime`	The maximum time spent waiting for an exclusive lock on the pool
`TimedOut`	The number of timed out connections
`TotalBlockingTime`	The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds
`TotalCreationTime`	The total time spent creating connections. The value is in milliseconds
`TotalGetTime`	The total time spent obtaining connections. The value is in milliseconds
`WaitCount`	The number of requests that had to wait for a connection

Datasources has the following JDBC statistics values

Table 5.26. JDBC statistics

Name	Desciption
`PreparedStatementCacheAccessCount`	The number of times that the statement cache was accessed
`PreparedStatementCacheAddCount`	The number of statements added to the statement cache
`PreparedStatementCacheCurrentSize`	The number of prepared and callable statements currently cached in the statement cache
`PreparedStatementCacheDeleteCount`	The number of statements discarded from the cache
`PreparedStatementCacheHitCount`	The number of times that statements from the cache were used
`PreparedStatementCacheMissCount`	The number of times that a statement request could not be satisfied with a statement from the cache

5.4. General deployment settings

This section will provide an overview of general deployment settings that are shared between resource adapter activations, and datasource deployments.

5.4.1. Flush strategies

The flush strategy option for the connection pool defines how the pool should be flushed in case there is an error on a connection belonging to the pool.

In all cases the connection with the error is destroyed, and the pool is scheduled for prefill if supported.

Table 5.27. Flush strategies

Name	Desciption
`FailingConnectionOnly`	Only the connection with the error is destroyed. This is the default strategy.
`InvalidIdleConnections`	All idle connections are checked if they are invalid, based on the `javax.resource.spi.ValidatingManagedConnectionFactory` return value.
`IdleConnections`	All idle connections are destroyed.
`Gracefully`	All idle connections are destroyed, and all active connections will be destroyed upon return to the pool.
`EntirePool`	All connections are destroyed, including current active connections.
`AllInvalidIdleConnections`	Like `InvalidIdleConnections`, but across all credentials for the pool if supported.
`AllIdleConnections`	Like `IdleConnections`, but across all credentials for the pool if supported.
`AllGracefully`	Like `Gracefully`, but across all credentials for the pool if supported.
`AllConnections`	Like `EntirePool`, but across all credentials for the pool if supported.

Table 5.28. Size policy properties

Name	Desciption
`Size`	The number of connections that should be created

This policy is useful when you want to increment with an additional number of connections per request in anticipation that the next request will also need a connection.

This is the default increment policy with a value of 1.

5.4.2.1.3. Watermark policy

The org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkIncrementer policy will fill the pool to the specified number of connections for each request.

Table 5.29. Watermark policy properties

Name	Desciption
`Watermark`	The watermark level for the number of connections

This policy is useful when you want to keep a specified number of connections in the pool at all time.

5.4.2.2. Decrement policies

The following decrement policies are supported.

5.4.2.2.1. MinPoolSize policy

The org.jboss.jca.core.connectionmanager.pool.capacity.MinPoolSizeDecrementer policy will decrement the pool to its min size for each request.

This policy is useful when you want to limit the number of connections after each idle timeout request.

5.4.2.2.2. Size policy

The org.jboss.jca.core.connectionmanager.pool.capacity.SizeDecrementer policy will decrement the pool by the specified number of connections for each idle timeout request.

Table 5.30. Size policy properties

Name	Desciption
`Size`	The number of connections that should be created

This policy is useful when you want to decrement an additional number of connections per idle timeout request in anticipation that the pool usage will lower over time.

5.4.2.2.3. TimedOut policy

The org.jboss.jca.core.connectionmanager.pool.capacity.TimedOutDecrementer policy will removed all connections that have timed out from the pool for each idle timeout request.

This policy is the default decrement policy.

5.4.2.2.4. Watermark policy

The org.jboss.jca.core.connectionmanager.pool.capacity.WatermarkDecrementer policy will decrement the pool to the specified number of connections for each idle timeout request.

Table 5.31. Watermark policy properties

Name	Desciption
`Watermark`	The watermark level for the number of connections

This policy is useful when you want to keep a specified number of connections in the pool at all time.

Chapter 6. Running

6.1. Starting the container

The IronJacamar container is started by entering the bin/ directory

cd ironjacamar-1.1.0.Final/bin

and executing

./run.sh

on a Un*x based system or

run.bat

The command takes an optional -b argument to define the binding address of the naming server

./run.sh -b 192.168.0.199

Once the container has started you should see a log entry like

13:33:10,999 INFO  [Main] Server started in 941ms

in the console where the command was executed.

After the container has started you can browse to

http://localhost:8080

to view the project documentation and use the administration console.

6.2. Stopping the container

The IronJacamar container is stopped by pressing the Ctrl-C keys.

Once the container has stopped you should see a log entry like

13:35:06,752 INFO  [Main] Server stopped in 29ms

in the console where the container was running.

Alternative the container can be stopped through the command line interface.

6.3. Command line interface

The IronJacamar container can be controlled by a command line interface.

If you are accessing a remote container you can use the -h option to specify the host name.

6.3.1. Deploy

You can deploy a resource adapter archive (.rar) using

java -jar fungal-cli.jar deploy <file>

where file specifies the resource adapter archive.

6.3.2. Undeploy

You can undeploy a resource adapter archive (.rar) using

java -jar fungal-cli.jar undeploy <file>

where file specifies the resource adapter archive.

6.3.3. Shutdown

You can shutdown the IronJacamar environment by

java -jar fungal-cli.jar shutdown

6.4. Apache Ant

The IronJacamar container can be controlled by Apache Ant tasks.

6.4.1. Start

The IronJacamar container can be started by the Apache Ant task org.jboss.jca.sjc.ant.Start which takes a home attribute to specify the home directory of the installation.

6.4.2. Stop

The IronJacamar container can be stopped by the Apache Ant task org.jboss.jca.sjc.ant.Stop which takes a home attribute to specify the home directory of the installation.

6.4.3. Deploy

Deployments to the IronJacamar container can be done by the Apache Ant task org.jboss.jca.sjc.ant.Deploy which takes a file attribute to specify the file that should be deployed. The task takes optional host and port attributes in order to specify the host and port where the IronJacamar container is located.

6.4.4. Undeploy

Undeploying from the IronJacamar container can be done by the Apache Ant task org.jboss.jca.sjc.ant.Undeploy which takes a file attribute to specify the file that should be undeployed. The task takes optional host and port attributes in order to specify the host and port where the IronJacamar container is located.

6.4.5. Ping

The IronJacamar container can be pinged for availability using the Apache Ant task org.jboss.jca.sjc.ant.Ping. The task takes optional host and port attributes in order to specify the host and port where the IronJacamar container is located.

6.5. Apache Maven

The IronJacamar container can be controlled by Apache Maven mojos.

6.5.1. Start

The IronJacamar container can be started by the Apache Maven mojo org.jboss.jca.sjc.maven.Start which takes a home element to specify the home directory of the installation.

6.5.2. Stop

The IronJacamar container can be stopped by the Apache Maven mojo org.jboss.jca.sjc.maven.Stop which takes a home element to specify the home directory of the installation.

6.5.3. Deploy

Deployments to the IronJacamar container can be done by the Apache Maven mojo org.jboss.jca.sjc.maven.Deploy which takes a file element to specify the file that should be deployed. The mojo takes optional host and port elements in order to specify the host and port where the IronJacamar container is located.

6.5.4. Undeploy

Undeploying from the IronJacamar container can be done by the Apache Maven mojo org.jboss.jca.sjc.maven.Undeploy which takes a file element to specify the file that should be undeployed. The mojo takes optional host and port elements in order to specify the host and port where the IronJacamar container is located.

6.5.5. Ping

The IronJacamar container can be pinged for availability using the Apache Maven mojo org.jboss.jca.sjc.maven.Ping. The mojo takes optional host and port elements in order to specify the host and port where the IronJacamar container is located.

Chapter 7. Validator

7.3. Running the standalone validator

7.1. Introduction

7.2. Reports

7.4. Apache Ant integration

7.4.1. Usage

7.5. Apache Maven integration

7.5.1. Usage

7.1. Introduction

The IronJacamar container features a validator which checks resource adapter archives against the Java Connector Architecture (JCA) specification.

The validator is doing a static analysis of the resource adapter classes and checks them against the rules defined in the validator.

The validator is used in the deployer chain of the JCA container, and is available as a standalone tool, as an Apache Ant task and as a Apache Maven plugin too.

7.2. Reports

The validator works by scanning the resource adapter in question and output a report which lists which rules have been violated.

An example could be

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public int hashCode()" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public boolean equals(Object)" method.
Code: com.mycompany.myproject.ResourceAdapterImpl

which means that com.mycompany.myproject.ResourceAdapterImpl is missing an equals and hashCode implementation.

Table 7.1. Validator report

Key	Desciption
`Severity`	Specifies the severity of the rule. ERROR: Critical error which must be fixed in order for the resource adapter to operate correctly. WARN: Error which should be fixed in order for the resource adapter to operate correctly.
`Section`	A reference to a section in the Java Connector Architecture specification where the requirement is defined.
`Descrption`	A short description of the rule.
`Code`	The class which triggered the rule.

7.3. Running the standalone validator

The validator can be run on the command line by

cd doc/validator
./validator.sh <file>

The reports will be generated into the current directory under the name of <file>.log.

7.4. Apache Ant integration

The validator integrates with Apache Ant such that you can generate the reports directly from your build environment before deploying the resoruce adapter into the IronJacamar container.

First you have to define the taskdef for the task

<taskdef name="validator"
         classname="org.jboss.jca.validator.ant.ValidatorTask"
         classpathref="ironjacamar.lib.path.id"/>

See the Apache Ant documentation for additional instructions on installation.

7.4.1. Usage

<validator rarFile="${myArchive.rar}" outputDir="${report.dir}"/>

Table 7.2. Apache Ant: validator

Key	Value
`rarFile`	The resource adapter file
`outputDir`	The directory where the reports should be generated
`classpath`	A classpath to resolve additional dependencies against

7.5. Apache Maven integration

The validator integrates with Apache Maven such that you can generate the reports directly from your build environment before deploying the resoruce adapter into the IronJacamar container.

To be able to use the validator plugin in your Maven project, you will have to add the following plugin declaration in the pom.xml of your project:






<build>

  <plugins>

    <plugin>

      <groupId>org.jboss.ironjacamar</groupId>

      <artifactId>ironjacamar-validator-maven</artifactId>

      <!-- The version of the plugin you want to use -->

      <version>1.1.0.Final</version>

      <executions>

        <execution>

          <goals>

            <goal>validate</goal>

          </goals>

        </execution>

      </executions>

      <configuration>

        <!-- output directory-->

        <outputDir>.</outputDir>

        

        <!-- rar filename -->

        <rarFile>/path/to/myresourceadapter.rar</rarFile>

        

        <!--  optional classpath 

        <classpath>

          <param>classpath1</param>

          <param>classpath2</param>

        </classpath>

        -->

      </configuration>

    </plugin>

  </plugins>

</build>

Note

By default, the validator-maven plugin is attached to the "package" phase of Maven.

See the Apache Maven documentation for additional instructions on installation.

7.5.1. Usage

Once you have configured your project's pom.xml to include the validator-maven plugin, as explained earlier, you can generate the report by running the package goal on your project.

mvn clean package

Table 7.3. Apache Maven: validator

Key	Value
`rarFile`	The resource adapter file
`outputDir`	The directory where the reports should be generated
`classpath`	A classpath to resolve additional dependencies against

Chapter 8. Code generator

8.3. Running the tool

8.1. Introduction

8.2. Functionality

8.3.1. Developer Input

8.4. Generated code

8.4.1. Apache Ant build environment
8.4.2. Apache Ant + Ivy build environment
8.4.3. Gradle build environment
8.4.4. Apache Maven build environment

8.1. Introduction

The IronJacamar project includes a resource adapter code generator which can generate a complete code skeleton that will help developers get started with their development tasks.

8.2. Functionality

The code generator will generate a resource adapter code skeleton based on the user input. The code generator supports

Resource adapter using JCA 1.7 annotations
Resource adapter using JCA 1.7 metadata
Resource adapter using JCA 1.6 annotations
Resource adapter using JCA 1.6 metadata
Resource adapter using JCA 1.5
Resource adapter using JCA 1.0
Apache Ant build environment
Apache Ant + Ivy build environment
Gradle build environment
Apache Maven build environment
Test suite environment

8.3. Running the tool

The code generator can be run on the command line by

./codegenerator.sh

from the doc/codegenerator directory.

The code generator supports the following arguments

Table 8.1. Code generator arguments

Argument	Desciption
`-o`	Specifies the output directory for the code skeleton.

The developer must then answer various questions regarding the properties of the resource adapter.

8.3.1. Developer Input

This section describes the questions that are asked in order to generate the code.

Table 8.2. Developer input

Question	Spec	Desciption	Type
Profile version (1.7/1.6/1.5/1.0)	All	Defines which Java EE Connector Architecture specification that the resource adapter should target
Type (O/Outbound/I/Inbound/B/Bidirectional)	JCA 1.5+	Defines if the resource adapter should contain outbound communication., inbound communication or both
Package name	All	The package name of the resource adapter
Transaction support (N/NoTransaction/L/LocalTransaction/X/XATransaction)	All	The transaction support level
Reauthentication (Y/Yes/N/No)	All	If the resource adapter supports reauthentication
Use annotations (Y/Yes/N/No)	JCA 1.6+	Should annotations be used for specifying the structure. If 'No' is selected a `META-INF/ra.xml` is generated
Include a ResourceAdapter (Y/Yes/N/No)	JCA 1.5+	Should an instance of a resource adapter class be included in the archive	Outbound
Resource adapter class name	JCA 1.5+	The class name of the resource adapter	Outbound or Bidirectional
Should the resource adapter class be Serializable (Y/Yes/N/No)	JCA 1.5+	Should the resource adapter class be serializable	Outbound
Managed connection factory class name	All	The class name of the managed connection factory	Outbound or Bidirectional
Managed connection class name	All	The class name of the managed connection	Outbound or Bidirectional
Connection interface class name	All	The class name of the connection interface	Outbound or Bidirectional
Connection implementation class name	All	The class name of the connection implementation	Outbound or Bidirectional
Connection factory interface class name	All	The class name of the connection factory interface	Outbound or Bidirectional
Connection factory implementation class name	All	The class name of the connection factory implementation	Outbound or Bidirectional
Resource adapter config properties	All	Include a configuration properties in the resource adapter instance	Outbound or Bidirectional
Managed connection factory config properties	All	Include a configuration properties in the managed connection factory instance	Outbound or Bidirectional
Use ResourceAdapterAssociation (Y/Yes/N/No)	All	Associate the managed connection factory instance with the resource adapter instance	Outbound or Bidirectional
Use CCI (Y/Yes/N/No)	All	Use the Common Client Interface for the connection / connection factory in the 'Outbound' part of the resource adapter	Outbound or Bidirectional
MessageListener interface name	JCA 1.5+	The name of the message listener interface for the activation	Inbound or Bidirectional
ActivationSpec class name	JCA 1.5+	The class name of the activation specification instance	Inbound or Bidirectional
ActivationSpec config properties	JCA 1.5+	Include configuration properties in the activation specification instance	Inbound or Bidirectional
Activation class name	JCA 1.5+	The class name of the activation instance	Inbound or Bidirectional
Add methods to connection interface (Y/Yes/N/No) [N]:	All	Use for add methods to connection interface	Outbound or Bidirectional
Include an admin object (Y/Yes/N/No)	JCA 1.5+	Should an admin object be added to the project
Use ResourceAdapterAssociation on admin object(Y/Yes/N/No)	JCA 1.5	Associate the admin object instance with the resource adapter instance
Admin object interface name	JCA 1.5+	The interface name of the admin object
Admin object class name	JCA 1.5+	The class name of the admin object
Admin object config properties	JCA 1.5	Include a configuration properties in the admin object instance
Generate a MBean class (Y/Yes/N/No)	All	Generate a MBean for the resource adapter
Integrate EIS test server (Y/Yes/N/No)	All	Should the IronJacamar test EIS server be integrated
Use JBoss Logging (Y/Yes/N/No) [N]:	All	Use JBoss Logging instead of Java Util Logging
Build environment [A/Ant/I/Ant+Ivy/M/Maven/G/Gradle]	All	Type of build environment

8.4. Generated code

The generated code will consist of the classes making up the resource adapter and a test suite environment based on the embedded distribution.

8.4.1. Apache Ant build environment

The following targets are supported in the Apache Ant build environment

Table 8.3. Apache Ant build environment

Target	Desciption
`compile`	Compiles all the files
`rar`	Builds the resource adapter archive
`prepare-test`	Prepares the test environment
`test`	Executes the tests
`docs`	Generates the documentation

8.4.2. Apache Ant + Ivy build environment

The following targets are supported in the Apache Ant + Ivy build environment

Table 8.4. Apache Ant + Ivy build environment

Target	Desciption
`compile`	Compiles all the files
`rar`	Builds the resource adapter archive
`prepare-test`	Prepares the test environment
`test`	Executes the tests
`docs`	Generates the documentation

8.4.3. Gradle build environment

The Gradle build environment currently support the standard tasks such as

Table 8.5. Gradle build environment

Target	Desciption
`compile`	Compiles all the files
`test`	Executes the tests

8.4.4. Apache Maven build environment

The following targets are supported in the Apache Maven build environment

Table 8.6. Apache Maven build environment

Target	Desciption
`compile`	Compiles all the files
`test`	Executes the tests

Chapter 9. Eclipse plugin

9.1. Installation of the plugin

9.2. Configuration of the plugin

9.3. The toolbar

9.4. The menu

9.5. Creating a new IronJacamar project

9.5.1. Project and package name
9.5.2. Creating a ResourceAdapter
9.5.3. Creating a ManagedConnectionFactory
9.5.4. Creating a MessageListener
9.5.5. Creating an AdminObject
9.5.6. Selecting the build environment

9.6. Validate IronJacamar project

9.7. Deploying an IronJacamar project

9.7.1. Deploying a RAR file to an IronJacamar server
9.7.2. Generate the -ra.xml and deploy it to IronJacamar server

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

Generate a resource adapter skeleton
Generate a deployment descriptor for a resource adapter
Validate a resource adapter
Deploy a resource adapter to an IronJacamar server instance
Deploy a deployment descriptor to an IronJacamar server instance

9.1. Installation of the plugin

The plugin is installed by

cp ironjacamar-eclipse.jar $ECLIPSE_HOME/plugins

on Un*x systems, or by

copy ironjacamar-eclipse.jar %ECLIPSE_HOME%\plugins

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

9.2. Configuration of the plugin

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

/opt/ironjacamar-1.1.0.Beta1

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.6. Validate IronJacamar project

The IronJacamar project can be validated by selecting it, and the Validate command in the toolbar will now be enabled. Click on the command to validate your project.

Another way to validate the IronJacamar project is to right click on the project, and select IronJacamar->Validate.

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.

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.

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.

Chapter 10. Other tools

10.1. Resource adapter information tool

10.2. Migration tool

10.2.1. Resource adapters
10.2.2. Data sources

10.1. Resource adapter information tool

The IronJacamar distribution features a resource adapter information tool, that can provide the important information about the resource adapter and a sample deployment descriptor.

The information about the resource adapter is generated using the following command:

./rar-info.sh myeis.rar

where the report will be located in myeis-report.txt. The tool can take an optional -classpath parameter such that additional external dependencies can be resolved against the resource adapter.

The report will contain information about

The name of the resource adapter
The Java EE Connector Architecture specification version
The type of the resource adapter
If the resource adapter supports reauthentication
If the resource adapter is compliant (see the validator tool)
If the resource adapter contains native libraries
The structure of the resource adapter archive
Overview of the resource adapter class
Overview of the managed connection factory classes
The connectory factory and connection API if common client interface isn't used
Overview of the admin object classes
Overview of the activation specification classes
Metadata included, including the MANIFEST.MF file
A sample deployment descriptor

The tool (rar-info.sh) is located in the doc/as/ directory of the distribution.

10.2. Migration tool

The IronJacamar distribution features a migration tool, that can convert the deployment format used in JBoss Application Server prior to version 7, and JBoss Enterprise Application Platform versions prior to version 6.

Since there are different formats (XSDs) to deploy datasources and a resource adapters the tool can convert to both these formats.

The tool (converter.sh) is located in the doc/as/ directory of the distribution.

10.2.1. Resource adapters

A resource adapter deployment is converted using the following command:

./converter.sh -ra old-ds.xml new-ra.xml

which will convert the file old-ds.xml to new-ra.xml. The content of new-ra.xml can then be copied into the resource-adapters subsystem in WildFly or used directly in the IronJacamar/Standalone distribution.

Note

Note that, the tool will do a best effort to convert all old attributes and elements to the new format. It will be necessary to make additional changes to the generated file. Please, consult this documentation for additional information.

10.2.1.1. WebLogic converter

The resource adapter converter tool can also convert the Oracle WebLogic weblogic-ra.xml files to the IronJacamar format.

The following command line can be used:

./converter.sh -ra --weblogic weblogic-ra.xml new-ra.xml

to get a best effort convertion of the Oracle WebLogic deployment file.

10.2.2. Data sources

A data source deployment is converted using the following command:

./converter.sh -ds old-ds.xml new-ds.xml

which will convert the file old-ds.xml to new-ds.xml. The content of new-ds.xml can then be copied into the datasources subsystem in WildFly or used directly in the IronJacamar/Standalone distribution.

Note

Chapter 11. Embedded

The IronJacamar embedded configuration provides a way of running a JCA container in-VM.

11.1. Overview

11.2. Configuration

11.3. Usage

11.3.1. Simple usage
11.3.2. Advanced usage

11.1. Overview

The configuration is useful when you want a

JCA container within your environment
JCA container when doing unit testing

Especially the ability to unit test your resource adapter archives before deploying them into a testing or a production environment will benefit developers.

In order to enhance the experience with working with the embedded configuration the container integrates with the ShrinkWrap and Arquillian frameworks.

11.2. Configuration

You will need all the JAR files located in the

$IRON_JACAMAR_HOME/bin
$IRON_JACAMAR_HOME/lib
$IRON_JACAMAR_HOME/lib/embedded

directories on your application class loader - f.ex.

java -classpath allthejarfiles.jar yourapp

in order to use the embedded configuration.

If you want integration with the Arquillian framework you need to add the JAR files located in the

$IRON_JACAMAR_HOME/lib/embedded/arquillian

directory as well.

The Arquillian/Byteman integration is located in the

$IRON_JACAMAR_HOME/lib/embedded/arquillian/byteman

directory.

Furthermore you will need to configure Java Naming and Directory Interface (JNDI) and logging using for example property files.

Sample jndi.properties file:

java.naming.factory.initial=org.jnp.interfaces.LocalOnlyContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces

Sample logging.properties file:

# Additional logger names to configure (root logger is always configured)
loggers=org.jboss.jca,org.jboss,org.jnp,com.arjuna

# Root logger level
logger.level=${iron.jacamar.log.level:INFO}
logger.handlers=CONSOLE, FILE

# org.jboss.jca
logger.org.jboss.jca.level=DEBUG

# org.jboss
logger.org.jboss.level=INFO

# org.jnp
logger.org.jnp.level=INFO

# com.arjuna
logger.com.arjuna.level=INFO

# Console handler configuration
handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler
handler.CONSOLE.properties=autoFlush
handler.CONSOLE.level=${iron.jacamar.log.console.level:INFO}
handler.CONSOLE.autoFlush=true
handler.CONSOLE.formatter=PATTERN

# File handler configuration
handler.FILE=org.jboss.logmanager.handlers.FileHandler
handler.FILE.level=${iron.jacamar.log.file.level:DEBUG}
handler.FILE.properties=autoFlush,fileName
handler.FILE.autoFlush=true
handler.FILE.fileName=${test.dir}/embedded/test.log
handler.FILE.formatter=PATTERN

# Formatter pattern configuration
formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter
formatter.PATTERN.properties=pattern
formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c{1}] %m%n

These files needs to be available to the application classloader.

Important

The IronJacamar code generator will generate a test suite based on the Arquillian functionality, so that setup can be used as a starting point for your own integration.

The setup will also show you how to use dependencies from the JBoss Nexus Maven repository instead if you choose the Maven or Ant+Ivy based build environment.

Note

Note that, if you want to be able to deploy datasources you will need to deploy the jdbc-local.rar for <datasource> support, or jdbc-xa.rar for <xa-datasource> support. Both archives can be found in the system/ directory.

11.3. Usage

IronJacamar Embedded supports both a simple and an advanced usage model, using pre-assembled resource adapter archives (.rar) or dynamic resource adapter archives based on ShrinkWrap.

The embedded environment supports registering resource adapters and datasources in the platform MBeanServer by setting the system property ironjacamar.embedded.management to true before starting the environment.

11.3.1. Simple usage

The IronJacamar Embedded container environment supports the following open source testing projects:

These extensions allow the developer to use the embedded platform with greater ease as there doesn't have to be a physical representation of the resource adapter archive located to the disk.

The Arquillian integration furthermore allows the developer to leave all the embedded container setup to the integration layer instead.

See the Arquillian and ShrinkWrap web sites for a detailed description of the projects and additional documentation.

11.3.1.1. Arquillian and ShrinkWrap

The code sample below shows an usage of deploying a ShrinkWrap resource adapter archive into the IronJacamar Embedded environment using Arquillian.



/*

 * IronJacamar, a Java EE Connector Architecture implementation

 * Copyright 2012, Red Hat Inc, and individual contributors

 * as indicated by the @author tags. See the copyright.txt file in the

 * distribution for a full listing of individual contributors.

 *

 * This is free software; you can redistribute it and/or modify it

 * under the terms of the GNU Lesser General Public License as

 * published by the Free Software Foundation; either version 2.1 of

 * the License, or (at your option) any later version.

 *

 * This software is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this software; if not, write to the Free

 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.

 */


package org.jboss.jca.arquillian.unit;


import org.jboss.jca.arquillian.embedded.Configuration;

import org.jboss.jca.arquillian.rars.simple.TestConnection;

import org.jboss.jca.arquillian.rars.simple.TestConnectionFactory;


import java.util.UUID;


import javax.annotation.Resource;


import org.jboss.arquillian.container.test.api.Deployment;

import org.jboss.arquillian.junit.Arquillian;

import org.jboss.logging.Logger;

import org.jboss.shrinkwrap.api.ShrinkWrap;

import org.jboss.shrinkwrap.api.spec.JavaArchive;

import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;


import org.junit.Test;

import org.junit.runner.RunWith;


import static org.junit.Assert.assertNotNull;


/**

 * Unit test for Arquillian integration

 * 

 * @author <a href="mailto:jesper.pedersen@ironjacamar.org">Jesper Pedersen</a>

 */

@RunWith(Arquillian.class)

@Configuration(autoActivate = true)

public class ArquillianTestCase

{

   // --------------------------------------------------------------------------------||

   // Class Members ------------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   private static Logger log = Logger.getLogger(ArquillianTestCase.class);


   private static String deploymentName = "ArquillianTest";


   /**

    * Define the deployment

    * @return The deployment archive

    */

   @Deployment

   public static ResourceAdapterArchive createDeployment()

   {

      ResourceAdapterArchive raa =

         ShrinkWrap.create(ResourceAdapterArchive.class, deploymentName + ".rar");


      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");

      ja.addPackage(TestConnection.class.getPackage());


      raa.addAsLibrary(ja);

      raa.addAsManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");


      return raa;

   }


   //-------------------------------------------------------------------------------------||

   // Tests ------------------------------------------------------------------------------||

   //-------------------------------------------------------------------------------------||


   @Resource(mappedName = "java:/eis/ArquillianTest")

   private TestConnectionFactory connectionFactory;

   

   /**

    * Basic

    * @exception Throwable Thrown if case of an error

    */

   @Test

   public void testBasic() throws Throwable

   {

      assertNotNull(connectionFactory);


      TestConnection c = connectionFactory.getConnection();

      assertNotNull(c);


      c.callMe();

      c.close();

   }

}

The class makes use of the org.jboss.jca.embedded.arquillian.Configuration annotation in order to specify that the deployed archive should be auto activated through the RAActivator bean.

Note

Note that, the name for the ResourceAdapterArchive must end with the .rar extension.

11.3.1.2. Arquillian and ShrinkWrap/Descriptors

The code sample below shows how to use Arquillian to deploy a ShrinkWrap resource adapter archive and activate the resource adapter using the ShrinkWrap/Descriptors API.

This example uses the org.jboss.jca.embedded.arquillian.Configuration annotation to explicit say not to auto activate the resource adapter archive.



/*

 * IronJacamar, a Java EE Connector Architecture implementation

 * Copyright 2012, Red Hat Inc, and individual contributors

 * as indicated by the @author tags. See the copyright.txt file in the

 * distribution for a full listing of individual contributors.

 *

 * This is free software; you can redistribute it and/or modify it

 * under the terms of the GNU Lesser General Public License as

 * published by the Free Software Foundation; either version 2.1 of

 * the License, or (at your option) any later version.

 *

 * This software is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this software; if not, write to the Free

 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.

 */


package org.jboss.jca.embedded.unit;


import org.jboss.jca.arquillian.embedded.Configuration;

import org.jboss.jca.embedded.dsl.resourceadapters11.api.ConnectionDefinitionsType;

import org.jboss.jca.embedded.dsl.resourceadapters11.api.ResourceAdapterType;

import org.jboss.jca.embedded.dsl.resourceadapters11.api.ResourceAdaptersDescriptor;

import org.jboss.jca.embedded.rars.simple.TestConnection;

import org.jboss.jca.embedded.rars.simple.TestConnectionFactory;

import org.jboss.jca.embedded.rars.simple.TestConnectionFactoryImpl;

import org.jboss.jca.embedded.rars.simple.TestConnectionImpl;

import org.jboss.jca.embedded.rars.simple.TestManagedConnectionFactory;

import org.jboss.jca.embedded.rars.simple.TestResourceAdapter;


import java.util.UUID;


import javax.annotation.Resource;


import org.jboss.arquillian.container.test.api.Deployment;

import org.jboss.arquillian.junit.Arquillian;

import org.jboss.logging.Logger;

import org.jboss.shrinkwrap.api.ShrinkWrap;

import org.jboss.shrinkwrap.api.asset.StringAsset;

import org.jboss.shrinkwrap.api.spec.JavaArchive;

import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;

import org.jboss.shrinkwrap.descriptor.api.Descriptors;

import org.jboss.shrinkwrap.descriptor.api.connector15.ConnectorDescriptor;

import org.jboss.shrinkwrap.descriptor.api.connector15.OutboundResourceadapterType;

import org.jboss.shrinkwrap.descriptor.api.connector15.ResourceadapterType;


import org.junit.Test;

import org.junit.runner.RunWith;


import static org.junit.Assert.assertNotNull;


/**

 * Unit test for ShrinkWrap/Descriptors integration

 * 

 * @author <a href="mailto:jesper.pedersen@ironjacamar.org">Jesper Pedersen</a>

 */

@RunWith(Arquillian.class)

@Configuration(autoActivate = false)

public class ShrinkWrapDescriptorsTestCase

{

   // --------------------------------------------------------------------------------||

   // Class Members ------------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   private static Logger log = Logger.getLogger(ShrinkWrapDescriptorsTestCase.class);


   private static String deploymentName = "sd.rar";


   /**

    * Define the resource adapter archive

    * @return The archive

    */

   @Deployment(order = 1)

   public static ResourceAdapterArchive createArchive()

   {

      ConnectorDescriptor raXml = Descriptors.create(ConnectorDescriptor.class, "ra.xml")

         .version("1.5");

      ResourceadapterType rt = raXml.getOrCreateResourceadapter()

         .resourceadapterClass(TestResourceAdapter.class.getName());

      OutboundResourceadapterType ort = rt.getOrCreateOutboundResourceadapter()

         .transactionSupport("NoTransaction").reauthenticationSupport(false);

      org.jboss.shrinkwrap.descriptor.api.connector15.ConnectionDefinitionType cdt =

         ort.createConnectionDefinition()

            .managedconnectionfactoryClass(TestManagedConnectionFactory.class.getName())

            .connectionfactoryInterface(TestConnectionFactory.class.getName())

            .connectionfactoryImplClass(TestConnectionFactoryImpl.class.getName())

            .connectionInterface(TestConnection.class.getName())

            .connectionImplClass(TestConnectionImpl.class.getName());


      ResourceAdapterArchive raa =

         ShrinkWrap.create(ResourceAdapterArchive.class, deploymentName);


      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");

      ja.addPackage(TestConnection.class.getPackage());


      raa.addAsLibrary(ja);

      raa.addAsManifestResource(new StringAsset(raXml.exportAsString()), "ra.xml");


      return raa;

   }


   /**

    * Define the deployment descriptor

    * @return The descriptor

    */

   @Deployment(order = 2)

   public static ResourceAdaptersDescriptor createDeployment()

   {

      ResourceAdaptersDescriptor dashRaXml = Descriptors.create(ResourceAdaptersDescriptor.class, "sd-ra.xml");

      ResourceAdapterType rt = dashRaXml.createResourceAdapter().archive(deploymentName);

      ConnectionDefinitionsType cdst = rt.getOrCreateConnectionDefinitions();

      org.jboss.jca.embedded.dsl.resourceadapters11.api.ConnectionDefinitionType cdt =

         cdst.createConnectionDefinition()

            .className(TestManagedConnectionFactory.class.getName())

            .jndiName("java:/eis/TestConnectionFactory").poolName("TestConnectionFactory");


      return dashRaXml;

   }


   //-------------------------------------------------------------------------------------||

   // Tests ------------------------------------------------------------------------------||

   //-------------------------------------------------------------------------------------||


   @Resource(mappedName = "java:/eis/TestConnectionFactory")

   private TestConnectionFactory connectionFactory;

   

   /**

    * Basic

    * @exception Throwable Thrown if case of an error

    */

   @Test

   public void testBasic() throws Throwable

   {

      assertNotNull(connectionFactory);


      TestConnection c = connectionFactory.getConnection();

      assertNotNull(c);


      c.callMe();

      c.close();

   }

}

11.3.1.3. Arquillian and Byteman

The code sample below shows how to use Arquillian to deploy a ShrinkWrap resource adapter archive and change the allocateConnection of org.jboss.jca.core.connectionmanager.AbstractConnectionManager to throw a ResourceException when the method is called.

The framework used to provide this functionality is called Byteman, which allows developers to change behavior of a method to for example throw an exception. This is called fault injection and can be used to increase code coverage of your project.



/*

 * IronJacamar, a Java EE Connector Architecture implementation

 * Copyright 2012, Red Hat Inc, and individual contributors

 * as indicated by the @author tags. See the copyright.txt file in the

 * distribution for a full listing of individual contributors.

 *

 * This is free software; you can redistribute it and/or modify it

 * under the terms of the GNU Lesser General Public License as

 * published by the Free Software Foundation; either version 2.1 of

 * the License, or (at your option) any later version.

 *

 * This software is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this software; if not, write to the Free

 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.

 */


package org.jboss.jca.arquillian.unit;


import org.jboss.jca.arquillian.embedded.Configuration;

import org.jboss.jca.arquillian.rars.simple.TestConnection;

import org.jboss.jca.arquillian.rars.simple.TestConnectionFactory;

import org.jboss.jca.embedded.dsl.InputStreamDescriptor;


import java.util.UUID;


import javax.annotation.Resource;

import javax.resource.ResourceException;


import org.jboss.arquillian.container.test.api.Deployment;

import org.jboss.arquillian.extension.byteman.api.BMRule;

import org.jboss.arquillian.junit.Arquillian;

import org.jboss.logging.Logger;

import org.jboss.shrinkwrap.api.ShrinkWrap;

import org.jboss.shrinkwrap.api.spec.JavaArchive;

import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;

import org.jboss.shrinkwrap.descriptor.api.Descriptor;


import org.junit.Test;

import org.junit.runner.RunWith;


import static org.junit.Assert.assertNotNull;

import static org.junit.Assert.fail;


/**

 * Unit test for Byteman integration

 * 

 * @author <a href="mailto:jesper.pedersen@ironjacamar.org">Jesper Pedersen</a>

 */

@RunWith(Arquillian.class)

@Configuration(autoActivate = false)

public class BytemanBMTestCase

{

   // --------------------------------------------------------------------------------||

   // Class Members ------------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   private static Logger log = Logger.getLogger(BytemanBMTestCase.class);


   /**

    * Define the deployment

    * @return The deployment archive

    */

   @Deployment(order = 1)

   public static ResourceAdapterArchive createDeployment()

   {

      ResourceAdapterArchive raa =

         ShrinkWrap.create(ResourceAdapterArchive.class, "byteman.rar");


      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");

      ja.addPackage(TestConnection.class.getPackage());


      raa.addAsLibrary(ja);

      raa.addAsManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");


      return raa;

   }


   /**

    * Define the activation

    * @return The deployment archive

    */

   @Deployment(order = 2)

   public static Descriptor createDescriptor()

   {

      ClassLoader cl = BytemanBMTestCase.class.getClassLoader();

      InputStreamDescriptor isd = new InputStreamDescriptor("byteman-ra.xml", 

                                                            cl.getResourceAsStream("byteman-ra.xml"));

      return isd;

   }


   //-------------------------------------------------------------------------------------||

   // Tests ------------------------------------------------------------------------------||

   //-------------------------------------------------------------------------------------||


   @Resource(mappedName = "java:/eis/BytemanTest")

   private TestConnectionFactory connectionFactory;


   /**

    * Byteman

    * @exception Throwable Thrown if case of an error

    */

   @Test

   @BMRule(name = "Throw exception on allocateConnection",

           targetClass = "org.jboss.jca.core.connectionmanager.AbstractConnectionManager",

           targetMethod = "allocateConnection",

           action = "throw new javax.resource.ResourceException()")

   public void testByteman() throws Throwable

   {

      assertNotNull(connectionFactory);


      TestConnection c = null;

      try

      {

         c = connectionFactory.getConnection();

         fail("Got a connection");

      }

      catch (ResourceException re)

      {

         // Ok

      }

      catch (Throwable t)

      {

         fail(t.getMessage());

         throw t;

      }

      finally

      {

         if (c != null)

            c.close();

      }

   }

}

See the Byteman web site for a detailed description of the project and additional documentation.

11.3.1.4. Arquillian and @ArquillianResource

The Arquillian integration allows the internally used org.jboss.jca.embedded.Embedded or javax.naming.Context instances to be injected into the test case using




import org.jboss.jca.embedded.Embedded;

import javax.naming.Context;

import org.jboss.arquillian.test.api.ArquillianResource;


@RunWith(Arquillian.class)

public class ResourceProviderTestCase

{

   @ArquillianResource

   private Embedded embedded;


   @ArquillianResource

   private Context context;

This will allow direct access to the APIs inside the test case.

11.3.1.5. IronJacamar integration

The code sample below shows how to use Arquillian to deploy a ShrinkWrap resource adapter archive and inject the IronJacamar metadata repository into the test case such that assertions can be made.

The IronJacamar container features various components that makes up the entire Java EE Connector Architecture container. The available list of components can be viewed in the configuration of the container or through the management console under the Kernel category.



/*/*

 * IronJacamar, a Java EE Connector Architecture implementation

 * Copyright 2011, Red Hat Inc, and individual contributors

 * as indicated by the @author tags. See the copyright.txt file in the

 * distribution for a full listing of individual contributors.

 *

 * This is free software; you can redistribute it and/or modify it

 * under the terms of the GNU Lesser General Public License as

 * published by the Free Software Foundation; either version 2.1 of

 * the License, or (at your option) any later version.

 *

 * This software is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this software; if not, write to the Free

 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.

 */


package org.jboss.jca.arquillian.unit;


import org.jboss.jca.arquillian.embedded.Configuration;

import org.jboss.jca.arquillian.embedded.Inject;

import org.jboss.jca.arquillian.rars.simple.TestConnection;

import org.jboss.jca.arquillian.rars.simple.TestConnectionFactory;

import org.jboss.jca.core.spi.mdr.MetadataRepository;


import java.util.UUID;


import javax.annotation.Resource;


import org.jboss.arquillian.container.test.api.Deployment;

import org.jboss.arquillian.junit.Arquillian;

import org.jboss.logging.Logger;

import org.jboss.shrinkwrap.api.ShrinkWrap;

import org.jboss.shrinkwrap.api.spec.JavaArchive;

import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;


import org.junit.Test;

import org.junit.runner.RunWith;


import static org.junit.Assert.assertNotNull;

import static org.junit.Assert.assertTrue;


/**

 * Unit test for Arquillian integration and injecting

 * 

 * @author <a href="mailto:jesper.pedersen@ironjacamar.org">Jesper Pedersen</a>

 */

@RunWith(Arquillian.class)

@Configuration(autoActivate = true)

public class InjectTestCase

{

   // --------------------------------------------------------------------------------||

   // Class Members ------------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   private static Logger log = Logger.getLogger(InjectTestCase.class);


   /**

    * Define the deployment

    * @return The deployment archive

    */

   @Deployment

   public static ResourceAdapterArchive createDeployment()

   {

      ResourceAdapterArchive raa =

         ShrinkWrap.create(ResourceAdapterArchive.class, "ArquillianTest.rar");


      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");

      ja.addPackage(TestConnection.class.getPackage());


      raa.addAsLibrary(ja);

      raa.addAsManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");


      return raa;

   }


   //-------------------------------------------------------------------------------------||

   // Tests ------------------------------------------------------------------------------||

   //-------------------------------------------------------------------------------------||


   @Resource(mappedName = "java:/eis/ArquillianTest")

   private TestConnectionFactory connectionFactory;

 

   @Inject(name = "MDR")

   private MetadataRepository mdr;

  

   /**

    * Basic

    * @exception Throwable Thrown if case of an error

    */

   @Test

   public void testBasic() throws Throwable

   {

      assertNotNull(connectionFactory);

      assertNotNull(mdr);

      assertNotNull(mdr.getResourceAdapters());

      assertTrue(mdr.getResourceAdapters().size() == 1);

   }

}

11.3.2. Advanced usage

11.3.2.1. ShrinkWrap

The code sample below shows an advanced usage of deploying a ShrinkWrap resource adapter archive into the IronJacamar Embedded environment.



/*

 * IronJacamar, a Java EE Connector Architecture implementation

 * Copyright 2012, Red Hat Inc, and individual contributors

 * as indicated by the @author tags. See the copyright.txt file in the

 * distribution for a full listing of individual contributors.

 *

 * This is free software; you can redistribute it and/or modify it

 * under the terms of the GNU Lesser General Public License as

 * published by the Free Software Foundation; either version 2.1 of

 * the License, or (at your option) any later version.

 *

 * This software is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this software; if not, write to the Free

 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.

 */


package org.jboss.jca.embedded.unit;


import org.jboss.jca.embedded.Embedded;

import org.jboss.jca.embedded.EmbeddedFactory;

import org.jboss.jca.embedded.rars.simple.TestConnection;

import org.jboss.jca.embedded.rars.simple.TestConnectionFactory;


import java.util.UUID;


import javax.naming.Context;

import javax.naming.InitialContext;

import javax.naming.NamingException;


import org.jboss.logging.Logger;

import org.jboss.shrinkwrap.api.ShrinkWrap;

import org.jboss.shrinkwrap.api.spec.JavaArchive;

import org.jboss.shrinkwrap.api.spec.ResourceAdapterArchive;


import org.junit.AfterClass;

import org.junit.BeforeClass;

import org.junit.Test;

import static org.junit.Assert.*;


/**

 * Test cases for deploying resource adapter archives (.RAR)

 * using ShrinkWrap

 * 

 * @author <a href="mailto:jesper.pedersen@ironjacamar.org">Jesper Pedersen</a>

 */

public class ShrinkWrapTestCase

{

   // --------------------------------------------------------------------------------||

   // Class Members ------------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   private static Logger log = Logger.getLogger(ShrinkWrapTestCase.class);


   private static final String JNDI_PREFIX = "java:/eis/";


   /*

    * Embedded

    */

   private static Embedded embedded;


   // --------------------------------------------------------------------------------||

   // Tests --------------------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   /**

    * Basic ShrinkWrap ResourceAdapterArchive test case

    * @exception Throwable Thrown if case of an error

    */

   @Test

   public void testBasic() throws Throwable

   {

      Context context = null;


      String name = UUID.randomUUID().toString();


      ResourceAdapterArchive raa =

         ShrinkWrap.create(ResourceAdapterArchive.class, name + ".rar");


      JavaArchive ja = ShrinkWrap.create(JavaArchive.class, UUID.randomUUID().toString() + ".jar");

      ja.addPackage(TestConnection.class.getPackage());


      raa.addAsLibrary(ja);

      raa.addAsManifestResource("simple.rar/META-INF/ra.xml", "ra.xml");


      try

      {

         embedded.deploy(raa);


         context = new InitialContext();

         TestConnectionFactory tcf = (TestConnectionFactory)context.lookup(JNDI_PREFIX + name);

         assertNotNull(tcf);


         TestConnection tc = tcf.getConnection();

         tc.callMe();

         tc.close();

      }

      catch (Exception t)

      {

         log.error(t.getMessage(), t);

         fail(t.getMessage());

      }

      finally

      {

         if (context != null)

         {

            try

            {

               context.close();

            }

            catch (NamingException ne)

            {

               // Ignore

            }

         }


         embedded.undeploy(raa);

      }

   }


   // --------------------------------------------------------------------------------||

   // Lifecycle Methods --------------------------------------------------------------||

   // --------------------------------------------------------------------------------||


   /**

    * Lifecycle start, before the suite is executed

    * @throws Throwable throwable exception 

    */

   @BeforeClass

   public static void beforeClass() throws Throwable

   {

      // Create and set an embedded JCA instance

      embedded = EmbeddedFactory.create();


      // Startup

      embedded.startup();

   }


   /**

    * Lifecycle stop, after the suite is executed

    * @throws Throwable throwable exception 

    */

   @AfterClass

   public static void afterClass() throws Throwable

   {

      // Shutdown embedded

      embedded.shutdown();


      // Set embedded to null

      embedded = null;

   }

}

Note

Note that, the name for the ResourceAdapterArchive must end with the .rar extension.

11.3.2.2. Embedded

The code sample below shows a simple usage of deploying a pre-assembled resource adapter archive into the IronJacamar Embedded environment.



import org.jboss.jca.embedded.Embedded;

import org.jboss.jca.embedded.EmbeddedFactory;


import java.net.URL;


import javax.naming.Context;

import javax.naming.InitialContext;

import javax.naming.NamingException;


import org.junit.AfterClass;

import org.junit.BeforeClass;

import org.junit.Test;

import static org.junit.Assert.*;


public class MyTestCase

{

   /** Embedded */

   private static Embedded embedded;


   /** JNDI prefix */

   private static final String JNDI_PREFIX = "java:/eis/";


   /**

    * Simple test to verify deployment of myresourceadapter.rar

    * @throws Throwable throwable exception 

    */

   @Test

   public void testDeployment() throws Throwable

   {

      URL archive = MyTestCase.class.getResource("myresourceadapter.rar");

      Context context = null;

 

      try

      {

         embedded.deploy(archive);


         context = new InitialContext();

         Object o = context.lookup(JNDI_PREFIX + "myresourceadapter");

         assertNotNull(o);

      }

      catch (Throwable t)

      {

         fail(t.getMessage());

      }

      finally

      {

         embedded.undeploy(archive);


         if (context != null)

         {

            try

            {

               context.close();

            }

            catch (NamingException ne)

            {

               // Ignore

            }

         }

      }

   }


   @BeforeClass

   public static void beforeClass() throws Throwable

   {

      // Create an embedded JCA instance

      embedded = EmbeddedFactory.create();


      // Startup

      embedded.startup();

   }


   @AfterClass

   public static void afterClass() throws Throwable

   {

      // Shutdown

      embedded.shutdown();

   }

}

Note

Note that, the url for the archive must end with the .rar extension - either representing a file or a directory.

See the IronJacamar Embedded API documentation for additional functionality.

11.3.2.3. Automatic activation of archives

IronJacamar features a bean called RAActivator which will automatic create a JNDI binding for connection factories and administration objects. However, sometimes it is of benefit to define these bindings in a -ra.xml file, and therefore RAActivator has to be disabled during that deployment phase.

This done by using the following code snippet



import org.jboss.jca.deployers.fungal.RAActivator;


// Disable RAActivator

RAActivator raa = embedded.lookup("RAActivator", RAActivator.class);


if (raa == null)

   throw new IllegalStateException("RAActivator not defined");


raa.setEnabled(false);


embedded.deploy("myrar.rar");

embedded.deploy("myrar-ra.xml");


raa.setEnabled(true);

which disables the bean, does the deployments and then reenables the bean again.

Chapter 12. EIS test server

The IronJacamar EIS test server provides a framework for emulating an Enterprise Information System such that no installation is needed.

12.1. Overview
12.2. Apache Ant
12.3. Apache Maven

Testing an Enterprise Information System can be a complex task, as their installation can quite complex and specific to a certain platform architecture.

As Java developers, and resource adapter developers in particularly, we are interested in a setup that will allow us to test the resource adapter against the EIS with as little difficulty as possible.

Having access to a component that easy integrates into our testing environment, and acts as the EIS in question is of benefit.

12.1. Overview

The EIS test server contains the following interface



/*

 * IronJacamar, a Java EE Connector Architecture implementation

 * Copyright 2012, Red Hat Inc, and individual contributors

 * as indicated by the @author tags. See the copyright.txt file in the

 * distribution for a full listing of individual contributors.

 *

 * This is free software; you can redistribute it and/or modify it

 * under the terms of the GNU Lesser General Public License as

 * published by the Free Software Foundation; either version 2.1 of

 * the License, or (at your option) any later version.

 *

 * This software is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

 * Lesser General Public License for more details.

 *

 * You should have received a copy of the GNU Lesser General Public

 * License along with this software; if not, write to the Free

 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA

 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.

 */

package org.jboss.jca.test.eis;


import java.io.InputStream;

import java.io.OutputStream;


/**

 * This interface represents a session between a resource adapter

 * and an Enterprise Information System

 *

 * Once the <code>handle</code> method returns the socket where

 * the communication takes place is closed

 *

 * @author <a href="mailto:jesper.pedersen@ironjacamar.org">Jesper Pedersen</a>

 */

public interface Handler

{

   /**

    * Handle an interaction with a client

    * @param is The input stream

    * @param os The output stream

    */

   public void handle(InputStream is, OutputStream os);

}

which represents a session between the resource adapter and the EIS.

The java.io.InputStream is the incoming communication coming from the resource adapter, and the java.io.OutputStream is the EIS' response to the request.

Once the method returns the socket between the resource adapter and the EIS is closed.

This means that the implementation of the Handler interface will represent the binary protocol between the resource adapter and the EIS. To the resource adapter it will look as it is communicating with the real Enterprise Information System installation.

12.2. Apache Ant

The Apache Ant tasks for starting and stopping the EIS test server are defined as the following


<taskdef name="start"
         classname="org.jboss.jca.test.eis.ant.Start"
         classpathref="main.lib.path.id"/>

<taskdef name="stop"
         classname="org.jboss.jca.test.eis.ant.Stop"
         classpathref="main.lib.path.id"/>

where main.lib.path.id contains the ironjacamar-test-eis.jar file.

The start task is used, like


<start host="localhost" port="1400"
       handler="org.jboss.jca.test.eis.EchoHandler">
  <classpath>
    <pathelement location="${build.eis.dir}/test"/>
  </classpath>
</start>

which starts the EIS test server on localhost using port 1400 with an implementation of the Handler interface of org.jboss.jca.test.eis.EchoHandler and a classpath of ${build.eis.dir}/test.

The stop task is used, like


<stop host="localhost" port="1400"/>

which stops the EIS test server on localhost using port 1400.

Between the start and stop tasks the resource adapters unit tests can be executed.

12.3. Apache Maven

The Apache Maven mojos for starting and stopping the EIS test server are defined as the following

       
<build>
  <plugins>
    <plugin>
      <groupId>org.jboss.ironjacamar</groupId>
      <artifactId>ironjacamar-test-eis</artifactId>
      <!-- The version of the plugin you want to use -->
      <version>1.1.0.Final</version>
      <executions>
        <execution>
          <goals>
            <goal>start</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <host>localhost</host>
        <port>1400</port>
        <handler>org.jboss.jca.test.eis.EchoHandler</handler>
        <classpath>
          <param>target/test-classes</param>
        </classpath>
      </configuration>
    </plugin>
    <plugin>
      <groupId>org.jboss.ironjacamar</groupId>
      <artifactId>ironjacamar-test-eis</artifactId>
      <!-- The version of the plugin you want to use -->
      <version>1.1.0.Final</version>
      <executions>
        <execution>
          <goals>
            <goal>stop</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <host>localhost</host>
        <port>1400</port>
      </configuration>
    </plugin>
  </plugins>
</build>

The start mojo will run in the process-test-classes phase, and the stop mojo will run in the test phase.

Chapter 13. Community

The forum is located at http://community.jboss.org/en/ironjacamar/dev

13.1. Website
13.2. User forum
13.3. Developer forum
13.4. Issue tracking

13.4. Issue tracking

We are using JIRA to manage our issues in the project.

These are divided into the following categories

Feature Request: A feature that you would like see implemented.
Bug: A software defect.

For all of these you should post your request to our user forum first.

The rest of the categories are for team use only.

Our issue tracking system located at http://issues.jboss.org/browse/JBJCA

Chapter 14. Troubleshooting

If you think you have found a bug you should verify this by posting to our forum first.

14.1. I think I have found a bug
14.2. I would like to implement a feature
14.3. How do I ?

14.1. I think I have found a bug

Our forum is located at http://community.jboss.org/en/ironjacamar

You can also search our issue tracking system located at http://issues.jboss.org/browse/JBJCA

14.2. I would like to implement a feature

So you have found an area where you are missing a feature and would like to submit a patch for it, great !

There are a couple of steps to get a feature included

First, you should create a new thread in our development forum where you describe the feature, its design and implementation.

Once there is an agreement on the feature and the design you should proceed with creating the patch.

To maximize your chances of getting the feature in the official build as soon as possible make sure that you run through the following steps:

ant clean test
ant clean checkstyle
ant clean findbugs
ant clean jacoco

All these should show that,

All your test cases for the feature is passing
Your code is correctly formatted according to project rules
There isn't any bug reports from the Findbugs environment
There is full code coverage based on the JaCoCo report

when done, create a JIRA task (Feature Request) in our JIRA environment and attach the unified diff formatted patch. See the developer guide for additional details.

Happy Coding !

14.3. How do I ?

We can't cover every single issue in this guide, so feel free to drop by our forums to see if a solution has already been provided. Otherwise feel free to ask your question there.

Our forum is located at http://community.jboss.org/en/ironjacamar

Appendix A. Schemas