The following sections discuss prerequisites that must be performed before Stardust can be deployed within a WebSphere application server.
A basic understanding of WebSphere 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
Clustering your Web Application with Hazelcast and to chapter
Optimizing the Performance of secure JCR Deployments accordingly.
Before any activities can be done, download WebSphere from the WebSphere
Download Site. Once downloaded, install WebSphere onto the host server. The
WebSphere installation directory is referred to as %WEBSPHERE_HOME%
from this point forward.
JDBC Drivers are configured as part of the application server setup within WebSphere and are documented in the following sections. JDBC Drivers are referenced using WebSphere environment variables and therefore are copied to the directory referenced by the variables.
We recommend to cluster your Web application with the data distribution platform Hazelcast as described in section Using Hazelcast on WebSphere.
When running in the IBM
WebSphere Application Server, Class.getResource(String) may return a
URL with a wsjar scheme, like
. By
default, EMF will not recognize this as an archive URI and will fail to handle
it correctly. This would probably result in multiple unregistered resource
errors (e.g. java.lang.IllegalArgumentException: resolve against
non-hierarchical or relative base) and/or null pointer exceptions. To overcome
such problems, EMF's set of recognized archive schemes must be changed by
setting the property as described below:
wsjar wszip jar zipIn the same way change the property java.awt.HeadlessException
to value false in the Custom Properties section.
Per default this property is set to
true on WebSphere. This might result into a java.awt.HeadlessException
if a diagram should be generated in the Stardust portal. Setting the
property to false prevents this exception.
This sections contains the following information regarding setting up the
transactional resources required by Stardust in the WebSphere server.
Set your classloader mode to Classes loaded with local classloader
first (parent last).
The login helps in authenticating the audit trail database



Alias: carnot-auth
User ID: your database login ID (for example
carnot)
Password: your database login password (for
example carnot)




DB2UNIVERSAL_JDBC_DRIVER_PATH<db2-home>/java (e.g.
/opt/IBM/db2/V8.1/java)




CarnotTxDataSource AuditTrail.DataSource 


<host of db> (e.g. localhost)<connection port db> (run netstat
-an to find out, or nmap <ip> from remote host)



webSphereDefaultIsolationLevel2 

carnot-bus as name for the new bus.
carnot-bus and select Topology
> Bus members. 
Restart WebSphere to check:

server1 .

carnot-bus is started.


CarnotConnectionFactory CarnotConnectionFactory 
In this section we will create three jms queues used for daemon specific, workflow and application specific messages.



server1) and click
Next.


server1.

carnot-bus.


carnot-bus and the following
JNDI names:
CarnotApplicationQueueCarnotSystemQueueCarnotDaemonQueue 
server1.

CarnotApplicationQueueCarnotApplicationQueue
CarnotConnectionFactory
10
CarnotSystemQueue and CarnotDaemonQueue.

MDBCarnotApplicationQueueeis/MDBCarnotApplicationQueue
QueueCarnotApplicationQueue
carnot-busAuto-acknowledge
110
Nondurable.
MDBCarnotDaemonQueue and MDBCarnotSystemQueue.
The following sections provide instructions on deploying Stardust in a WebSphere application server.
Note
The following osgi related system properties are
overwritten to make process diagrams in the Stardust portal available
with a WebSphere deployment:
The following sections provide instructions on deploying the Stardust components as a single Enterprise Archive. All components execute within a single JVM process on the WebSphere application server. This deployment utilizes the provided EJB features such as JMS queues for forking jobs, message driven bean for controlling queuing and EJB session beans for management client / server interaction and threading.
To achieve the carnot.ear file or needed war files provided by Stardust,
download one of the Maven archetype templates from the Stardust artifactory
matching your requirements.
The following deployment configurations for WebSphere are provided as archetypes:
ipp-archetype-was8-ipp-ear - prepares an EAR deployment for
WebSphere 8 and provides a console environment for EJBipp-archetype-was8-ipp-portal-war - prepares a WAR deployment
for WebSphere 8Please 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.
Include the log4j-1.2.15.jar in the server classpath.
Add the following jar files, residing in %WAS_HOME%/runtimes
to the classpath.
List of jar files for WebSphere 8:
Set your classloader mode to classloader with local classes loader first (parent last) .



CARNOT


MessageListener : eis/MDBCarnotSystemQueue
DaemonListener : eis/MDBCarnotDaemonQueue
ResponseHandler : eis/MDBCarnotApplicationQueue

DocumentManagementService : org.eclipse.stardust.engine.api.runtime.DocumentManagementService
WorkflowService : org.eclipse.stardust.engine.api.runtime.WorkflowService
AdministrationService : org.eclipse.stardust.engine.api.runtime.AdministrationService
UserService : org.eclipse.stardust.engine.api.runtime.UserService
QueryService : org.eclipse.stardust.engine.api.runtime.QueryService
ForkingService : org.eclipse.stardust.engine.api.runtime.ForkingService

