Chapter 4. Configuration

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

Note, that an existing enlisted connection is allowed to be obtained. This can be disallowed by setting the system property ironjacamar.allow_marked_for_rollback_fast_fail to true.

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.1.5. Disable `setRollbackOnly` calls

IronJacamar calls transaction.setRollbackOnly() when the ManagedConnection has a fatal error occur on it after calling the transaction.delistResource(xaResource, XAResource.TMFAIL) method.

IronJacamar has a system property called ironjacamar.rollback_on_fatal_error which is either a value of true, false or a ',' separated list of pool names where setRollbackOnly shouldn't be called.

Warning

By disabling the setRollbackOnly call it is up to the transaction manager to make sure that the outcome of transaction is correctly handled, since the associated XAResource instance no longer can access the Enterprise Information System, and hence implementation specific behavior.

4.2. Logging service

The IronJacamar container uses JBoss Logging framework as the implementation.

The configuration is done in the

config/logging.properties

file.

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

4.3. Transaction service

The IronJacamar container uses Narayana its transaction implementation.

The configuration is done in the

config/transaction.xml

file.

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

file.

4.4.1.1. Configuration

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






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



  <!-- PicketBox -->

  <bean name="PicketBoxSocket"

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

  </bean> 



  <!-- DistributedWorkManagerSocket -->

  <bean name="DistributedWorkManagerSocket"

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

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



    <!-- The name -->

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



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

    <property name="ShortRunningThreadPool">

       <inject bean="DistributedWorkManagerShortRunningThreadPoolSocket"/>

    </property>



    <!-- The XA terminator -->

    <property name="XATerminator">

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

    </property>



    <!-- The callback security module -->

    <property name="CallbackSecurity">

       <inject bean="Callback"/>

    </property>



    <!-- The security integration module -->

    <property name="SecurityIntegration">

       <inject bean="PicketBoxSocket"/>

    </property>



    <!-- The policy -->

    <property name="Policy">

       <inject bean="DistributedWorkManagerPolicySocket"/>

    </property>



    <!-- The selector -->

    <property name="Selector">

       <inject bean="DistributedWorkManagerSelectorSocket"/>

    </property>



    <!-- The transport -->

    <property name="Transport">

       <inject bean="DistributedWorkManagerTransportSocket"/>

    </property>



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

  </bean>



  <!-- DistributedBootstrapContextSocket -->

  <bean name="DistributedBootstrapContextSocket"

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

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

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

    <property name="TransactionSynchronizationRegistry">

       <inject bean="TransactionSynchronizationRegistry"/>

    </property>

    <property name="WorkManagerName">

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

    </property>

    <property name="XATerminator">

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

    </property>

  </bean>



</deployment>

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.jca.core.spi.security.SubjectFactory"

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

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

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

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

</bean>

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

file.

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 IronJacamar project features a web server which is used to serve web archive deployments. More information about Jetty can be found at the homepage.

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.