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.
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 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.
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:
%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.
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.
Copy JDBC drivers used to access the Stardust Audit Trail Database to the following directory, %JBOSS_HOME%/server/ <serverName>/lib.
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:
Please refer to chapter Creating a Runtime Environment with Apache Maven in the Installation Guide section Other Archetypes of our Stardust 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.
To prepare a deployment on JBoss, perform the following steps:
<JBoss-Home>/bin/standalone.bat
<JBoss-Home>/bin/add-user.bat
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:
<?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><driver name="mysql" module="com.mysql"> <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class> </driver>
<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>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> -->
<?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>jackrabbit-jca-2.6.1-infinity02.rar
file from the following location:
Dependencies: javax.jcr export,org.slf4jFurther 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
ooxml-schemas and xmlbeans from the WAR deployment and use the one
from the Jackrabbit RAR. Drop the poi-ooxml-schemas JAR and put ooxml-schemas into it.
jackrabbit-jca-2.6.1-infinity02.rar mentioned above.
<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><subsystem xmlns="urn:jboss:domain:jca:1.1"> <archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>
<global-modules> <module name="javax.jcr" slot="main" /> </global-modules>
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>
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.
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.
The following examples demonstrates the usage of Hazelcast on WebLogic 10.3. Stardust provides a prepared RAR file to be deployed with WebLogic.
To perform a separate RAR deployment, copy the artifact
<icon></icon>is removed
<?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>
To perform a RAR inside EAR deployment perform the following steps:
<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>
<resource-ref> <res-ref-name>cache/HazelcastCF</res-ref-name> <jndi-name>java:/HazelcastCF</jndi-name> </resource-ref>
<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>
<module xmlns="urn:jboss:module:1.1" name="com.hazelcast">
<dependencies>
<module name="javax.api" />
</dependencies>
<resources>
<resource-root path="hazelcast-2.4-stardust03.jar" />
</resources>
</module><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-stardust03.jar" />
</resources>
</module><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>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
<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>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.
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>
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>