JBoss

This section describes how to setup the Stardust Portal and the Process Engine in JBoss. Many figures are from the Windows operating system but any supported JBoss platform can be used. Note that currently, for JBoss version 7.1, only Spring deployment is supported. Also note that for JBoss EAP 6.2 the JBoss version 7.1 Spring deployment is compatible and should be used, if required.

Limitations with JBoss 7.1

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

Prerequisites

The following sections discuss prerequisites that must be performed before Stardust 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 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 Stardust 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.

JDBC Drivers

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

Predefined Deployment Configurations for JBoss

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

Refer to chapter Creating a Stardust Runtime Environment with Apache Maven in the Stardust Installation Guide for details.

Stardust provides predefined deployment configurations:

Please refer to the Stardust support team for details on how to receive these configurations.

Deployment with JBoss Version 7.1 or JBoss EAP version 6.2

The setup for JBoss EAP 6.2 EJB or Spring deployment is identical just that some JBoss subsystems declarations that are already defined in the standalone.xml might have a newer version. To prepare a Spring deployment on JBoss 7.1, 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 <JBoss-Home>/standalone/deployments folder. 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-0.9.20.jar and logback-core-0.9.20.jar have to be removed from rar file to use the JBoss logging framework.
  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 on 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 Stardust 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. Stardust 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-stardust02/hazelcast-ra-2.4-stardust02.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-stardust02.rar (download from https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast-ra/2.4-stardust02/hazelcast-ra-2.4-stardust02.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-stardust02.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-stardust02.jar and hazelcast-ra-2.4-stardust02.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>