IBM WebSphere

This guide describes how to configure WebSphere with Oracle and DB2 for LSPS.

Prerequisites:

• Oracle or DB2 database initialized with the lsps-db-migration tool.

To set up IBM WebSphere Application Server with LSPS, do the following:

1. Install WebSphere:
2. Open the WebSphere Application Server Administrative Console.
3. Configure the JVM arguments:
   1. In the Administration Console, expand Servers > Server Type and click WebSphere application servers.
   2. On the right, click the name of your server.
   3. On the Configuration tab of the server detail page, expand Java and Process Management and click Process Definition.
   4. Under the Additional Properties section on the right, click Java Virtual Machine.
   5. Scroll down.
   6. Under Generic JVM arguments, enter the memory arguments, for example, -Xmx1g -XX:MaxPermSize=256m.
   7. Optionally, in the Generic JVM arguments, allow testing and profiling by adding the arguments:
      • To enable running of automated Testbench and Selenium tests, add the -Dcom.whitestein.lsps.vaadin.ui.debug=true parameter.
      • To enable analysis of performance issues with the LSPS Profiler, add the -DlspsProfile=true parameter.
        
4. Enter the database credentials:
   1. On the left, expand Security and click Global Security.
   2. On the right, expand Java Authentication and Authorization Service and click J2C authentication data.
   3. Click New to create an authentication user:
      • Alias: LSPS_DS_AUTH
      • User ID: lsps
      • Password: <PASSWORD>
   4. Click Apply.
5. Create the JDBC provider for your database:
   1. On the left, expand Resources > JDBC and click JDBC providers.
   2. On the right, select the node visibility in the Scope dropdown box.
   3. Setup the JDBC provider for your database:
      • If you are using Oracle:
        1. Copy the Oracle JDBC driver to $WAS_INSTALL_ROOT/OracleJDBCdriver/ojdbc6.jar, for example, c:\sw\IBM\WebSphere\AppServer\OracleJDBCdriver\ojdbc6.jar
        2. Click New and set the properties:
           • Database type: Oracle
           • Provider type: Oracle JDBC Driver
           • Implementation type: XA data source
           • Name: Oracle JDBC Driver (XA)
        3. Click Next.
        4. Enter the database-class-path information:
           • Class path: ${ORACLE_JDBC_DRIVER_PATH}/ojdbc6.jar
           • Directory location for ojdbc6.jar: $WAS_INSTALL_ROOT/OracleJDBCdriver
        5. Click Next and Finish.
      • If you are using DB2
        1. Copy the Oracle JDBC driver to $WAS_INSTALL_ROOT/DB2JDBCdriver/db2jcc4.jar, for example, c:\sw\IBM\WebSphere\AppServer\DB2JDBCdriver\db2jcc4.jar
        2. Click New and set the properties:
           • Database type: DB2
           • Provider type: DB2 Universal JDBC driver provider
           • Implementation type: XA Datasource
           • Name: DB2 Universal JDBC Driver Provider (XA)
        3. Set the DB2UNIVERSAL_JDBC_DRIVER_PATH variable to point to the location with the jar files.
           
