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.

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.

To prepare the JBoss deployment:

  1. Download JBoss, e.g. from: http://sourceforge.net/projects/jboss/files/JBoss/JBoss-5.1.0.GA/jboss-5.1.0.GA-jdk6.zip/download.
  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.

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:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE datasources
    PUBLIC "-//JBoss//DTD JBOSS JCA Config 1.5//EN"
    "http://www.jboss.org/j2ee/dtd/jboss-ds_1_5.dtd">

<datasources>
     <xa-datasource>
         <jndi-name>AuditTrail.DataSource</jndi-name>
         <xa-datasource-property name="URL">database_url</xa-datasource-property>
         <xa-datasource-class> database_driver_fully_qualified_class_namee</xa-datasource-class>
         <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
         <user-name>database_username</user-name>
         <password>database_password</password>
         <track-connection-by-tx>true</track-connection-by-tx>
         <no-tx-separate-pools>true</no-tx-separate-pools>
         <exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.<databasetype>ExceptionSorter</exception-sorter-class-name>
         <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.<databasetype>ValidConnectionChecker</valid-connection-checker-class-name>
         <min-pool-size>1</min-pool-size>
         <max-pool-size>10</max-pool-size>
         <idle-timeout-minutes>10</idle-timeout-minutes>
         <no-tx-separate-pools/>
         <metadata>
             <type-mapping><databasetype></type-mapping>
         </metadata>
     </xa-datasource>
 </datasources>

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.

<?xml version="1.0" encoding="UTF-8"?>

<server>
   
   <mbean code="org.jboss.jms.server.destination.QueueService" name="jboss.messaging.destination:service=Queue,name=CarnotApplicationQueue" xmbean-dd="xmdesc/Queue-xmbean.xml">
   	<depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
	<depends>jboss.messaging:service=PostOffice</depends>
	<attribute name="JNDIName">queue/CarnotApplicationQueue</attribute>
	<attribute name="RedeliveryDelay">10000</attribute>
	<attribute name="MaxDeliveryAttempts">3</attribute>
   </mbean>
   <mbean code="org.jboss.jms.server.destination.QueueService" name="jboss.messaging.destination:service=Queue,name=CarnotSystemQueue" xmbean-dd="xmdesc/Queue-xmbean.xml">
   	<depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
	<depends>jboss.messaging:service=PostOffice</depends>
	<attribute name="JNDIName">queue/CarnotSystemQueue</attribute>
	<attribute name="RedeliveryDelay">10000</attribute>
	<attribute name="MaxDeliveryAttempts">3</attribute>
   </mbean>
   <mbean code="org.jboss.jms.server.destination.QueueService" name="jboss.messaging.destination:service=Queue,name=CarnotDaemonQueue" xmbean-dd="xmdesc/Queue-xmbean.xml">
   	<depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
	<depends>jboss.messaging:service=PostOffice</depends>
	<attribute name="JNDIName">queue/CarnotDaemonQueue</attribute>
	<attribute name="RedeliveryDelay">10000</attribute>
	<attribute name="MaxDeliveryAttempts">3</attribute>
   </mbean>
   <mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
      name="jboss.messaging.connectionfactory:service=CarnotConnectionFactory"
      xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
      <depends optional-attribute-name="ServerPeer">jboss.messaging:service=ServerPeer</depends>
      <depends optional-attribute-name="Connector">jboss.messaging:service=Connector,transport=bisocket</depends>
      <depends>jboss.messaging:service=PostOffice</depends>
      
      <attribute name="JNDIBindings">
         <bindings>
            <binding>/CarnotConnectionFactory</binding>
            <binding>java:/CarnotConnectionFactory</binding>
         </bindings>
      </attribute>
   </mbean>
</server>

XA JCR Data Source

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

  1. Copy the jcr-2.0.jar file from the lib folder of your Stardust installation to your deploy folder (e.g. <JBoss_dir>/server/<serverName>/lib). If the portal's war files already contain a copy of jcr-2.0.jar, delete it from the war files to avoid classloader problems.
  2. Download the prepared jackrabbit-jca-2.2.5-infinity03.rar file from https://infinity.sungard.com/repository/ipp-3rd-party/org/apache/jackrabbit/jackrabbit-jca/2.2.5-infinity03/jackrabbit-jca-2.2.5-infinity03.rar.
  3. Copy the file to your deploy folder (e.g. <JBoss_dir>/server/<serverName>/deploy).
  4. Create the file ipp-jcr-ds.xml to your deploy folder. Change the entries as follows:
    1. Change the homeDir property to match the folder where you want Jackrabbit to store its files.
    2. Change the configFile property to match the file with the Jackrabbit repository configuration (repository.xml).
    <?xml version="1.0" encoding="UTF-8"?>
