5
Multiple JVM Support and Load Balancing

Multiple JVM Support and Load Balancing describes multiple Java Virtual Machine (JVM) support in Wireless Edition. Each section of this document presents a different topic. These sections include:

Note:

Oracle recommends that each Java Virtual Machine (JVM) not support more than 200 concurrent user sessions.

Important:

In this document:

WE_HOME is the directory in which Wireless Edition is installed followed by the "panama" sub-directory. For example:
```
c:\ias10210\panama (Windows)
/private/ias10210/panama (UNIX)
```

Replace "WE_HOME" with the fully-qualified directory path.

ORACLE_HOME is the directory in which Oracle9i Application Server is installed.

5.1 Overview

The following sections describe three possible deployment scenarios for multiple Java Virtual Machine (JVM) support in Wireless Edition:

This document describes:

The Cache synchronization setup (to ensure that the object caches of each instance are synchronous).
Multiple JVM environment without JServ session cookies.
Personalization Portal setup.

Note:

The steps in this document assume an initial configuration of single JVM support. Verify that Wireless Edition is initially set up to run as a single instance communicating with a single Oracle HTTP Server instance.

5.2 Multiple Instances on Same Machine as Oracle HTTP Server

To configure multiple JVM instances on the same machine:

Modify the jserv.conf file so the Oracle HTTP Server is aware of the multiple JServ instances that are running. Start each of these JServ instances manually. Insert the following statements after any existing statements in the section that begins with <IFModule> and ends with </IFModule> in the jserv.conf file. The jserv.conf file is in the ORACLE_HOME\Apache\JServ\conf directory.
1. Modify the following:
```
<IfModule mod_jserv.c>
ApJServManual on
```
2. Running multiple instances of JServ requires a manual start for each instance:
```
ApJServMount /ptg balance://set1/root
```
3. W1, W2,...WN are integers that determine the load-balancing weight assigned to each of the instances. To balance equally among all instances; do not specify Wx; the weight value must be an integer. Weight can be decided on the relative load you want each JServ to handle. Requests for /ptg are load-balanced on set "set1":
```
ApJServBalance set1 PC1 W1
ApJServBalance set1 PC2 W2
.
.
ApJServBalance set1 PCN WN
```
4. Port numbers can be any valid port on the system, however they should not conflict with any other application using the same port.
```
ApJServHost PC1 ajpv12://localhost:7771 
ApJServHost PC2 ajpv12://localhost:7772
.
.
ApJServHost PCN ajpv11://localhost:777N
```
5. JS1 to JSN are routing cookies. These can be set to any unique string for each entry.
```
ApJServRoute JS1 PC1
ApJServRoute JS2 PC2
.
.
ApJServRoute JSN PCN
```
6. This file is used internally by Apache for implementing fault tolerance:
```
ApJServShmFile ORACLE_HOME\Apache\Jserv\jserv_shm
```
7. Close the section using:
```
</IfModule>
```

Start the Oracle HTTP Server.

ORACLE_HOME\Apache\Apache\Apache.exe -k start -d
ORACLE_HOME\Apache\Apache

Create and modify the jserv.properties files for each of the instances. Make copies of the default jserv.properties files for each of the instances, for example, jserv1.properties, jserv2.properties. The jserv.properties file is in the ORACLE_HOME\Apache\JServ\conf directory. Modify the files:
1. Port which the instance uses to communicate with Apache using the AJP protocol. x corresponds to each of the JServ instances 1...N.
```
port=777x
```
2. The log file. For Unix, ensure that the JServ process owner has write permissions for this file:
```
log.file=ORACLE_HOME\Apache\Jserv\logs\jservx.log
```
3. This allows only clients from the local machine to access the JServ instances:
```
security.allowedAddresses=127.0.0.1
```
4. Change the location of class files specific to the JServ instance from:
```
wrapper.classpath=<WE_HOME>\server\classes
```
  to:
