WebSphere

Prerequisites

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.

Download and Installation

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

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.

Clustering your Web Application with Hazelcast

We recommend to cluster your Web application with the data distribution platform Hazelcast as described in section Using Hazelcast on WebSphere 7.

Java Virtual Machine Setup

When running in the IBM WebSphere Application Server, Class.getResource(String) may return a URL with a wsjar scheme, like wsjar:file:/C:/dev/ws/default/sample_app/xsd.resources.jar!/org/eclipse/xsd/plugin.properties. 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:

  1. Login into your WebSphere administration console.
  2. Go to Servers > server1 > Java and Process Management -> Process Definition > Java Virtual Machine > Custom Properties.
  3. Add the following properties:

In 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.

WebSphere Setup

This sections contains the following information regarding setting up the transactional resources required by Stardust in the WebSphere server. The following description is based on WebSphere version 7. Set your classloader mode to Classes loaded with local classloader first (parent last).

Audit Trail Login

The login helps in authenticating the audit trail database

  1. Login into WebSphere administration console.
  2. Navigate to Security > Global security.



  3. In the Global security pane, expand Java Authentication and Authorization Service and select J2C authentication data.



  4. Click New.



  5. Enter the following details:

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



  6. Click OK.

JDBC Driver

  1. Login into WebSphere administration console.
  2. Navigate to Environment > WebSphere Variables.



  3. To select a server scope, select a node scope first.



  4. Click New to create a new entry.



  5. Enter the following properties:

  6. Click Apply then OK.

Data Source

  1. Login into WebSphere administration console.
  2. Navigate to Resources > JDBC > JDBC providers.



  3. Select server scope and click Apply.
  4. Click New to add a new entry.
  5. In the according drop down lists select the following:


  6. Click Next. Check the driver jars are in class path.
  7. Click Next. Now you see the summary, e.g.:



  8. Click Finish in case the summary displays correct data.
  9. Select Additional properties > Data sources.



  10. Click New to add a new datasource.
  11. Enter the following basic data source information:
  12. Click Next.
  13. Enter database specific properties



  14. Enable the Use this Data Source in container managed persistence (CMP) option.
  15. Use the default store helper class



  16. Container-managed authentication: carnot-auth



  17. Enter the following Data source properties:


  18. Click OK and save.
  19. Navigate to datasources.



  20. Select created datasource and choose TestConnection.



Transaction Isolation Level

  1. Navigate to Data sources > Additional Properties > Custom properties.



  2. Click New and create isolation with the following details:

JMS Provider

  1. Navigate to Service Integration > Buses.



  2. Click New.
  3. Enter carnot-bus as name for the new bus.



  4. Click Next and Finish to confirm.
  5. Click on carnot-bus and select Topology > Bus members.



  6. Click Add to create a new entry with default setting, without specifying a JNDI name for the bus member.
  7. Click Finish and save.

Restart WebSphere to check:

  1. Select Servers > Server Types > WebSphere application servers



  2. Click on server1 .



  3. Select Server messaging > Messaging engines



  4. Now check if the carnot-bus is started.



JMS Connection Factory

  1. Navigate to Resources > JMS > Queue connection factories



  2. Select the server and click New.
  3. Select Default messaging provider and click OK.



  4. Enter the following properties:

  5. Click OK.

JMS Queues

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

  1. Navigate to Service Integration > Buses.
  2. Click carnot-bus.
  3. Select Destination resources > Destinations.



  4. Click New to create queues.
  5. Select type Queue.



  6. Use the following queue names:


  7. Assign the queue to a bus member (server1) and click Next.



  8. Click Finish to confirm the queue creation.



  9. Restart the WebSphere server.
  10. Navigate to Servers > Server Types > WebSphere Application servers.



  11. Select server1.



  12. Click Server messaging > Messaging engines



  13. Select the server carnot-bus.
  14. Select Message points > Queue points.



  15. Now the message points for your queues are listed.



Queue Destinations

  1. Navigate to Resources > JMS > JMS providers.



  2. Select Default messaging provider.
  3. Select Queues > New.
  4. Add three JMS queues with bus-name carnot-bus and the following JNDI names:

Listener Ports

  1. Navigate to Servers > Server Types > WebSphere Application servers.
  2. Click server1.
  3. Click Communications > Messaging > Message listener service.



  4. Select Additional Properties > Listener Ports



  5. Click New to add new listener ports. Start with the following entries:


  6. Repeat these steps for CarnotSystemQueue and CarnotDaemonQueue.

