JBoss

This section describes how to setup the Infinity Process Platform Portal and the Process Engine in JBoss. Many figures are from the Windows operating system but any supported JBoss platform can be used.

Prerequisites

The following sections discuss prerequisites that must be performed before Infinity Process Platform can be deployed within a JBoss application server.

A basic understanding of JBoss Administration, Enterprise Application Archive (EAR), and Web Application Archive (WAR) files is required from this point forward.

Note
We recommend to enable 2nd-level caching for production deployments to optimize the performance of a secure JCR deployment. For details refer to section Tuning by using Hazelcast and to chapter Optimizing the Performance of secure JCR Deployments accordingly.

JBoss Download and Installation

Please refer to the Infinity Release Notes for details on the currently supported JBoss version. Make sure your JAVA_HOME variable is set correctly in case you start the JBoss server from the command line.

To prepare the JBoss deployment:

  1. Download JBoss.
  2. Extract the ZIP-File.
  3. Copy %JBOSS_HOME%/server/default to %JBOSS_HOME%/server/<serverName>
  4. The server can be started with
    %JBOSS_HOME%/bin/run.bat -c <serverName>

If a server name is used other than default, edit the JBoss startup script in %JBOSS_HOME%/bin and add the following JVM system property to the command line.

-Djboss.server.name=<serverName>

Additional JBoss system properties can be set in the startup script. Please refer to the JBoss documentation for more information regarding system properties.

Required RESTEasy Upgrade within JBoss 7.1

RESTEasy is a portable implementation of the JAX-RS specification and bundled with JBoss 7.1. Note that this stack needs to be upgraded to version 3.x. Please refer to Upgrading Resteasy Within JBoss AS 7 of the RESTEasy JAX-RS JBoss documentation site for details.

JDBC Drivers

Copy JDBC drivers used to access the Infinity Process Platform Audit Trail Database to the following directory, %JBOSS_HOME%/server/ <serverName>/lib.

Predefined Deployment Configurations for JBoss

The Infinity Process Platform provides preconfigured deployment configuration for JBoss as Maven archetype templates. You can download them from the Infinity Process Platform artifactory matching your requirements. The following deployment configurations for JBoss are provided to prepare a Infinity Process Platform Portal WAR/EAR deployment for JBoss:

Please refer to chapter Creating a Runtime Environment with Apache Maven in the Installation Guide section Other Archetypes of our Infinity Process Platform Wiki Maven/Basic Setup page for details on how to retrieve these configurations.

Note that for JBoss EAP 6.3 and 6.4 the JBoss version 7.1 Spring deployment ipp-archetype-jb71-ipp-portal-war is compatible and should be used, if required. On the other hand, in case you like to prepare an EAR deployment for JBoss 7.1, you can use archetype ipp-archetype-jb6-eap-ipp-ear for JBoss EAP 6.3 and 6.4.

Preparing the Deployment

