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.

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.

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.

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.

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

ipp-archetype-jb51-ipp-ear - prepares an EAR deployment for JBoss 5.1 and contains a console module which invokes the calls against an EAR deployment.
ipp-archetype-jb51-ipp-portal-war - prepares a WAR deployment for JBoss 5.1
ipp-archetype-jb71-ipp-portal-war - prepares a WAR deployment for JBoss 7.1

To prepare a reporting WAR deployment for JBoss, use one of the following archetypes:

ipp-archetype-jb51-reporting-war - prepares a Reporting WAR deployment for JBoss 5.1
ipp-archetype-jb71-reporting-war - prepares a Reporting WAR deployment for JBoss 7.1

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

Deployment Configuration with JBoss Version 5.1

This section covers steps required to configure a deployment with JBoss Version 5.1.

XA Data Source

The connection to the Stardust Audit Trail database is configured in a xml file and placed in the folder %JBOSS_HOME%/server/<serverName>/deploy. You can copy a JBoss supplied example XA datasource file located at %JBOSS_HOME%/docs/examples/jca/<database>-xa-ds.xml to %JBOSS_HOME%/server/<server-name>/deploy/ipp-xa-ds.xml and modify it with content to match the Stardust Audit Trail database, such as:

XA Connection Factory and JMS queues

For an Spring setup, JMS is an optional, but highly recommended component. For EAR setups JMS is required.

The connection factory and the JMS queues are configured with the following content in %JBOSS_HOME%/server/ <server-name>/deploy/ipp-jms-ds.xml. Create this file, and paste the following contents into the file.

XA JCR Data Source

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

Remove build-in JSF implementation

Without the JSF-libraries, also the admin-console doesn't work anymore. This Web application is a default deployment and might be removed.

Spring Deployment with JBoss Version 7.1

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:

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:

Jackrabbit Configuration

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 connection-factory dummyCF has to be created as workaround due to the following JBoss issue https://issues.jboss.org/browse/AS7-5538:

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
RAR inside EAR deployment

Separate RAR deployment

To perform a separate RAR deployment, copy the artifact

Copy the artifact com.hazelcast:hazelcast:2.4:jar to the %JBOSS_HOME%/server/default/lib folder ( http://mirrors.ibiblio.org/pub/mirrors/maven2/com/hazelcast/hazelcast/2.4/hazelcast-2.4.jar ) of your JBoss application server.

Deploy the resource adapter com.hazelcast:hazelcast-ra:2.4:rar with the following adjustments:

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

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>

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:

Copy hazelcast-ra-2.4-stardust01.rar (download from https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast-ra/2.4-stardust01/hazelcast-ra-2.4-stardust01.jar) to /standalone/deployments
Add hazelcast.xml to your classpath

Add the following lines to the standalone.xml file:

<resource-adapters>
   <resource-adapter>
       <archive>hazelcast-ra-2.4-stardust01.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>

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>

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>

Create modules for hazelcast-2.4-stardust01.jar and hazelcast-ra-2.4-stardust01.jar and add them to global modules in standalone.xml:

hazelcast-2.4-stardust01.jar:

Add folder <JBOSS7_HOME>/modules/com/hazelcast/main
Copy hazelcast-2.4-stardust01.jar into that folder

Create module.xml with following content:

<module xmlns="urn:jboss:module:1.1" name="com.hazelcast">
   <dependencies>
      <module name="javax.api" />
   </dependencies>

   <resources>
      <resource-root path="hazelcast-2.4-stardust01.jar" />
   </resources>
</module>

hazelcast-ra-2.4-stardust01.jar:

Add folder <JBOSS7_HOME>/modules/com/hazelcast/ra/main
Copy hazelcast-ra-2.4-stardust01.jar into that folder

Create module.xml with following content:

<module xmlns="urn:jboss:module:1.1" name="com.hazelcast.ra">
   <dependencies>
      <module name="javax.resource.api" />
      <module name="javax.api" />
      <module name="com.hazelcast" />
   </dependencies>
   <resources>
      <resource-root path="hazelcast-ra-2.4-stardust01.jar" />
   </resources>
</module>

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>

Set the following properties in your carnot.properties file:

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

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>