Activation Specifications

  1. Navigate to Resources > JMS > JMS providers.
  2. Click Default messaging provider.
  3. Select Additional Properties > Activation specifications



  4. Click New to create new activation specifications.
  5. In the Administration part, enter:


  6. In the Destination part, enter:


  7. In the Additional part, enter:


  8. Add Subscription durability: Nondurable.



  9. Similarly create MDBCarnotDaemonQueue and MDBCarnotSystemQueue.

Deployment

The following sections provide instructions on deploying Stardust in a WebSphere application server.

Note that the following osgi related system properties are overwritten to make process diagrams in the Stardust portal available with a WebSphere deployment:

Deploying the EAR file into the WebSphere Application Server

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.

Predefined deployment configurations for WebSphere

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:

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

Stardust provides predefined deployment configurations for WebSphere including a prepared ear file. Please refer to the Stardust support for details.

Configuration

Add the following jar files, residing in %WAS_HOME%/runtimes to the classpath.

List for jar files for WebSphere 7:

List of jar files for WebSphere 8:

Set your classloader mode to classloader with local classes loader first (parent last) .

  1. Login to the Administration Console.
  2. Select Applications > New Application.


  3. Select New Enterprise Application.



  4. Browse to carnot.ear.



  5. Click Next.
  6. Select Detailed as setting on how to install the application and select Next.
  7. In the Select installation options part, choose the following options:

  8. Select Next.
  9. In the Map modules to servers part, review options to perform the EJB deploy and select Next.



  10. Continue by accepting default settings until you get to Bind listeners for message-driven beans.
  11. In the Bind listeners for message-driven beans part, choose the following activation specifications target resource JNDI names:

  12. Select Next.
  13. Enter the following JNDI names for the EJB:

  14. Click Next.
  15. Fill in the JNDI names for the EJB references:

  16. Select Next.
  17. Map Resource References to resources:
  18. Click Next.
  19. Map Resource Environment Entry References to Resources:

  20. Click Next.
  21. Map virtual hosts for Web modules

    Choose a server to deploy and select Next.
  22. Leave option Uncheck as option for Ensure all unprotected 2.x methods have the correct level of protection and select Next.
  23. Now you can check the Summary of your installation.

  24. Select Finish.



  25. Save your configuration.

Running a WebSphere 7 deployment on WebSphere 8

To be able to run a WebSphere 7 deployment on WebSphere 8 the following additional steps are required:

  1. If not already done, 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.
  2. Deploy the Jackrabbit RAR:
    If you have deployed the resource adapter you have to validate if the checkbox Isolate this resource provider is enabled. You can find this option at Resources > Resources Adapters > Resource adapters > <your-jackrabbit-deployment>. If you click on <your-jackrabbit-deployment> you see the option in the lower part of the panel.
  3. Create a Maven project on basis of the archetypes mentioned in section Predefined deployment configurations for WebSphere. You can do that as follows: 
    mvn archetype:generate -DarchetypeGroupId=com.infinity.bpm.archetypes 
      -DarchetypeArtifactId=ipp-archetype-was7-ipp-ear -DarchetypeVersion=<version> 
      -DgroupId=com.infinity.qa -DartifactId=was8-ipp-ear -Dversion=1.0-SNAPSHOT -DinteractiveMode=false
    Please note that the command mentioned above is using the archetype in version determined via <version> and is creating an EAR deployment.
  4. For ipp-archetype-was7-ipp-ear you have to do modify the console pom.xml. Open ipp-archetype-was8-ipp-ear/console/pom.xml in an editor and change each occurrence of 7.0.0 in the dependencies section to 8.0.0.
  5. Create the deployment: 
    mvn package -Dwasclient.dir=<path-which-contains-the-client-JARs>
    Hereby, <path-which-contains-the-client-JARs> should contain the following libraries:
  6. Deploy the archive exactly in the same way as for WebSphere 7. You can find the deployment in ipp-archetype-was8-ipp-ear/ear/target for the EAR deployment and ipp-archetype-was8-ipp-portal-war/target respectively for WAR deployment.

SecurityExceptions or AccessControlExceptions during Deployment

In some cases, a SecurityException or AccessControlException occurs during the deployment using diagram runtime components. To avoid these exceptions:

  1. Add the following entries to the web.xml file:
  2. Replace the listener entry: 
    <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.