```
wrapper.classpath=<WE_HOME>\server\classesx
```
To enable cache synchronization among the database instances, modify the Wireless Edition specific properties files. The default location for these files is in the <WE_HOME>\server\classes directory. Create copies of this directory structure and modify the structure so that each of the JServ instances have unique port numbers and other resources. For example, these directories should appear as <WE_HOME>\server\classesx, where x corresponds to each of the JServ instances 1...N. Modify the System.properties file in the <WE_HOME>\server\classesx\oracle\panama\core\admin directory:
1. Set the unique identifier for the instance. x corresponds to each of the JServ instances 1...N.
```
instance.identifier=instancex
```
2. Set the following parameter to true for every instance to ensure that the instance participates in cache synchronization:
```
participateInCacheSynchronization=true
```
3. This value should point to the machine and port where the Master Instance for Cache synchronization is running. It should have the same value for all instances. Ensure that the port number (2007 in this case) is the same as the one specified by the rmi.registry.port parameter in the Master.properties file:
```
masterInstance.url=//localhost:2007
```
4. Modify the properties files in Table 5-1. These files are in the <WE_HOME>\server\classesx\oracle\panama\core directory. The sub-directories are specified.
5. Run the following SQL scripts by connecting to the repository database as the Wireless Edition database user. The scripts are provided in the <WE_HOME>\server\classesx\oracle\panama\sql directory.
```
create_cachesync_schema.sql
enable-cachesynch_triggers.sql
```
6. The master server must be started by running the script <WE_HOME>\server\classesx\oracle\panama\sample\runMasterServer.bat or runMasterServer.sh.

Property File	Setting
\admin\AsynchNotification.properties	server.listen.port=5500x
\core\admin\AsynchRequest.properties	server.listen.port=6500x
\core\admin\Ftp.properties	ftp.server.port=910x
\core\admin\Notification.properties	sms.server.port=5000x
\core\admin\Rmi.properties	rmi.server.port=201x The port number on which the RMI server runs.
\probe\www-server.properties	port=809x
\magent\config\MAgent.properties	magent.server.port=201x Same as rmi.server.port in Rmi.properties.
\spatial\spatial.properties	Change path to class files to reflect the per instance classes.
\Master\Master.properties	Modify the db.connect parameter in this file to be the same as that in System.properties. Modify only the Master.properties file in the classpath of the master instance. ptgInstances.length=N ptgInstance1.rmi.host=localhost ptgInstance1.rmi.port=2011 (This is the value of rmi.server.port in the Rmi.properties file.) ptgInstance1.rmi.objectName=CacheSyncClient (Do not change CacheSyncClient to any other value.) ptgInstance2.rmi.host=localhost ptgInstance2.rmi.port=2012 ptgInstance2.rmi.objectName=CacheSyncClient ptgInstanceN.rmi.host=localhost ptgInstanceN.rmi.port=201N ptgInstanceN.rmi.objectName=CacheSyncClient

Table 5-1 Property File Settings

Property File Setting

\admin\AsynchNotification.properties

server.listen.port=5500x

\core\admin\AsynchRequest.properties

server.listen.port=6500x

\core\admin\Ftp.properties

ftp.server.port=910x

\core\admin\Notification.properties

sms.server.port=5000x

\core\admin\Rmi.properties

rmi.server.port=201x
The port number on which the RMI server runs.

\probe\www-server.properties

port=809x

\magent\config\MAgent.properties

magent.server.port=201x
Same as rmi.server.port in Rmi.properties.

\spatial\spatial.properties

Change path to class files to reflect the per instance classes.

\Master\Master.properties

Modify the db.connect parameter in this file to be the same as that in System.properties.
Modify only the Master.properties file in the classpath of the master instance.
ptgInstances.length=N
ptgInstance1.rmi.host=localhost
ptgInstance1.rmi.port=2011 (This is the value of rmi.server.port in the Rmi.properties file.)
ptgInstance1.rmi.objectName=CacheSyncClient (Do not change CacheSyncClient to any other value.)
ptgInstance2.rmi.host=localhost
ptgInstance2.rmi.port=2012
ptgInstance2.rmi.objectName=CacheSyncClient
ptgInstanceN.rmi.host=localhost
ptgInstanceN.rmi.port=201N
ptgInstanceN.rmi.objectName=CacheSyncClient

