6 Configuring JBoss for Oracle Real-Time Decisions

Oracle RTD is supported on both UNIX and Windows platforms for the JBoss application server. The following sections explain how to install the Real-Time Decision Server on JBoss 4.3 EAR.

Note:

Although the Real-Time Decision Server runs on either UNIX or Windows, the Oracle RTD client tools must be run from a Windows platform.

Terminology:

In this chapter:

The directory into which you unzipped the JBoss 4.3 EAP archive file is referred to as JBOSS_HOME, for example, C:\Program Files\EnterprisePlatform-4.3.0.GA_CP03, C:\jboss-eap-4.3.
The directory into which you installed Oracle RTD is referred to as RTD_HOME, for example, C:\OracleBI\RTD.

This chapter contains the following topics:

Section 6.1, "Configuring Server Properties"
Section 6.2, "Creating a JDBC Provider for the Oracle RTD Database"
Section 6.3, "Creating Oracle RTD Roles and Users."
Section 6.4, "Installing and Starting the Oracle Real-Time Decisions Application on JBoss"
Section 6.5, "Assigning Permissions to Custom Roles."
Section 6.6, "Uninstalling the Oracle Real-Time Decisions Application from JBoss"
Section 6.7, "Configuring SSL for Real-Time Decision Server (Recommended)"
Section 6.8, "Setting Up JConsole for JBoss"

6.1 Configuring Server Properties

Note:

Make sure that you have performed the instructions in Section 1.4.4, "Installing JBoss for Oracle RTD."

This section consists of the following topics:

Section 6.1.1, "Adding Oracle RTD Logging to the JBoss Server"
Section 6.1.2, "Copying Oracle RTD Log 4J Jar File to JBoss"
Section 6.1.3, "Copying New Version of Eclipse JDT Compiler to the JBoss Web Container Directory"
Section 6.1.4, "Modifying the JBoss Start Script"

6.1.1 Adding Oracle RTD Logging to the JBoss Server

To add Oracle RTD logging to the JBoss Server, perform the following steps:

Open the file JBOSS_HOME /jboss-as/server/default/conf/jboss-log4j.xml.

Locate:

<!-- ============================== -->
<!-- Append messages to the console -->
<!-- ============================== -->

and add the following at the end of the above section:

<!-- ============================================== -->
<!-- START: Oracle RTD Appender Message Definitions -->
<!-- ============================================== -->

<appender name="SIGMA" class="com.sigmadynamics.util.SDRollingZipFileAppender">
   <param name="Threshold" value="DEBUG"/>
   <param name="File" value="${rtd.log.file}"/>
   <param name="Append" value="true"/>
   <param name="MaxFileSize" value="20000KB"/>
   <layout class="org.apache.log4j.PatternLayout">
   <param name="ConversionPattern" value="%d{ISO8601} %-5p [%c{1}] %m%n"/>
   </layout>
   <filter class="org.jboss.logging.filter.TCLFilter">
      <param name="AcceptOnMatch" value="true"/>
      <param name="DeployURL" value="RTD.ear"/>
   </filter>
   <filter class="org.apache.log4j.varia.DenyAllFilter"/>
</appender>

<appender name="ENG_TRACE_FILE" class="com.sigmadynamics.util.SDRollingZipFileAppender">
   <param name="Threshold" value="TRACE"/>
   <param name="File" value="${rtd.log.file}.trace"/>
   <param name="Append" value="true"/>
   <param name="MaxFileSize" value="20000KB"/>
   <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d{{HH:mm:ss,SSS}} [%t] %m%n"/>
     <!--
     <param name="ConversionPattern" value="%d{{HH:mm:ss,SSS}} [%t] %-5p [%c{1}] %m%n"/>
     -->
   </layout>
</appender>

<!-- ============================================ -->
<!-- END: Oracle RTD Appender Message Definitions -->
<!-- ============================================ -->

Locate:

<!-- ====================== -->
<!-- More Appender examples -->
<!-- ====================== -->

and add the following at the end of the above section:

<!-- ============================================ -->
<!-- START: Oracle  Limit Category Definitions -->
<!-- ============================================ -->

<category name="ENG_TRACE" additivity="false">
  <priority value="DEBUG"/>
  <appender-ref ref="ENG_TRACE_FILE"/>
</category>

<category name="com.sigmadynamics.server.SDDistributedHashtable">
  <priority value="ERROR"/>
</category>

<category name="com.sigmadynamics.client">
  <priority value="ERROR"/>