Jackrabbit Deployment

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:

  1. Expand Servers > Application Servers > <server> > Web Container Settings > Web Container > Custom Properties.
  2. Select New and then enter com.ibm.ws.webcontainer.invokefilterscompatibility as the property name and true as the value.
  3. Save the update and restart the server.

Include the jcr-2.0.jar in the server classpath.

Download the Jackrabbit rar file from http://archive.apache.org/dist/jackrabbit/2.6.1/jackrabbit-jca-2.6.1.rar and copy the file to your deploy folder.

Note: For Websphere 7 and 8, 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:

  1. Click Resources > Resource Adapters.
  2. Click Install RAR and select jackrabbit-jca-2.6.1.rar.
  3. Click Next and leave all the boxes empty on the next page. For Websphere 7 and 8, you need to select the Isolate this resource provider checkbox.
  4. Click OK.

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:

  1. Go back to Resources > Resource Adapters.
  2. Click New.
  3. Give your new resource a name (e.g. Jackrabbit JCR Adapter).
  4. Select jackrabbit-jca-2.6.1.rar from the archive path drop-down list.
  5. Click Apply.

Now continue:

  1. Scroll down and click J2C Connection Factories.
  2. Click New.
  3. Give your factory a name (e.g. JackrabbitConnectionFactory).
  4. Type the jndi name (e.g. jcr/jackrabbit).
  5. Use component-managed authentication alias. Please note that you have to create it before with the credentials, which are identical to the users.properties.
  6. Set mapping-configuration alias to DefaultPrincipalMapping.
  7. Click Apply.
  8. Scroll down and click Custom Properties.
  9. Set the values of HomeDir and ConfigFile (use classpath:repository.xml) to appropriate values.
  10. Save your changes to the master configuration.

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.

Setting the JCR Connection Factory

You need to verify the JCR connection factory settings.

  1. In the Resource Adapters, click Apache Jackrabbit JCR Adapter
  2. Click View Deployment Descriptor
  3. Check that XA Transaction is specified in <transaction-support>
     

     
  4. If not specified, you need to stop the server, edit the Deployment Descriptor and start the server again.

Jackrabbit Deployment on Oracle JRockit

Note that deployment on Oracle JRockit is not possible for Jackrabbit version prior to 2.0. You need to use version 2.6.1.

Download the Jackrabbit rar file from http://archive.apache.org/dist/jackrabbit/2.6.1/jackrabbit-jca-2.6.1.rar.

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.

Setting up additional Jackrabbit VFS Repositories

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.

Classloading for Portals and Engine Deployment

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:

  1. Go to Applications > Application Types > WebSphere enterprise applications.
  2. In the Enterprise Applications section, select carnot.ear:

    Classloading step1

  3. In Detail Properties click on Class loading and updating detection.

    Classloading step1

  4. In the General Properties part: Classloading step1

  5. Select OK.
  6. Go back to Enterprise Applications > carnot.ear and click Manage Modules in the Modules part:

    Classloading step1

  7. In the Enterprise Applications > carnot.ear > Manage Modules pane select SunGard CSA LLC - Stardust Portal.

    Classloading step1

  8. In the Enterprise Applications > carnot.ear > Manage Modules > ipp-portal.war section, select Classes loaded with local class loader first (parent last) as Class loader order:

    Classloading step1

Using Hazelcast on WebSphere 7

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.

Example Use Case - Hazelcast RAR inside EAR deployment

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:

  1. Download the hazelcast-2.4-stardust01.jar from the repository: https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast/2.4-stardust01/hazelcast-2.4-stardust01.jar into the lib folder of your application server.
  2. Download the hazelcast-ra-2.4-stardust01.rar file from the repository: https://infinity.sungard.com/repository/ipp-3rd-party/com/hazelcast/hazelcast-ra/2.4-stardust01/hazelcast-ra-2.4-stardust01.rar
  3. Put this RAR file into the root folder of your EAR.
  4. Adapt your EAR file in the following way:
    1. The following lines need to be added to the application.xml of the EAR: 
      [...]
<application [...]>
[...]
   <module>
      <connector>hazelcast-ra-2.4-stardust01.rar</connector>
   </module>
[...]
</application>
  5. Deploy your EAR
  6. The JNDI name of the Hazelcast resource adapter can be configured afterwards under Enterprise Applications > application name > Manage Modules > HazelcastRA > Resource Adapter > J2C connection factories in the WebSphere Administration Console.
  7. Optional: Put an appropriate 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.