To prepare a deployment on JBoss, perform the following steps:

  1. Start JBoss via
    <JBoss-Home>/bin/standalone.bat
  2. Add user for administration console (http://localhost:9990/console):
    <JBoss-Home>/bin/add-user.bat
  3. Add deployments in the administration console

DataSource (MySQL)

JBoss 7 uses a module system for class loading. Therefore a new module for the database driver jar has to be created. The module has to be created in folder <JBoss-Home>/modules:

  1. Create a new folder com/mysql/main in folder <JBoss-Home>/modules
  2. Create a new file module.xml with following content in that folder:
    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="com.mysql">
       <resources>
          <resource-root path="mysql-connector-java-5.1.21-bin.jar" />
       </resources>
       <dependencies>
          <module name="javax.api" />
          <module name="javax.transaction.api"/>
       </dependencies>
    </module>
  3. Copy the mysql database driver mysql-connector-java-5.1.21-bin.jar into folder <JBoss-Home>/modules/com/mysql/main.
  4. Add a driver reference in server configuration file <JBoss-Home>/standalone/configuration/standalone.xml in 'drivers' element:
    <driver name="mysql" module="com.mysql">
       <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
    </driver>
  5. Add a datasource in server configuration file <JBoss-Home>/standalone/configuration/standalone.xml in 'datasources' element:
    <xa-datasource jndi-name="java:/AuditTrail.DataSource" pool-name="AuditTrailDS" enabled="true" use-java-context="true" use-ccm="false">
       <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/ipp</xa-datasource-property>
       <driver>mysql</driver>
       <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
       <xa-pool>
           <no-tx-separate-pools>true</no-tx-separate-pools>
           <min-pool-size>1</min-pool-size>
           <max-pool-size>10</max-pool-size>
       </xa-pool>
       <timeout>
           <idle-timeout-minutes>10</idle-timeout-minutes>
       </timeout>
       <security>
           <user-name>carnot</user-name>
           <password>ag</password>
       </security>
       <validation>
           <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
           <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
       </validation>
    </xa-datasource>

Web Service Endpoint Issue

An issue with already registered Web Service endpoints might occur because JBoss already starts a Web service. To prevent the issue, comment out the following lines in file <JBoss-Home>/standalone/configuration/standalone.xml:

<!--  subsystem xmlns="urn:jboss:domain:webservices:1.1">
   <modify-wsdl-address>true</modify-wsdl-address>
   <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
   <endpoint-config name="Standard-Endpoint-Config"/>
   <endpoint-config name="Recording-Endpoint-Config">
       <pre-handler-chain name="recording-handlers" protocol-bindings="##SOAP11_HTTP ##SOAP11_HTTP_MTOM ##SOAP12_HTTP ##SOAP12_HTTP_MTOM">
           <handler name="RecordingHandler" class="org.jboss.ws.common.invocation.RecordingServerHandler"/>
       </pre-handler-chain>
   </endpoint-config>
</subsystem> -->

Jackrabbit Configuration

  1. Create a new folder javax/jcr/main in folder <JBoss-Home>/modules
  2. Create a new file module.xml with following content in that folder:
    <?xml version="1.0" encoding="UTF-8"?>
    
    <module xmlns="urn:jboss:module:1.0" name="javax.jcr">
    	<resources>
            <resource-root path="jcr-2.0.jar"/>
        </resources>
    	<dependencies>
    		<module name="javax.transaction.api" export="true"/>
    	</dependencies>
    </module>
  3. Copy jcr-2.0.jar to folder <JBoss-Home>/modules/javax/jcr/main.
  4. Copy the jackrabbit-jca-2.6.1.rar to folder <JBoss-Home>/standalone/deployments. You can download the jackrabbit-jca-2.6.1-infinity02.rar file from the following location: https://infinity.sungard.com/repository/simple/ipp-3rd-party/org/apache/jackrabbit/jackrabbit-jca/2.6.1-infinity02/jackrabbit-jca-2.6.1-infinity02.rar.
    In the rar file the META-INF/MANIFEST.MF has to be changed by adding the following line to the end of the file:
    Dependencies: javax.jcr export,org.slf4j
    Further the jars logback-classic-1.0.0.jar and logback-core-1.0.0.jar have to be removed from rar file to use the JBoss logging framework.

    Additionally note:
    In case you like to use DOCX files, e.g. for templating, and you have a local jackrabbit-jca-2.6.1.rar which was downloaded via the earlier jackrabbit-jca-2.6.1-infinity01.rar file version, do one of the following:

  5. In <JBoss-Home>/standalone/configuration/standalone.xml the following content should be added inside <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0"> in the <resource-adapters> element:
    <resource-adapter>
       <archive>
           jackrabbit-jca-2.6.1.rar
       </archive>
       <transaction-support>
           XATransaction
       </transaction-support>
       <connection-definitions>
           <connection-definition class-name="org.apache.jackrabbit.jca.JCAManagedConnectionFactory" jndi-name="java:/jcr/jackrabbit" enabled="true" use-java-context="true" use-ccm="false">
               <config-property name="configFile">
                    C:/tmp/configuration/repository.xml
               </config-property>
               <config-property name="bindSessionToTransaction">
                   true
               </config-property>
               <config-property name="homeDir">
                   C:/tmp/jcrjboss7
               </config-property>
           </connection-definition>
       </connection-definitions>
    </resource-adapter>
  6. Copy the repository.xml configuration file to <JBoss-Home>/standalone/configuration folder.
  7. Due to an issue with validation when deploying Jackrabbit on JBoss ( see https://issues.apache.org/jira/browse/JCR-3241), the archive-validation should be disabled within the JCA subsystem in <JBoss-Home>/standalone/configuration/standalone.xml as a workaround:
       <subsystem xmlns="urn:jboss:domain:jca:1.1">
       <archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>
  8. Set up a global module for jcr-2.0.jar to be accessible to all deployments. In <subsystem xmlns="urn:jboss:domain:ee:1.0"> add the following lines:
    <global-modules>
       <module name="javax.jcr" slot="main" />            
    </global-modules>

JMS Configuration

In <JBoss-Home>/standalone/configuration/standalone.xml the following content should be added inside <subsystem xmlns="urn:jboss:domain:messaging:1.1">. The following issue is fixed since JBoss EAP 6.2 but if JBoss 7.1 is used the connection-factory dummyCF has to be created as workaround due to the following JBoss issue https://issues.jboss.org/browse/AS7-5538:

<hornetq-server>
   <connectors>
       <in-vm-connector name="in-vm" server-id="0"/>
   </connectors>
   <acceptors>
       <in-vm-acceptor name="in-vm" server-id="0"/>
   </acceptors>
   <jms-connection-factories>
   <--JBoss 7.1 Only -->
       <connection-factory name="dummyCF">
           <connectors>
               <connector-ref connector-name="in-vm"/>
           </connectors>
           <entries>
               <entry name="java:jboss/exported/jms/dummyCF"/>
           </entries>
       </connection-factory>
       <pooled-connection-factory name="hornetq-ra">
           <connectors>
              <connector-ref connector-name="in-vm"/>
           </connectors>
           <entries>
              <entry name="java:/CarnotConnectionFactory"/>
           </entries>
           <transaction mode="xa"/>
       </pooled-connection-factory>
   </jms-connection-factories>
   <jms-destinations>
       <jms-queue name="IppApplicationQueue">
           <entry name="java:/queue/CarnotApplicationQueue"/>
       </jms-queue>
       <jms-queue name="IppSystemQueue">
           <entry name="java:/queue/CarnotSystemQueue"/>
       </jms-queue>
       <jms-queue name="IppDaemonQueue">
           <entry name="java:/queue/CarnotDaemonQueue"/>
       </jms-queue>
   </jms-destinations>
</hornetq-server>

Setting up additional Jackrabbit VFS Repositories

To set up additional Jackrabbit VFS repositories in JBoss, you need to configure a new connection factory on the server using a different repository home and JNDI name.

This resource can then be bound using the DocumentManagementService#bindRepository API. Please refer to chapter Managing Document Repositories of the Programming Guide for details.

Tuning by using Hazelcast

You can use Hazelcast for tuning via retrieving entities from in-memory cache. Hazelcast is a clustering and scalable data distribution platform. For detailed information on Hazelcast refer to http://www.hazelcast.com/product.jsp.

For details on tuning via an in-memory cache in Infinity refer to chapter Retrieving Entities from In-Memory Cache in the Developer Handbook.

Example Use Case

The following examples demonstrates the usage of Hazelcast on WebLogic 10.3. TheInfinity Process Platform provides a prepared RAR file to be deployed with WebLogic.

Separate RAR deployment

To perform a separate RAR deployment, copy the artifact

  1. Copy the artifact com.hazelcast:hazelcast:2.4:rar to the %JBOSS_HOME%/server/default/lib folder ( https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast-ra/2.4-stardust03/hazelcast-ra-2.4-stardust03.rar ) of your JBoss application server.
  2. Deploy the resource adapter com.hazelcast:hazelcast-ra:2.4:rar with the following adjustments:
    1. The file ra.xml in META-INF/ folder of the RAR file as well as the hazelcast-ra-2.4.jar file need to be adjusted such that the line
      <icon></icon>
      is removed
    2. A file ending with -ds.xml, residing in %JBOSS_HOME%/server/default/deploy, and having the following content can be used as a data source in order to make the Hazelcast connection factory available under java:/HazelcastCF in the JNDI tree:
       <?xml version="1.0" encoding="UTF-8"?>
         <!DOCTYPE connection-factories
            PUBLIC "-//JBoss//DTD JBOSS JCA Config 1.5//EN"
               "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd">
      
         <connection-factories> 
            <tx-connection-factory>
               <local-transaction/>
               <track-connection-by-tx>true</track-connection-by-tx>
               <jndi-name>HazelcastCF</jndi-name>
               <rar-name>hazelcast-ra-2.4.rar</rar-name>
               <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> 
            </tx-connection-factory>
         </connection-factories>
         
  3. Optionally put an appropriate hazelcast.xml on the classpath of your EAR. Otherwise a default configuration will be taken from hazelcast-ra-2.4.jar.

RAR inside EAR deployment

To perform a RAR inside EAR deployment perform the following steps:

  1. Copy hazelcast-ra-2.4-stardust03.rar (download from https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast-ra/2.4-stardust03/hazelcast-ra-2.4-stardust03.rar) to /standalone/deployments
  2. Add hazelcast.xml to your classpath
  3. Add the following lines to the standalone.xml file:
    <resource-adapters>
       <resource-adapter>
           <archive>hazelcast-ra-2.4-stardust03.rar</archive>
           <transaction-support>XATransaction</transaction-support>
           <connection-definitions>
               <connection-definition class-name="com.hazelcast.jca.ManagedConnectionFactoryImpl" jndi-name="java:/HazelcastCF" use-ccm="false" />
          </connection-definitions>
       </resource-adapter>
          
  4. Add the following to your jboss-web.xml file:
    <resource-ref>
       <res-ref-name>cache/HazelcastCF</res-ref-name>
       <jndi-name>java:/HazelcastCF</jndi-name>
    </resource-ref>
  5. Extend your web.xml file with the following lines:
    <resource-ref>
       <res-ref-name>cache/HazelcastCF</res-ref-name>
       <res-type>com.hazelcast.jca.HazelcastConnectionFactoryImpl</res-type>
       <res-auth>Container</res-auth>
    </resource-ref>
  6. Create modules for hazelcast-2.4-stardust03.jar and hazelcast-ra-2.4-stardust03.jar and add them to global modules in standalone.xml:
  7. Add Hazelcast modules to global modules in standalone.xml:
    <subsystem xmlns="urn:jboss:domain:ee:1.0">
       <ear-subdeployments-isolated>false</ear-subdeployments-isolated>
       <global-modules>
           <module name="javax.jcr" slot="main"/>
           <module name="com.hazelcast" slot="main"/>
           <module name="com.hazelcast.ra" slot="main"/>
       </global-modules>
    </subsystem>
  8. Set the following properties in your carnot.properties file to enable Hazelcast caching:
    Infinity.Engine.Caching = true
    Infinity.Engine.Caching.CacheFactory = org.eclipse.stardust.engine.core.cache.hazelcast.HazelcastCacheFactory
    
    Infinity.Engine.Caching.Hazelcast.TxMode = rw
    Infinity.Engine.Caching.Hazelcast.ConnectionFactoryJndiName = HazelcastCF
    Infinity.Engine.Caching.Hazelcast.GlobalCacheName = ipp-2nd-level-cache
       
  9. In ra.xml config-properties have to be initialized as JBoss does not accept empty string values. For config-property connectionTracingEvents a value e.g. FACTORY_INIT has to be set:
    <config-property>
       <description>Comma separated list of FACTORY_INIT, CREATE, TX_START, TX_COMPLETE, CLEANUP and DESTROY to
          trace connection events</description>
       <config-property-name>connectionTracingEvents</config-property-name>
       <config-property-type>java.lang.String</config-property-type>
       <config-property-value>FACTORY_INIT</config-property-value>
    </config-property>

Known Restrictions

Limitations with JBoss 7.1

The following modifications need to be applied in the JBoss 7.1 server:

Due to an issue, the JBoss default jsf implementation cannot be changed as param WAR_BUNDLES_JSF_IMPL is not working in JBoss 7.1.1. (WAR file using WAR_BUNDLES_JSF_IMPL embedded in an EAR file fails deployment). It is caused by the issue: (JSF Version retrieved from deployment unit instead of top level deployment unit)

As a workaround, in com/sun/jsf-impl/main module in jsf-impl-2.1.7-jbossorg-2.jar/META-INF: the .tld files have to be renamed to e.g. *-tmp.tld.

Limitations with JBoss 7.1 for EJB3 Deployment

While deploying JBoss 7.1 for EJB 3, the following exception may occur: org.jboss.msc.service.ServiceNotFoundException: Service service jboss.ejb.default-resource-adapter-name-service not found

For successful deployment, add following under <subsystem xmlns="urn:jboss:Domain:ejb3:1.4"> of standalone.xml file.

<mdb>
   <resource-adapter-ref resource-adapter-name="hornetq-ra"/>
   <bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
</mdb>

Restrictions for a Deployment with MySQL Version 5.6

The MySQL 5.6 installation comes with the MySql Connector/J in version 5.1.34. If you deploy this JAR into JBoss as a module and include it in the standalone.xml file, you are facing the following exception:

INFO  [org.jboss.as.connector.deployers.jdbc] JBAS010417: Started Driver service with driver-name = mysql
ERROR [org.jboss.as.controller.management-operation] JBAS014612: Operation ("add") failed - address: ([
    ("subsystem" => "datasources"),
    ("jdbc-driver" => "mysql")
]): org.jboss.msc.service.DuplicateServiceException: Service jboss.jdbc-driver.mysql is already registered

This is a known issue for JBoss versions earlier than 8 (Module for MySQL JDBC driver with version 5.1.30+ needs <driver-class> in standalone.xml). As a workaround you can define a specific driver-class in the standalone.xml in the driver section as follows:

<driver name="mysql" module="com.mysql">
   <driver-class>com.mysql.jdbc.Driver</driver-class>
   <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
</driver>