1 Installing Oracle SOA Suite with JBoss Application Server

1.3.1 Step 1: Configure the Oracle Database

Follow these instructions to configure Oracle Database 10g.

1. Install Oracle Database 10g 10.1.0.2.

2. Open SQL*Plus and log in as a user with the SYSDBA privilege.

3. Shut down the database:

   SQL> SHUTDOWN IMMEDIATE
   

4. Install the Oracle Database 10g 10.1.0.5 patch in the same Oracle home in which you installed Oracle Database 10g.

5. If using Linux only, then log in as the root user and run the following command from the operating system command prompt:

   /etc/init.d/init.cssd stop
   

6. Start the database in upgrade mode in SQL*Plus:

   SQL> STARTUP UPGRADE
   

7. Run the following script:

   SQL> @ORACLE_HOME/rdbms/admin/catpatch.sql;
   

8. Shut down the database:

   SQL> SHUTDOWN IMMEDIATE
   

9. Restart the database:

   SQL> STARTUP
   

10. Run the following script:

    SQL> @ORACLE_HOME/rdbms/admin/utlrp.sql;
    

1.3.2 Step 2: Install Oracle SOA Suite Basic 10.1.3.1.0 for OC4J

You can download and install the basic Oracle SOA Suite 10.1.3.1 for OC4J from Oracle SOA Suite 10g Software Downloads Web site at

http://www.oracle.com/technology/software/tech/soa/index.html

You must install Oracle SOA Suite into the same directory outside of JBoss. JBoss installation will refer to binaries and property files from this installation. This external installation must be there permanently, it is not a temporary staging area. Even though it also contains OC4J, you will not be starting and stopping it. This is an important prerequisite prior to the JBoss installation.

1.3.3 Step 3: Create the Oracle SOA Suite Schema in the Oracle Database

To create the Oracle SOA Suite schema in the Oracle Database:

1. Navigate to the Disk1\install\soa_schemas\irca folder in the Oracle SOA Suite installation setup files directory.

2. Set ORACLE_HOME to point to the Oracle Database installation location. For example,

   set ORACLE_HOME=c:\Oracle10g
   

3. Enter irca.bat on Windows and ./irca.sh in Linux.

   This runs the irca script to create the schemas required for BPEL, ESB, and OWSM.

4. Enter sys password when prompted.

   The SOA schema is loaded into the Oracle Database.

1.3.4 Step 4: Apply SOA Suite Patchset 10.1.3.3

You must download the SOA Suite patchset 10.1.3.3 from OracleMetaLink and then apply the patchset on Oracle SOA Suite 10.1.3.1. Perform the following steps:

1. Log in to OracleMetaLink at http://metalink.oracle.com. The OracleMetaLink home page is displayed.

2. Click Patches & Updates. The Patches & Updates page is displayed.

3. Click Simple Search.

4. In the Search By field, enter 6148874. The details of the patchset 6148874 are displayed.

5. Follow the instructions in the patchset to install the patchset on Oracle SOA Suite 10.1.3.1.

   Caution:

   You should not start/restart the Oracle SOA Suite instance of OC4J server after applying the patch.

6. Shutdown the SOA Suite Post patch upgrade as follows:

   WARNING:

   Do not start Oracle SOA Server from the Windows Start Menu or by running the SOA_Home\opmn\bin\opmnctl -startall script. These actions are not supported.

   Note:

   The scripts to configure Oracle SOA Suite on JBoss require that the JAVA_HOME environment parameter be set prior to running the script.

   Caution:

   You should not start/restart the Oracle SOA Suite instance of OC4J server after applying the patch.

   For...	Run...
   Windows XP	SOA_HOME\opmn\bin> opmnctl stopall
   Linux	SOA_HOME\opmn\bin> ./opmnctl stopall

   
   

1.3.5 Step 5: Apply Opatch on Oracle SOA Suite 10.1.3.3

You need to download the 6757520 patchset from OracleMetaLink and then apply the patchset on Oracle SOA Suite 10.1.3.3.

1. Log in to OracleMetaLink at http://metalink.oracle.com. The OracleMetaLink home page is displayed.

2. Click Patches & Updates. The Patches & Updates page is displayed.

3. Click Simple Search.

4. In the Search By field, enter 6757520. The details of the patchset 6757520 are displayed.

5. Download the p6757520_101330_Generic.zip file for bug 6757520.