org.eclipse.stardust.engine.api.ejb2.beans.LocalForkingService
: org.eclipse.stardust.engine.api.runtime.ForkingServiceorg.eclipse.stardust.engine.api.ejb2.RemoteWorkflowService
: org.eclipse.stardust.engine.api.runtime.WorkflowServiceorg.eclipse.stardust.engine.api.ejb2.RemoteAdministrationService
: org.eclipse.stardust.engine.api.runtime.AdministrationServiceorg.eclipse.stardust.engine.api.ejb2.RemoteUserService
: org.eclipse.stardust.engine.api.runtime.UserServiceorg.eclipse.stardust.engine.api.ejb2.RemoteQueryService
: org.eclipse.stardust.engine.api.runtime.QueryServiceorg.eclipse.stardust.engine.api.ejb2.RemoteDocumentManagementService
: org.eclipse.stardust.engine.api.runtime.DocumentManagementServicejms/CarnotSystemQueue references to CarnotSystemQueue.
jms/CarnotApplicationQueue references to CarnotApplicationQueue.
jms/CarnotDaemonQueue references to CarnotDaemonQueue.




In some cases, a SecurityException or AccessControlException occurs
during the deployment using diagram runtime components.
To avoid these exceptions:
web.xml file:
<context-param>
<param-name>carnot.LOGIN_PAGE</param-name>
<param-value>/plugins/common/login.iface</param-value>
</context-param>
<servlet>
<servlet-name>ippLandingPage</servlet-name>
<servlet-class>com.infinity.bpm.portal.umb.LandingPage</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
index_jsp and logout.jsp:
<servlet-mapping>
<servlet-name>ippLandingPage</servlet-name>
<url-pattern>/index.jsp</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ippLandingPage</servlet-name>
<url-pattern>/ipp/common/ippPortalLogout.jsp</url-pattern>
</servlet-mapping>
<listener>
<listener-class>org.eclipse.stardust.engine.api.web.jsf.common.SessionContextListener</listener-class>
</listener>
with the following entry:
<listener>
<listener-class>org.eclipse.stardust.ui.web.common.listener.SessionContextListener</listener-class>
</listener>
With these entries, the exceptions mentioned above will be avoided, as the servlet will be executed in the regular security context.
To prepare a Jackrabbit deployment, set the WebSphere custom property
com.ibm.ws.webcontainer.invokefilterscompatibility
in your to true, e.g. by performing the following steps:
com.ibm.ws.webcontainer.invokefilterscompatibility
as the property name and true as the value.Include the jcr-2.0.jar in the server classpath.
Download the Jackrabbit rar file from
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.Note
Once you download the jackrabbit-jca-2.6.1.rar file, remove the
org/w3c folder from xmlbeans-2.3.0.jar to have a proper classpath. This folder contains the
Java package org.w3c.dom, which is already included in the JRE.
Furthermore it is required to remove the geronimo-stax-api_1.0_spec-1.0.1.jar to make
Web services available.
To deploy the resource archive, perform the following steps:
jackrabbit-jca-2.6.1.rar.Note
You can store the repository.xml file in the jackrabbit-jca-2.6.1.rar file. If you include it in the rar file, then
you must set the ConfigFile property to classpath:repository.xml.
Also, include users.properties and roles.properties within the rar file.
However, note that there are
many ways of packaging repository.xml.
In case an exception is thrown during those steps, then retry with the following steps for Jackrabbit installation:
Jackrabbit JCR Adapter).jackrabbit-jca-2.6.1.rar from the archive path drop-down list.Now continue:
JackrabbitConnectionFactory).jcr/jackrabbit).component-managed authentication alias. Please note that you
have to create it before with the credentials, which are identical to the
users.properties.DefaultPrincipalMapping.classpath:repository.xml) to appropriate values.Note:
In case the current environment requires the Websphere
Deployment Manager (DMgr) on the same or separate server, the jcr-2.0.jar
file needs to be present in the Deployment Manager's classpath and target
server's classpath.
You need to verify the JCR connection factory settings.

Download the Jackrabbit rar file from
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.To deploy, follow the steps provided in the section Jackrabbit Deployment.
But note that you need to include the jcr-2.0.jar in the server classpath instead of jcr-1.0.jar.
To set up additional Jackrabbit VFS repositories in WebSphere, 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.
To make deployment possible for the Stardust Portals and the engine, some classloading settings are necessary. The following example describes steps to enable the deployment of the Stardust Portal. Note that the steps for the classloading settings of other WAR files are similar. Perform the following steps:
carnot.ear:

Classes loaded with local classloader first (parent last).Class loader for each WAR file in application.

SunGard CSA LLC -
Stardust Portal.
Classes loaded with local class loader first (parent last)
as Class loader order:
Hazelcast is a clustering and scalable data distribution platform. For the second level caching functionality Stardust leverages Hazelcast's distributed Map capabilities. Please refer to http://www.hazelcast.com/product.jsp for detailed information on Hazelcast.
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 in-memory cache is turned on by default with the property below in
your server-side carnot.properties file.
Infinity.Engine.Caching = true
If not, set this property explicitly.
To deploy the Hazelcast resource adapter inside your EAR, perform the following steps:
hazelcast-2.4-stardust03.jar from the repository:
https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast/2.4-stardust03/hazelcast-2.4-stardust03.jar
into the lib folder of your application server.hazelcast-ra-2.4-stardust03.rar file from the repository:
https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast-ra/2.4-stardust03/hazelcast-ra-2.4-stardust03.rar
application.xml
of the EAR:
[...]
<application [...]>
[...]
<module>
<connector>hazelcast-ra-2.4-stardust03.rar</connector>
</module>
[...]
</application>
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
hazelcast.xml on the classpath of
your EAR (or a default configuration will be taken from com.hazelcast:hazelcast:2.4).
A default hazelcast.xml
can be found here: hazelcast.xml.