Start each of the JServ instances manually after the Oracle HTTP Server is started. Create a batch script to supply all the classes specified in the jserv.properties file to Java as part of the classpath. See Section 5.6.3 for a sample batch script.

5.3 Multiple Instances on the Same Machine/Oracle HTTP Server on Different Machine

The steps are the same as in Section 5.2 except for the following:

While configuring jserv.conf change the ApJServHost directive so that the Oracle HTTP Server points to the machine running the JServ instances, by specifying its IP address. For example:
```
ApJServHost PC1 ajpv12://jserv-machine:7771 
ApJServHost PC2 ajpv11://jserv-machine:7772
.
.
ApJServHost PCN ajpv11://jserv-machine:777N
```
These port numbers can be any valid port on the machine running JServ instances, only that they must not conflict with any other application using the same port.
In each of the jserv.propertiesx files, change the bindaddress parameter to the IP address of the machine running the JServ instance, and the security.allowedAddresses parameter to point to the IP address of the machine running the Oracle HTTP Server. For example:
```
bindaddress=ip_address_of_machine_running_jserv_instance
security.allowedAddresses=192.168.1.2
```

5.4 Multiple Instances and Oracle HTTP Server All on Different Machines

The steps are similar to Section 5.2, in addition:

Modify the jserv.conf file on the machine running the Oracle HTTP Server. Ensure that the ApJServHost directive includes the IP addresses of each of the machines running the JServ instances. For example:
```
ApJServHost PC1 ajpv12://jserv-machine1:8007 
ApJServHost PC2 ajpv11://jserve-machine2:8007
.
.
ApJServHost PCN ajpv11://jserv-machineN:8007
```
Start the Oracle HTTP Server.

On each machine running the JServ instances, modify the jserv.properties file:

bindaddress=ip_address_of_machine_running_jserv_instance
security.allowedAddresses=oraclehttpserver_ip_address

On the machine running the Master Instance, modify the Master.properties file. See Table 5-1 for more information.
Modify the system.properties file in the <WE_HOME>\server\classes\oracle\panama\core\admin directory on all machines:
1. Set the unique identifier for the instance:
```
instance.identifier=instancex
```
2. Set the following parameter to true to ensure that the instance participates in cache synchronization:
```
participateInCacheSynchronization=true
```
3. Set the following parameter to point to the machine and port where the Master Instance for Cache synchronization is running. It should have the same value for all instances. Ensure that the port number (2007 in this case) is the same as the one specified by the rmi.registry.port parameter in the Master.properties file.
```
masterInstance.url=//machine_running_master_instance:2007
```
4. Run the SQL script enable_cachesync_schema.sql by connecting to the repository database as the Wireless Edition database user. The script resides, by default, in the <WE_HOME>\sql directory.
5. Start the master server on the machine running the master instance by running the script runMasterServer.bat in the <WE_HOME>\sample directory.
Start each of the JServ instances manually using the batch script. See Section 5.6.3 for a sample script.

5.5 Load Balancing

When multiple instances are running, load balancing can be performed by a separate machine. For example, there could be several Oracle HTTP Server instances, each with a set of JServ instances balanced on a one-to-many basis by this machine. The Oracle HTTP Server instances can perform load balancing by using a hardware load balancer in front of the Oracle HTTP Server instances.

The main purpose of multiple JVM support in Wireless Edition is to provide scalability through load-balancing. There are three implementations when setting up load-balancing.

Load-balancing among Oracle HTTP servers through hardware load-balancing.
Load-balancing among Jserv instances with cookies.
Load-balancing among Jserv instances with URL rewriting.

5.5.1 Load-Balancing with Cookies

When intermediate gateways or proxies and the clients support cookies, load balancing can be achieved using cookies:

Set the enable.http.session.binding parameter in all of the System.properties files (on all machines, if more than one machine is involved) to true.
In the ORACLE_HOME\Apache\JServ\conf\zone.properties file set the session.useCookies parameter to true.

5.5.2 Load Balancing Through URL Rewriting