</category>

<category name="com.sigmadynamics">
  <priority value="DEBUG"/>
</category>

<category name="org.jboss.messaging.core.impl.JDBCSupport">
  <priority value="INFO"/>
</category>

<category name="org.jboss.jms.server.plugin.JDBCJMSUserManager">
  <priority value="INFO"/>
</category>

<category name="org.jgroups.protocols">
  <priority value="ERROR"/>
</category>

<category name="sigmadynamics.application">
  <priority value="DEBUG"/>
</category>

<category name="request.trace.sigmadynamics.application">
  <priority value="TRACE#com.sigmadynamics.util.XLevel"/>
</category>

<category name="request.log.sigmadynamics.application">
  <priority value="DEBUG"/>
</category>

<!-- ========================================== -->
<!-- END: Oracle RTD Limit Category Definitions -->
<!-- ========================================== -->

Locate:

<!-- ======================== -->
<!-- Set up the Root category -->
<!-- ======================== -->

and add the following line to <root>:

<appender-ref ref="SIGMA"/>

Save the file.

6.1.2 Copying Oracle RTD Log 4J Jar File to JBoss

Perform the following step, which adds Oracle RTD classes for displaying Oracle RTD server logs:

Copy RTD_HOME/package/jboss/rtdlog4j.jar to JBOSS_HOME/jboss-as/server/default/lib/.

6.1.3 Copying New Version of Eclipse JDT Compiler to the JBoss Web Container Directory

Perform the following step:

Copy RTD_HOME/package/jboss/ecj-3.4.jar to JBOSS_HOME/jboss-as/server/default/deploy/jboss-web.deployer/.

Note:

This overrides the older version of the Eclipse JDT compiler jasper-jdt.jar.

See JBoss Bug #JBPAPP-869: https://jira.jboss.org/jira/browse/JBPAPP-869.

6.1.4 Modifying the JBoss Start Script

The JBoss start scripts for Windows and Unix are different. Follow the steps in the appropriate section:

Section 6.1.4.1, "Modifying the Windows JBoss Start Script"
Section 6.1.4.2, "Modifying the Unix JBoss Start Script"

6.1.4.1 Modifying the Windows JBoss Start Script

To modify the Windows JBoss start script, perform the following steps:

Open JBOSS_HOME/jboss-as/bin/run.bat.

Near the top of the file, add the following (after replacing RTD_HOME_TO_REPLACE with your actual value, for example, C:\OracleBI\RTD):

set RTD_HOME=RTD_HOME_TO_REPLACE

set JAVA_OPTS= -Dorg.jboss.net.protocol.file.decodeFilePaths=true
set JAVA_OPTS=%JAVA_OPTS% -Dnologging=true -DSDLoggingPriority=DEBUG
set JAVA_OPTS=%JAVA_OPTS% -Djboss.partition.udpGroup=228.1.2.10
set JAVA_OPTS=%JAVA_OPTS% -Dhibernate.connection.release_mode=auto
set JAVA_OPTS=%JAVA_OPTS% -Drtd.install.dir=%RTD_HOME%
set JAVA_OPTS=%JAVA_OPTS% -Drtd.home.dir=%RTD_HOME%
set JAVA_OPTS=%JAVA_OPTS% -DSDLoggingFileName=%RTD_HOME%/log/server.log
set JAVA_OPTS=%JAVA_OPTS% -DDSPerfCounterLogFile=%RTD_HOME%/log/ds_perf.cvs 
set JAVA_OPTS=%JAVA_OPTS% -Drtd.log.file=%RTD_HOME%/log/server.log
set JAVA_OPTS=%JAVA_OPTS% -Djava.net.preferIPv4Stack=true
set JAVA_OPTS=%JAVA_OPTS% -Xmx512m -XX:MaxPermSize=128m

set JBOSS_CLASSPATH=%RTD_HOME%/lib/jdbc/bijdbc14.jar
set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%RTD_HOME%/lib/jdbc/sqljdbc.jar
set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%RTD_HOME%/lib/jdbc/db2jcc_license_cu.jar
set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%RTD_HOME%/lib/jdbc/db2jcc.jar
set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;%RTD_HOME%/lib/jdbc/ojdbc14.jar

Save the file.

Note:

To start the JBoss application server on Windows, perform the following:

Open a command window (cmd) and 'cd' to: JBOSS_HOME/jboss-as/bin/.
Start JBoss by entering:
```
run.bat --configuration=default --host=<host or ip for JBoss to listen on>
```
For example:

run.bat --configuration=default --host=0.0.0.0

To stop the JBoss application server on Windows, perform the following:

Open a command window (cmd) and 'cd' to: JBOSS_HOME/jboss-as/bin/.
Stop JBoss by entering:

shutdown.bat --server=localhost:1099 -S -u admin -p admin

6.1.4.2 Modifying the Unix JBoss Start Script

To modify the Unix JBoss start script, perform the following steps:

Open JBOSS_HOME/jboss-as/bin/run.sh.

Near the top of the file, add the following (after replacing RTD_HOME_TO_REPLACE and JAVAHOME_TO_REPLACE with actual values, such as /home/rtd and /home/java):

JAVA_HOME="JAVAHOME_TO_REPLACE"
export JAVA_HOME

RTD_HOME="RTD_HOME_TO_REPLACE"

JAVA_OPTS="$JAVA_OPTS -Dorg.jboss.net.protocol.file.decodeFilePaths=true"
JAVA_OPTS="$JAVA_OPTS -Dnologging=true -DSDLoggingPriority=DEBUG"
JAVA_OPTS="$JAVA_OPTS -Djboss.partition.udpGroup=228.1.2.10"
JAVA_OPTS="$JAVA_OPTS -Dhibernate.connection.release_mode=auto"
JAVA_OPTS="$JAVA_OPTS -Drtd.install.dir=$RTD_HOME"
JAVA_OPTS="$JAVA_OPTS -Drtd.home.dir=$RTD_HOME"
JAVA_OPTS="$JAVA_OPTS -DSDLoggingFileName=$RTD_HOME/log/server.log"
JAVA_OPTS="$JAVA_OPTS -DDSPerfCounterLogFile=$RTD_HOME/log/ds_perf.cvs"
JAVA_OPTS="$JAVA_OPTS -Drtd.log.file=$RTD_HOME/log/server.log"
JAVA_OPTS="$JAVA_OPTS -Drtd.log.file=$RTD_HOME/log/server.log"
JAVA_OPTS="$JAVA_OPTS -Djava.net.preferIPv4Stack=true
JAVA_OPTS="$JAVA_OPTS -Xmx512m -XX:MaxPermSize=128m -server

JBOSS_CLASSPATH="$RTD_HOME/lib/jdbc/bijdbc14.jar"
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$RTD_HOME/lib/jdbc/sqljdbc.jar"
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$RTD_HOME/lib/jdbc/db2jcc_license_cu.jar"
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$RTD_HOME/lib/jdbc/db2jcc.jar"
JBOSS_CLASSPATH="$JBOSS_CLASSPATH:$RTD_HOME/lib/jdbc/ojdbc14.jar"

Tips:

If you get the error OutOfMemoryError, set the -Xmx argument to -Xmx1024M.
If you get the error OutOfMemoryError:PermGen, set the -XX:MaxPermSize argument to -XX:MaxPermSize=256M.

Save the file.

Note:

To start the JBoss application server on Unix, perform the following:

Open a command window (cmd) and 'cd' to: JBOSS_HOME/jboss-as/bin/.
Start JBoss by entering:
```
run.sh --configuration=default --host=<host or ip for JBoss to listen on>
```
For example:

run.sh --configuration=default --host=0.0.0.0

To stop the JBoss application server on Unix, perform the following:

Open a command window (cmd) and 'cd' to: JBOSS_HOME/jboss-as/bin/.
Stop JBoss by entering:

shutdown.sh --server=localhost:1099 -S -u admin -p admin

6.2 Creating a JDBC Provider for the Oracle RTD Database

To create a JDBC provider for the Oracle RTD database, set up the Oracle RTD SDDS data source and to copy it to the JBoss deploy directory, as follows:

In RTD_HOME/package/jboss, choose your supported database and open the file appropriate to that database, as follows:
- For DB2: rtd-db2-ds.xml
- For Oracle: rtd-oracle-ds.xml
- For SQL Server: rtd-sqlserver-ds.xml
Replace the following:
- ${DB_SERVER} with your database server
  
  For example: localhost
  
  Note:
  If the database is on a SQL Server named instance, specify the name of your database server using the format host_name\instance_name.
- ${DB_PORT} with your database port
  
  For example: 50000 for db2, 1521 for oracle, 1433 for sqlserver
- ${DB_NAME} with your database name
  
  For example: RTD for db2 and sqlserver, orcl for oracle