<connection-factories>
    <tx-connection-factory>
        <jndi-name>JcrContentRepository</jndi-name>
        <xa-transaction/>
        <rar-name>jackrabbit-jca-2.2.5-infinity03.rar</rar-name>
        <connection-definition>javax.jcr.Repository</connection-definition>
        <config-property name="homeDir" type="java.lang.String">C:/repository-jcr</config-property>
        <config-property name="configFile" type="java.lang.String">classpath:repository.xml</config-property>
        <config-property name="bindSessionToTransaction" type="java.lang.Boolean">true</config-property>
    </tx-connection-factory>
</connection-factories>
  5. Create a configuration in your repository.xml as definied in your ipp-jcr-ds.xml in JBOSS_HOME/server/<serverName>/conf folder, Start with the default configuration and adopt to your environment and requirements)
  6. Create the following property files and add them to your classpath:
  7. In the users.properties file, add default entries, which can be one or more users as keys and their passwords as values: 
    ipp-jcr-user=ipp-jcr-password
  8. To change the user/password, in your carnot.properties file, you can add two entries - ContentRepository.User=<username> and ContentRepository.Password=<password>, which should be the same as the entries in users.properties.
  9. You can leave the roles.properties file empty.

Remove build-in JSF implementation

  1. Remove the JSF jars %JBOSS_HOME%/server/<serverName>/deploy/jbossweb.sar/jsf-libs/*.jar.
  2. Remove the following line from %JBOSS_HOME%/server/<serverName>/deploy/jbossweb.sar/META_INF/jboss-structure.xml: 
    <path name="jsf-libs" suffixes=".jar" />
  3. Edit %JBOSS_HOME%/server/<serverName>/deployers/jbossweb.deployer/web.xml by commenting out or removing the following lines:

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

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:

To prepare a reporting WAR deployment for JBoss 5.1, use the following archetype:

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.

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:1.9:jar to the %JBOSS_HOME%/server/default/lib folder ( http://mirrors.ibiblio.org/pub/mirrors/maven2/com/hazelcast/hazelcast/1.9/hazelcast-1.9.jar ) of your JBoss application server.
  2. Deploy the resource adapter com.hazelcast:hazelcast-ra:1.9:rar with the following adjustments:
    1. The file ra.xml in META-INF/ folder of the RAR file as well as the hazelcast-ra-1.9.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-1.9.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-1.9.jar.

RAR inside EAR deployment

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

  1. Copy the Copy the artifact com.hazelcast:hazelcast:1.9:jar to the root folder of your EAR. ( http://mirrors.ibiblio.org/pub/mirrors/maven2/com/hazelcast/hazelcast/1.9/hazelcast-1.9.jar )
  2. Put the resource adapter com.hazelcast:hazelcast-ra:1.9:rar into the root folder of your EAR:
    1. The file ra.xml in META-INF/ folder of the RAR file as well as the hazelcast-ra-1.9.jar file need to be adjusted such that the line 
      <icon></icon>
      is removed
    2. The following lines need to be added to the application.xml of your EAR: 
      [...]
<application [...]>
[...]
   <module>
      <connector>hazelcast-ra-1.9.rar</connector>
   </module>
[...]
</application>
    3. Add a classpath entry for hazelcast-1.9.jar to the META-INF/MANIFEST.MF of your carnot-engine.jar as well as hazelcast-ra-1.9-infinity01.rar.
    4. A file ending with -ds.xml, residing in the root folder of the hazelcast RAR file (inside the EAR), 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 (assuming your EAR's name is carnot.ear): 
      <?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>carnot.ear#hazelcast-ra-1.9.rar</rar-name>
      <connection-definition>javax.resource.cci.ConnectionFactory</connection-definition> 
   </tx-connection-factory>
</connection-factories>
  3. Deploy your EAR
  4. Optionally put an appropriate hazelcast.xml on the classpath of your EAR. Otherwise a default configuration will be taken from hazelcast-ra-1.9.jar.

Known Issue with Web Services Deployment and Structured Data XPaths

Note that when deploying a model on JBoss using Stardust Web Services, XPaths of structured data do not get generated in the STRUCTURED_DATA table. Perform the following steps so that the XPath entries are created correctly:

  1. Remove the <JBOSS_DIR</lib/endorsed folder
  2. Preferably use a version as high as possible of JDK 6