When intermediate gateways or proxies do not support cookies, load balancing can be achieved through URL rewriting:

Set the enable.http.session.binding parameter in all of the System.properties files (on all machines, if more than one machine is involved) to true.
In the ORACLE_HOME\Apache\JServ\conf\zone.properties file set the session.useCookies parameter to false.

5.6 Configuring the Personalization Portal for Load-Balancing

This section describes the configuration of the Personalization Portal in two environments:

5.6.1 Clients/Gateways Support Cookies

To set up the Personalization Portal when clients and/or intermediate gateways support cookies, enable one of the load-balanced Wireless Edition instances to service Personalization Portal requests. Modify the jserv.conf file to change the value of the ApJServDefaultPort parameter to the port number of any of the load-balanced instances (ApJServDefaultPort 7771).

5.6.2 Clients/Gateways Do Not Support Cookies

To set up the Personalization Portal when clients and/or intermediate gateways do not support cookies, run a separate Wireless Edition instance to service Personalization Portal requests.

Modify the jserv.conf file to change the value of the ApJServDefaultPort parameter to the port number of any unoccupied port (ApJServDefaultPort 7774).
Create a copy of the jserv.properties file, for example, jserv4.properties (assuming that there are three load-balanced instances running) for each of the instances and modify the following:
1. Set the port which the instance uses to communicate with Oracle HTTP Server using the AJP protocol. This should be the same as the value set for the ApJServDefaultPort parameter in the jserv.conf file.
```
port=7774
```
2. Set the log file. For UNIX ensure that the JServ process owner has write permissions for this file.
```
log.file=ORACLE_HOME\Apache\Jserv\logs\jserv4.log
```
3. Ensure that only the Oracle HTTP Server talks to this JServ instance:
```
security.allowedAddresses=oraclehttpserver_ip_address
```
4. Change wrapper.classpath=<WE_HOME>\server\classes to wrapper.classpath=<WE_HOME>\server\classesx. This is the location of class files specific to the JServ instance.
Copy the default zone.properties file in ORACLE_HOME\Apache\Jserv\conf to zone_pp.properties. In this file, ensure that the session.useCookies parameter has a value of true.
```
root.properties= ORACLE_HOME\Apache\Jserv\conf\zone_pp.properties
```
Modify the various Wireless Edition specific properties files. The default location for these files is in the <WE_HOME>\server\classes directory. Create a copy of this directory and modify the properties files so that each of the JServ instances has a unique port number and other resources. For example, the directory should appear as <WE_HOME>\server\classes. In the <WE_HOME>\server\classes4\oracle\panama\core\admin\ directory, modify the System.properties file.
1. Set the unique identifier for this instance:
```
instance.identifier=instance
```
2. Set the following parameter to true to ensure that the instance participates in cache synchronization:
```
participateInCacheSynchronization=true
```
3. Set the enable.http.session.binding to false.
4. Set the following to point to the machine and port where the Master Instance for Cache synchronization is running. It should have the same value for all instances. Ensure that the port number (2007 in this case) is the same as the one specified by the rmi.registry.port parameter in the Master.properties file on the machine running the Master instance.
```
masterInstance.url=//localhost:2007
```
5. Set the following in the AsynchNotification.properties file in the <WE_HOME>\server\classes\oracle\panama\core\admin\ directory to:
```
server.listen.port=5500
```
6. Set the following in the AsynchRequest.properties file in the <WE_HOME>\server\classes\oracle\panama\core\admin\ directory to:
```
server.listen.port=6500
```
7. Set the following in the Ftp.properties file in the <WE_HOME>\server\classes\oracle\panama\core\admin\ directory to:
```
ftp.server.port=910
```
8. Set the following in the Notification.properties file in the <WE_HOME>\server\classes\oracle\panama\core\admin\ directory to:
```
sms.server.port=5000
```
9. Set the following in the Rmi.properties file in the <WE_HOME>\server\classes\oracle\panama\core\admin\ directory. This is the port number on which the RMI server runs:
```
rmi.server.port=201
```
10. Set the following in the www-server.properties file in the <WE_HOME>\server\classes\oracle\panama\core directory:
```
port=809
```
11. Set the following in the MAgent.properties file in the <WE_HOME>\server\classes\oracle\panama\magent\config directory. This is the same as the rmi.server.port setting in Rmi.properties in the <WE_HOME>\server\classes\oracle\panama\core\admin directory.
```
magent.server.port=201
```
12. Set the path to the class files to reflect the per instance classes in the Spatial.properties file in the <WE_HOME>\server\classes\oracle\panama\spatial\ directory.