- ${DB_USER} with your database user name
  
  For example: jsmith
- ${DB_PASSWORD} with your database user password
Save the file and copy it to JBOSS_HOME/jboss-as/server/default/deploy/.

6.3 Creating Oracle RTD Roles and Users

Note:

For general information about roles and permissions in Oracle RTD, see Chapter 7, "Configuring Security for Oracle Real-Time Decisions."

In JBoss, the default security provider uses two files to define users and roles, respectively. These files should be edited, or created if they do not already exist, to include the users that are to access Oracle RTD, and their enterprise roles.

6.3.1 Creating Oracle RTD Administrators and Other Users

Assuming JBoss is installed in the directory signified by JBOSS_HOME, then edit this file to include the names and passwords (in clear-text) of users that will access Oracle RTD:

JBOSS_HOME/jboss-as/server/default/conf/users.properties

Note:
Because the default security provider that comes with JBoss stores user names and passwords in an unencrypted form, Oracle highly recommends some other identity store be used with JBoss.

The following shows an example of the content of this file, to demonstrate the syntax. The user name and password appear on the same line, separated by an '=' character.

# A users.properties file for use with the UsersRolesLoginModule
sdsu=welcome1
don=donSecret1
jane=janeSecret1

The users are defined in the following table:

Table 6-1 Users

User Name	Password	Description
sdsu	welcome1	An Oracle RTD administrator
don	donSecret1	An Oracle RTD developer
jane	janeSecret1	An Oracle RTD business

6.3.2 Creating Standard Roles

You create Roles in the default security provider of JBoss by editing this file:

JBOSS_HOME/jboss-as/server/default/conf/roles.properties

Note:

Create the file if it does not already exist.

In the file, each user and the corresponding assigned roles should appear on a single line.

# A roles.properties file for use with the UsersRolesLoginModule
#
sdsu=RTDUsers,RTDAdministrators
don=RTDUsers,RTDStudioDeployers,RTDDecsionCenterUsers
jane=RTDUsers,RTDDecisionCenterEditors

The following are the roles defined as in the previous list, all of which are standard roles:

RTDUsers
RTDAdministrators
RTDDecisionCenterEditors
RTDDecisionCenterUsers
RTDStudioDeployers

The following are the Oracle RTD standard roles not referenced by the example, and hence not created:

RTDStudioDownloaders
RTDBatchAdministrators
RTDChoiceEditors

6.3.3 Creating Custom Roles

Define custom roles in the same manner as standard roles, by editing the file roles.properties.

Note:

Create the file if it does not already exist.

6.3.4 Updating Oracle RTD's Deployment Descriptors

Two of Oracle RTD's deployment descriptor files must be updated to reference any custom roles. These files are embedded within ui.war and soap.war, both of which are embedded within RTD.ear.

Note:

This section describes the changes that need to be made to two web.xml files, but does not describe precisely how to find and update those files. The process is similar to the process of updating the web.xml files to contain custom database resource references, as described in Section 8.4.2, "Adding the New Data Source to Oracle RTD."

Update ui.war

The file represented by this path must be updated to reference any custom roles:

rtd.ear/ui.war/web-inf/web.xml

There are three places within the file web.xml that need to be updated to reference custom roles. Look for the three occurrences of the string, "RTD-Custom-Roles", inside comments.

The first two places are for inserting security-role-ref elements, as in the following:

<!-- RTD-Custom-Roles. Insert custom RTD roles here, as might be needed for
         ILS-specific access. For example, RTD_ILS2Developers could be a role for
         deploying the Inline Service named ILS2, and RTD_ILS2Users for viewing or
         editing ILS2 in Decision Center.
 -->
      <security-role-ref>
          <role-name>RTD_ILS2Developers</role-name>
          <role-link>RTD_ILS2Developers</role-link>
      </security-role-ref>
      <security-role-ref>
          <role-name>RTD_ILS2Users</role-name>
          <role-link>RTD_ILS2Users</role-link>
      </security-role-ref>

The third place for custom roles is for inserting security-role elements, as in the following:

<!-- RTD-Custom-Roles. Insert here security-role elements for any custom RTD roles,
         as might be needed for ILS-specific access. For example, RTD_ILS2Developers
         could be a role for deploying the Inline Service named ILS2, and RTD_ILS2Users
         for viewing or editing ILS2 in Decision Center.
-->
      <security-role>
          <role-name>RTD_ILS2Developers</role-name>
      </security-role>
      <security-role>
          <role-name>RTD_ILS2Users</role-name>
      </security-role>