6. Follow the instructions given in the Readme.txt file of patch 6757520 and apply the patch on Oracle SOA Suite 10.1.3.3.

1.3.6 Step 6: Install JBoss and Configure Oracle SOA Suite for JBoss

1. Install JBoss Application Server.

   Note:

   If installing on Linux, then change the permissions using the command chmod a+x jboss-4.0.5.GA.

2. Download the Oracle SOA Suite 10.1.3.3 JBoss from Application Server 10g Release 3 (10.1.3.x) Downloads Web site at

   http://www.oracle.com/technology/software/products/ias/htdocs/101310.html and unzip to your local machine. The contents of this zip file are extracted to the SOAJBossInstallables folder.

3. Modify the following mandatory installation properties in the SOAJBossInstallables\cfg\constants.properties file:

   Note:

   • These instructions assume that you have obtained JBoss version 4.0.5.

   • The directory to which you download the Oracle SOA Suite should be the same host on which JBoss is installed.

   • Unzip the SOAJBossInstallables folder as a non-root user (same user as used to install Oracle SOA Suite 10.1.3.1 for OC4J). For example, Oracle.

   • If installing on Linux, then change the permissions to the SOAJBossInstallables folder using the chmod -R 755 SOAJBossInstallables command.

   Note:

   Mandatory properties cannot have a comment tag or contain blank values. Failure to follow this requirement results in errors during installation. Also, ensure that you enter the appropriate information for each of the fields. Any typo will cause errors during installation.

   However, the proxy settings properties, such as PROXY_HOST is non-mandatory.

   Property	Description
   JBOSS_HOME	The directory path in which JBoss is installed. For example, JBOSS_HOME=C:\jboss-4.0.5.GA
   SOA_HOME	The directory path in which Oracle SOA Suite is installed. For example, SOA_HOME=C:\product\10.1.3.1\ OracleSOA_JBoss\
   DRIVER_TYPE	The datasource class that the installable utilizes to create datasources for the OracleSOAServer managed server. For example, DRIVER_TYPE=oracle.jdbc.xa.client.OracleXADataSource
   HOSTNAME	This is the name of the system in which the database is installed.For example, HOSTNAME=localhost
   PORTNUMBER	The port to which the database is listening.For example, PORTNUMBER=1521
   SID	The name of the databse instance.For example, SID=ORCL
   DEFAULTPORT	The port where OracleSOAServer is running.For example, DEFAULTPORT=9700
   RMI_PORT_SOASERVER	The default RMI port for OracleSOAServer.For example,RMI_PORT_SOASERVER=9099
   RMI_PORT_DECSERVER	The default RMI port for DecisionServer. For example,RMI_PORT_DECSERVER=9599
   AQ.JMS.ENABLED	If the value of the property is true, then AQ is enabled; if the value of the property is false, then JBoss JMS is enabled. For example,AQ.JMS.ENABLED=true
   BPEL.JAASAUTHUSERID	The user id for orabpel schema in database.For example BPEL.JAASAUTHUSERID=orabpel
   BPEL.JAASAUTHPASSWD	The password for orabpel schema in database.For example BPEL.JAASAUTHPASSWD=orabpel
   OWSM.JAASAUTHUSERID	The user id for owsm schema in database.For example OWSM.JAASAUTHUSERID=orawsm
   OWSM.JAASAUTHPASSWD	The password for owsm schema in database.For example OWSM.JAASAUTHPASSWD=orawsm
   ESB.JAASAUTHUSERID	The user id for esb schema in database. For example ESB.JAASAUTHUSERID=oraesb
   ESB.JAASAUTHPASSWD	The password for esb schema in database.For example ESB.JAASAUTHPASSWD=oraesb
   PROXY_HOST	The host name of the proxy server. For example, PROXY_HOST=www-proxy.us.oracle.com
   PROXY_PORT	The port where the proxy server is running. For example, PROXY_PORT=80
   NON_PROXY_HOST	The list of non-proxy hosts that are divided by a | symbol. For example, NON_PROXY_HOST=*.oracle.com|*.oraclecorp.com|localhost|

   
   