6. Create JDBC XA data source:
   • To set up an Oracle data source, do the following:
     1. On the left, expand Resources > JDBC and click Data sources:
     2. Select the visibility of the data source in the Scope dropdown; for cluster environments, set Scope to Cluster.
     3. Click New.
     4. Enter the data source name LSPS_DS and the JNDI name jdbc/LSPS_DS, and click Next.
        1. Select Select an existing JDBC provider with Oracle JDBC driver (XA) and click Next.
        2. Set URL to jdbc:oracle:thin:@127.0.0.1:1521:LSPSand select Use this data source in container managed persistence (CMP). Click Next.
        3. Set Authentication alias for XA recovery to LSPS_DS_AUTH, Component-managed authentication alias to LSPS_DS_AUTH.
     5. Click Next and Finish.
   • To set up a DB2 data source, do the following:
     1. On the left, expand Resources > JDBC and click Data sources:
     2. Select the visibility of the data source in the Scope dropdown; for cluster environments, set Scope to Cluster.
     3. Click New.
     4. Enter the data source name LSPS_DS and the JNDI name jdbc/LSPS_DS, and click Next.
        1. Select Select an existing JDBC provider with DB2 Universal JDBC Driver Provider (XA)
        2. Set Driver type to 4.
        3. Set Database name to lsps.
        4. Set Server name to localhost.
        5. Set Port number to 50000
        6. Select Use this data source in container managed persistence (CMP).
        7. Set Authentication alias for XA recovery to LSPS_DS_AUTH.
        8. Set Component-managed authentication alias to LSPS_DS_AUTH.
        9. Define additional properties of the data source:
           1. Open the data source detail
           2. Click Custom properties on the right.
           3. Click New to create the properties:
              • webSphereDefaultIsolationLevel with value 2 (this means transaction isolation the level read-commited);
              • progressiveStreaming with value 2 (see https://issues.jboss.org/browse/JBPAPP-2613, also https://www.ibm.com/developerworks/community/forums/html/topic?id=77777777-0000-0000-0000-000014050755) and properties fullyMaterializeLobData=true, fullyMaterializeInputStreams=true, progresssiveLocators=2
              • downgradeHoldCursorsUnderXa=true
              • resultSetHoldabilityForCatalogQueries=1
7. Create a JMS queue, JMS queue connection factory, and the corresponding JMS activation specifications Use the default messaging provider and store messages in the LSPS database:
   1. Expand Service Integration and click Buses.
   2. Click New and follow the wizard to create a new bus:
      • Set the name to LSPS_BUS.
      • Unselect Bus security.
   3. On the Buses page, click LSPS_BUS
   4. On the detail page, click the Bus members link in the Topology section.
   5. Click Add and create a bus member with the following details:
      • Server: default value
      • Message store: Data store
      • Use existing data source
      • Data source JNDI name: jdbc/LSPS_DS
      • Schema name: empty
      • Authentication alias: LSPS_DS_AUTH
      • Create tables: true
      • Restrict long running locks: true (for cluster with High Availability)
   6. On the LSPS_BUS detail page, click Destinations in the Destination resources section:
      1. Click New and create a new queue:
         • Destination type: Queue
         • Identifier: LSPS_DEST
         • Bus member: your local server node
      2. Click New and create a new topic:
         • Destination type: Topic space
         • Identifier: LSPS_TOPIC
   7. Expand Resources > JMS > Connection factories and create a connection factory:
      1. Set Scope to your local server node.
      2. Set provider to Default messaging provider.
      3. Set Name to LSPS_CF.
      4. Set JNDI Name to jms/LSPS_CF.
      5. Set BUS Name to LSPS_BUS.
   8. Expand Resources > JMS > Queue and create a queue:
      1. Set Scope to your local server node.
      2. Set provider to Default messaging provider.
      3. Set Name to LSPS_QUEUE.
      4. Set JNDI Name to jms/LSPS_QUEUE.
      5. Set BUS Name to LSPS_BUS.
      6. Set Queue Name to LSPS_DEST.
   9. Expand Resources > JMS > Topic and create a topic:
      • Scope: local server node
      • Provider: Default messaging provider
      • Name: LSPS_TOPIC
      • JNDI Name: jms/LSPS_TOPIC
      • Bus name: LSPS_BUS
      • Topic space: LSPS_TOPIC
   10. Go to Resources/JMS/Activation specifications and create activation specification:
       1. Expand Resources > JMS > Activation specification and create an activation specification:
          • Scope: local server node
          • Provider: Default messaging provider
          • Name: LSPS_AS
          • JNDI Name: jms/LSPS_AS
          • Destination type: Queue
          • Destination JNDI name: jms/LSPS_QUEUE
          • Bus name: LSPS_BUS
       2. Create another activation specification:
          • Provider: Default messaging provider
          • Name: LSPS_WS_AS
          • JNDI Name: jms/LSPS_WS_AS
          • Destination type: Topic
          • Destination JNDI name: jms/LSPS_TOPIC
          • Bus name: LSPS_BUS
8. Set up the LSPS security:
   1. Copy lsps-security-websphere-\<LSPS_VERSION>.jar to $WAS_HOME/lib/ext, typically, C:\sw\IBM\WebSphere\AppServer\lib\ext.
   2. Save your changes.
   3. Restart WebSphere.
   4. Go to Security/Global Security:
      1. Enable administrative security: true
      2. Enable application security: true
      3. Go to Security/Global Security and configure the User account repository:
         1. Choose Standalone custom registry and click Set as current
         2. Click Configure:
            • Primary administrative user name: admin
            • Custom registry class name: com.whitestein.lsps.security.LSPSUserRegistry
      4. Go to Global Security -> LTPA -> LTPA timeout and set the LTPA timeout to the maximum period of time the user is expected to be active in a session, for example, 10 hours (600 minutes). After the period elapses, the user is logged out.
      5. Set the Session timeout: When the user is active, the session time is extended. When the user is inactive, they are logged out when the Session timeout has elapsed, at the latest after the LTPA timeout.
         1. Navigate to Servers > Server Types > WebSphere Application Servers
         2. Select your application server instance.
         3. On the Configuration tab select the Session Management link.
         4. Adjust the value in the Session timeout setting.

            Note: You can use your own authentication, such as, LDAP; However make sure that every authenticated person exists in the LSPS table LSPS_PERSONS apart from your authentication source.

9. Create a mail session: Expand Resources > Mail > Mail Sessions and create mail session:
   1. Set Scope to your local server node and click New.
   2. Under General Properties, set:
      • Name to LSPS_MAIL
      • JNDI Name to mail/LSPS_MAIL.
   3. Under Outgoing Mail Properties, set:
      • Server: <your mail server hostname/IP>
      • Protocol: smtp/smtps
      • User: \<username\>
      • Password: \<password\>
      • Verify Password: `<password>'
      • Return e-mail address: '<return e-mail address>'
10. Set org.apache.el.parser.COERCE_TO_ZERO property to false:
    1. Expand Servers > Server types > WebSphere application servers
    2. Click your server name.
    3. Under Server Infrastructure, expand Java and Process Management and click Process definition.
    4. Under Additional Properties, click Java Virtual Machine.
    5. Under Additional Properties, click Custom properties.
    6. Define the property org.apache.el.parser.COERCE_TO_ZERO with the value false.
       
11. Save your changes.
12. Restart the server and deploy your customized LSPS application EAR.

Now you are ready to upload your modules to the server from Designer or with the command-line tool.