Now the instance can be started using the batch file in Section 5.6.3.

5.6.3 Sample Batch File

The following is a sample batch file for manually starting and stopping Oracle HTTP Server. Classes for hooks or other features should be added at the end of the file.

@ECHO OFF
set classpath=%classpath%;ORACLE_HOME\java\lib;PORACLE_HOME\Apache\jdk\lib
set classpath=%classpath%;ORACLE_HOME\Apache\Jserv\ApacheJserv.jar
set classpath=%classpath%;ORACLE_HOME\Apache\Jsdk\lib\jsdk.jar
set classpath=%classpath%;<WE_HOME>\server\classes%1
set classpath=%classpath%;<WE_HOME>\lib\panama.zip
set classpath=%classpath%;<WE_HOME>\lib\panama_core.zip
set classpath=%classpath%;<WE_HOME>\lib\panama_portal.zip
set classpath=%classpath%;<WE_HOME>\lib\panama_papz.zip
set classpath=%classpath%;ORACLE_HOME\jdbc\lib\classes12.zip
set classpath=%classpath%;ORACLE_HOME\jsp\lib\ojsp.jar
set classpath=%classpath%;ORACLE_HOME\lib\servlet.jar
set classpath=%classpath%;ORACLE_HOME\Apache\BC4J\lib\jndi.jar
set classpath=%classpath%;ORACLE_HOME\lib\xmlparserv2.jar
set classpath=%classpath%;<WE_HOME>\lib\client.zip
set classpath=%classpath%;<WE_HOME>\lib\server.zip
set classpath=%classpath%;<WE_HOME>\lib\caboshare-opt-1_0_0.zip
set classpath=%classpath%;<WE_HOME>\lib\marlin-opt-1_0_0.zip
set classpath=%classpath%;<WE_HOME>\lib\ocelot-opt-1_0_0.zip
set classpath=%classpath%;<WE_HOME>\lib\share-opt-1_1_7.zip
set classpath=%classpath%;<<WE_HOME>>\lib\tecate-opt-1_0_0.zip
set classpath=%classpath%;<WE_HOME>\lib\regexp.jar
set classpath=%classpath%;<WE_HOME>\lib\sax2.jar
set classpath=%classpath%;<WE_HOME>\lib\activation.jar
set classpath=%classpath%;<WE_HOME>\lib\mail.jar
set classpath=%classpath%;<WE_HOME>\lib\ldap.jar
set classpath=%classpath%;<WE_HOME>\lib\ldapbp.jar
set classpath=%classpath%;<WE_HOME>\lib\providerutil.jar
set classpath=%classpath%;<WE_HOME>\lib\sdoapi.jar
set classpath=%classpath%;<WE_HOME>\lib\sdovis.jar
set classpath=%classpath%;<WE_HOME>\lib\MapQuestX.jar
set classpath=%classpath%;<WE_HOME>\lib\MQJavaCore.jar
set classpath=%classpath%;<WE_HOME>\lib\RoutingJServerClient.jar
set classpath=%classpath%;<WE_HOME>\lib\jai_codec.jar
set classpath=%classpath%;WE_HOME\lib\classes%1
REM  Add other classpath entries here for specific features or hooks implemented
REM  by the customer.
java -c %org.apache.jserv.JServ ORACLE_HOME\Apache\JServ\conf\jserv%1.properties

This script (in the example, jservmanual.sh) can be used in the following manner to start and stop a Jserv instance:

To start instance 1, use:
```
jservmanual.sh 1 
```
To stop an instance, use:
```
jservmanual.sh 1 -s 
```

5 Multiple JVM Support and Load Balancing