4. Run the following script from the SOAJBossInstallables\bin folder at the operating system command prompt:

   For...	Run...
   Windows XP	setup.bat
   Linux	setup.sh

   
   

   Note:

   The setup.sh script would not have execute privileges. So, run chmod +x setup.sh.

   This script creates folders called OracleSOAServer and DecisionServer in the JBOSS_HOME\server\ directory. This configures the required applications, database connections, and adapters.

   Note:

   While running the setup.bat or setup.sh file, set the evironment variable JAVA_HOME to the SOA_HOME\jdk folder. For example, SOA_HOME\jdk in Microsoft Windows or /SOA_HOME/jdk in Linux. If JAVA_HOME path does not exist, then setup file throws a message asking to set the JAVA_HOME before running the setup file.

   Installation progress is logged to the SOAJBossInstallables\bin\logs\output.log file.

5. Apply the jbossws-1.2.1 patch.

   By default, Jboss 4.0.5 comes with the Web service deployer 1.0.4(jbossws-1.0.4), there are issues while running Web services using this deployer, hence you need to upgrade to jbossws1.2.1.

   You can download jbossws-1.2.1.GA.zip from the JBoss Web Services Download Web site at

   http://labs.jboss.com/jbossws/downloads

   After the download, follow the instructions given in the Install.txt file, and apply the patch to the already configured OracleSOAServer.

6. Start JBoss as follows:

   For...	Run...
   Windows XP	JBOSS_HOME/jboss-4.0.5/bin/startServer.bat -c OracleSOAServer
   Linux	/JBOSS_HOME/bin/startServer.sh -c OracleSOAServer

   
   

   Note:

   Do not start OracleSOAServer from the Windows Start Menu or by running the SOA_Home\opmn\bin\opmnctl -startall script. These actions are not supported.

7. (Optional). Start the DecisionServer server as follows:

   For...	Run...
   Windows XP	JBOSS_HOME\bin\startServer.bat -c DecisionServer
   Linux	JBOSS_HOME/bin/startServer.sh -c DecisionServer

   
   

   Note:

   Starting DecisionServer is not mandatory. Decision Service applications needs to be deployed only into the DecisionServer server. Start this server, only if decision service applications are available.

8. (Optional). Commands to stop the OracleSOAServer or DecisionServer are as follows:

   Note:

   Use these commands to stop OracleSOAServer /DecisionServer.

   Stop the OracleSOAServer as follows:

   For...	Run...
   Windows XP	stopServer.bat -s jnp://localhost:${RMI_PORT_SOASERVER}
   Linux	stopServer.sh -s jnp://localhost:${RMI_PORT_SOASERVER}

   
   

   Stop the DecisionServer as follows:

   For...	Run...
   Windows XP	stopServer.bat -s jnp://localhost:${RMI_PORT_DECSERVER}
   Linux	stopServer.sh -s jnp://localhost:${RMI_PORT_DECSERVER}

   
   

1.4.1 From the BPELPM Developer Prompt Using Ant

You can use ant in the BPEL PM developer prompt to deploy J2EE applications. This section contains the following topics:

• Prerequisite Checks

• Steps to Deploy Using the BPELPM Prompt

1.4.2 From JDeveloper

You can also deploy J2EE applications from JDeveloper. This section contains the following topics:

• Prerequisite Checks

• Steps to Deploy Using JDeveloper

1.5.1 Using LDAP

This section describes the following steps to configure LDAP in JBoss and to enable LDAP authentication for OracleSOAServer:

1. Navigate to login-config.xml in the JBOSS_HOME\server\OracleSOAServer\conf directory.

2. Precede the "UsersRolesLoginModule" text with a comment character for application-policy BPELAuthentication.

3. Remove the comment character for the "LdapLoginModule" text (By default, the "LdapLoginModule" text is commented.)

4. Save the changes.

5. Restart OracleSOAServer.

The above step disables the default file-based authentication and enables external LDAP authentication.

1.5.2 Using High Availability Setup

This section describes the High Availability (HA) support available for Oracle SOA Suite 10.1.3.3 on JBoss. This section contains the following topics:

• Prerequisite Checks

• Steps to Configure HA for Oracle SOA Suite

1.6.1 Verifying Installation from JBoss

Perform the following steps to check if the Oracle BPEL Process Manager Console has started:

1. Navigate to http://localhost:9700/BPELConsole/ or to the location where the software is installed, for example, http://<machine-name>:9700/BPELConsole/. The Oracle BPEL Process Manager Console is displayed.

2. Log in using admin as the username and password that you configured as per the application authentication policy.

Perform the following steps to check if the Oracle Web Service Manager Console has started:

1. Navigate to http://localhost:9700/ccore/Login.jsp or to the location where the software is installed, for example, http://<machine-name>:9700/ccore/Login.jsp. The Oracle Web Service Manager Console is displayed.

2. Log in using admin as the username and password that you configured as per the application authentication policy.

Perform the following steps to check if the Enterprise Service Bus Console has started:

1. Navigate to http://localhost:9700/esb or to the location where the software is installed, for example, http://<machine-name>:9700/esb. The Enterprise Service Bus Console is displayed.

2. Log in using admin as the username and password that you configured as per the application authentication policy.

1.6.2 Verifying BPEL, ESB, OWSM Consoles

Perform the following steps to check if the BPEL, ESB, OWSM Consoles have started:

1. Navigate to http://localhost:<default_port>/BPELConsole/ (Or to the location where the software is installed, for example, http://<machine-name>:<default_port>/BPELConsole/. The BPEL Console window is displayed as shown in Figure 1-1.

   Navigate to the http://localhost:<default_port>/esb/. The ESB Console window is displayed, as shown in Figure 1-2.

   Navigate to the http://localhost:<default_port>/ccore/. The OWSM Console window is displayed, as shown in Figure 1-3.

   Note:

   The <default_port> is defined in the constants.properties file.

   Figure 1-1 BPEL Console Window

   
   Description of "Figure 1-1 BPEL Console Window"
   
   

   Figure 1-2 ESB Console Window

   
   Description of "Figure 1-2 ESB Console Window"
   
   

   Figure 1-3 OWSM Console Window

   
   Description of "Figure 1-3 OWSM Console Window"
   
   

2. Log in to the BPEL Console using admin as the username and password that you configured as per the application authentication policy. Similarly, log in to the ESB and OWSM console. The Oracle Enterprise Manager BPEL Console page is displayed.

   Log in to the ESB Console using the username and password, the Oracle Enterprise Manager ESB Console page is displayed.

   Log in to the OWSM Console using the username and password, the Oracle Enterprise Manager Web Services Manager Console page is displayed.

1.6.3 Verifying the SelectAllByTitle Sample for the Database Adapter

1. Log in to the database and start SQL*Plus.

2. Run the setup.sql script:

   SQL> @Oracle_Home/samples/tutorials/122.DBAdapter/sql/setup.sql;
   

   This script creates and populates the movies table in the database.

3. Point the database adapter to your database by editing the DbAdapter-ds.xml file in the JBOSS_HOME\server\OracleSOAServer\deploy\ directory and modify the <tx-connection-factory> jndi-name property for Outbound Connection Factories to eis/DB/BPELSamples.

   Note:

   Refer to Section, "Running Adapter Samples" for more information.

4. Select Start, All Programs, Oracle - Oracle_Home, Oracle SOA Suite, Developer Prompt.

5. Change to the following directory:

   tutorials\122.DBAdapter\SelectAllByTitle
   

6. Run the following command:

   ant
   

   This compiles and deploys all projects dependent on this tutorial. Projects are deployed into Oracle_Home\bpel\domains\domain_name\deploy.

7. Select Start, All Programs, Oracle - Oracle_Home, Oracle SOA Suite, BPEL Console.

8. Click SelectAllByTitle in the Deployed BPEL Processes list.

9. Refer to the MOVIES table, and enter the movie title on the Initiate page. For example, 'The Aviator'.

10. Click Post XML Message.

11. View the results and inspect the instance.

1.6.4 Running Adapter Samples

This section contains the following topics:

1.6.5 Deploying Samples Using Ant

Ensure that admin.user and admin.password in SOA_HOME\bpel\utilities\ant-orabpel.properties are updated with the credentials of a valid user from the authentication store setup for authentication.Samples can be deployed from the developer prompt using the ant script following the above step.The samples containing only BPEL processes can be fully deployed using the ant script.Samples containing additional components such as Decision Service applications, workflow forms, and UI applications must be deployed in the following manner.

1. Use the ant script to deploy the BPEL process of the sample.

2. For each Decision Service application, manually edit the jsps file and the decisionservice.xml file to replace the variables for domain, host the port as required. Generate the war or ear file, and deploy into DecisionServer. Start the application.

3. For each workflow form application, generate the war or ear file, and deploy into OracleSOAServer. Start the Application.

4. For each UI Application, manually edit the doApply.jsp to replace the variables for domain, host the port as required. Generate the war or ear file, and deploy into OracleSOAServer. Start the application.