Update soap.war

The file represented by this path must be updated to reference any custom roles:

rtd.ear/soap.war/web-inf/web.xml

There are two places within the file web.xml that must be updated to reference custom roles. Look for the two occurrences of the string, "RTD-Custom-Roles", inside comments.

The first place is for inserting security-role-ref elements, as in the following:

<!-- RTD-Custom-Roles. Insert custom RTD roles here, as might be needed for
         ILS-specific access. For example, RTD_ILS2Developers could be a role for
         deploying the Inline Service named ILS2, and RTD_ILS2Users for viewing or
         editing ILS2 in Decision Center.
-->
      <security-role-ref>
          <role-name>RTD_ILS2Developers</role-name>
          <role-link>RTD_ILS2Developers</role-link>
      </security-role-ref>
      <security-role-ref>
          <role-name>RTD_ILS2Users</role-name>
          <role-link>RTD_ILS2Users</role-link>
      </security-role-ref>

The second place for custom roles is for inserting security-role elements, as in the following:

<!-- RTD-Custom-Roles. Insert here security-role elements for any custom RTD roles,
         as might be needed for ILS-specific access. For example, RTD_ILS2Developers
         could be a role for deploying the Inline Service named ILS2, and RTD_ILS2Users
         for viewing or editing ILS2 in Decision Center.
-->
      <security-role>
          <role-name>RTD_ILS2Developers</role-name>
      </security-role>
      <security-role>
          <role-name>RTD_ILS2Users</role-name>
      </security-role>

6.4 Installing and Starting the Oracle Real-Time Decisions Application on JBoss

To install the Oracle RTD on JBoss, copy the Oracle RTD.ear file to the JBoss deploy directory, as follows:

Copy RTD_HOME/package/RTD.ear to JBOSS_HOME/jboss-as/server/default/deploy/.

After you start JBoss, Oracle RTD is automatically started.

6.5 Assigning Permissions to Custom Roles

As described in Section 7.4, "Assigning Permissions," assign Cluster permissions, Inline Service permissions, and Decision Center Perspective permissions to any custom roles.

6.6 Uninstalling the Oracle Real-Time Decisions Application from JBoss

To uninstall Oracle RTD from JBoss, you must remove RTD.ear file from the JBoss deploy directory when JBoss has been stopped, as follows:

Stop JBoss.
Remove the RTD.ear file from the JBoss deploy directory, JBOSS_HOME/jboss-as/server/default/deploy/.
Start JBoss.

For information about starting and stopping JBoss on your operating system, see the Note - which refers to both start and stop scripts - at the end of the section appropriate to your installation:

Section 6.1.4.1, "Modifying the Windows JBoss Start Script"
Section 6.1.4.2, "Modifying the Unix JBoss Start Script"

6.7 Configuring SSL for Real-Time Decision Server (Recommended)

The process of setting up SSL for all client connections to Real-Time Decision Server takes place automatically as you install JBoss for Oracle RTD. For details, see Section 1.4.4, "Installing JBoss for Oracle RTD."

Note:

If you want to use your own keystore and truststore, you do not need to complete the instructions in Section 2.6.

6.8 Setting Up JConsole for JBoss

To set up JConsole for JBoss, follow the instructions appropriate for your operating system:

Section 6.8.1, "Setting Up JConsole for JBoss on Windows"
Section 6.8.2, "Setting Up JConsole for JBoss on Unix"

6.8.1 Setting Up JConsole for JBoss on Windows

To set up JConsole for JBoss on Windows, perform the following steps:

Open JBOSS_HOME/jboss-as/bin/run.bat.

Near the top of the file, add the following:

set JAVA_OPTS=%JAVA_OPTS% -Dcom.sun.management.jmxremote=true
set JAVA_OPTS=%JAVA_OPTS% -Dcom.sun.management.jmxremote.port=12345
set JAVA_OPTS=%JAVA_OPTS% -Dcom.sun.management.jmxremote.authenticate=false
set JAVA_OPTS=%JAVA_OPTS% -Dcom.sun.management.jmxremote.ssl=false

Save the file.

6.8.2 Setting Up JConsole for JBoss on Unix

To set up JConsole for JBoss on Unix, perform the following steps:

Open JBOSS_HOME/jboss-as/bin/run.sh.

Near the top of the file, add the following:

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote=true"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.port=12345"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.ssl=false"

Save the file.