1.7.1 Limitations

Note the following limitations:

• JBoss and Oracle SOA Suite 10.1.3.1 should be installed as the same user on Linux and the user should not be a root user.

  Note:

  When deploying BPEL processes into BPEL Server on JBoss, you only must specify the following two properties in build property files:

  • http.hostname = <SOA_hostname>

  • http.port = 9700

  These properties can be either defined in the build.properties file in your project or in the ant-orabpel.properties file. You can also create a customized build property file, which will overwrite the other two build propery files when properties get loaded by ant.

  Once properties are loaded by ant, the order in which the properties are loaded are as follows:

  1. Customized build property file

     To use this file when deploying a BPEL project, use the following command:

     ant -propertyfile <name>, where <name> is the build property filename created by users.
     

  2. build.properties file in your BPEL project

  3. If BPEL_HOME environment variable is specified, then BPEL_HOME/utilities/ant-orabpel.properties will be used, otherwise, JDEV_HOME/integration/bpel/utilities/ant-orabpel.properties is loaded by ant, where JDEV_HOME is the JDeveloper installation directory.

  It is recommended using build.properties file or customized build property files when deploying BPEL processes using ant.

1.7.2 Known Issues

Note the following known issues:

JMS Adapter

• JMS Adapter throws the following NullPointerException during initialization on non-Oracle platforms:

  JmsConnectionFactory: Unable to set connectionparameters for OracleConnectionManager 
  java.lang.NullPointerException 
  at oracle.tip.adapter.jms.JmsConnectionFactory.<init>(JmsConnectionFactory.java:91)
  at oracle.tip.adapter.jms.JmsManagedConnectionFactory.createConnectionFactory(JmsManagedConnectionFactory.java:81) 
  at org.jboss.resource.connectionmanager.ConnectionFactoryBindingService.createConnectionFactory(ConnectionFactoryBindingService.java:128) 
  at org.jboss.resource.connectionmanager.ConnectionFactoryBindingService.startService(ConnectionFactoryBindingService.java:65) 
  at org.jboss.system.ServiceMBeanSupport.jbossInternalStart(ServiceMBeanSupport.java:289) 
  at org.jboss.system.ServiceMBeanSupport.jbossInternalLifecycle(ServiceMBeanSupport.java:245)
  at sun.reflect.GeneratedMethodAccessor2.invoke(Unknown Source)
  

  This is a benign error and does not stop the JMS connection factory from initializing.

Decision Services

• The following data type binding warnings and errors are displayed during deployment and start of Decision Service (Business Rules) Applications. These errors and warnings can be ignored.

  WARN  [JAXRPCMetaDataBuilder] Cannot obtain java type mapping for:
  {http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent}tDecisionServiceError
  WARN  [JAXRPCMetaDataBuilder] Cannot obtain java type mapping for:
  {http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent}tDecisionServiceError
  WARN  [JAXRPCMetaDataBuilder] Cannot obtain java type mapping for:
  {http://xmlns.oracle.com/AutoLoanFlow/CreditRatingAgent}tDecisionServiceError
  WARN  [SchemaBindingBuilder] Type definition not found in schema:
  {http://xml.apache.org/xml-soap}Element
  WARN  [SchemaBindingBuilder] Cannot obtain type binding for:
  {http://xml.apache.org/xml-soap}Element
  WARN  [JAXRPCMetaDataBuilder] Cannot obtain java type mapping for:
  {http://xmlns.oracle.com/AutoLoanFlow/LoanAdvisorAgent}tDecisionServiceError
  WARN  [JAXRPCMetaDataBuilder] Cannot obtain java type mapping for:
  {http://xmlns.oracle.com/AutoLoanFlow/LoanAdvisorAgent}tDecisionServiceError
  WARN  [SchemaBindingBuilder] Type definition not found in schema:
  {http://xml.apache.org/xml-soap}Element
  WARN  [SchemaBindingBuilder] Cannot obtain type binding for:
  {http://xml.apache.org/xml-soap}Element
  

ESB Log Messages

• Please ignore the *Priority [Category]* of log messages for ESB components alone. For example,

17:25:54,993 ERROR [STDERR] Mar 17, 2008 5:25:54 PM
oracle.tip.esb.server.bootstrap.ESBBaseResourceAdapter start *INFO*:
Starting..
*Priority :*ERROR *          [Category]:*[STDERR]