sun.com | How To Buy | My Sun | Worldwide Sites

|  |  | Sun Java™ System Application Server Enterprise Edition 8.1 2005Q1 |  |  |

Sun Java (tm) System Application Server Enterprise Edition 8.1 2005Q1
Sample Applications

Sample applications packaged for Enterprise Edition release simply demonstrate session persistence, clustering - failover, and high availability and reliability features. Please refer to the Installation Guide for Sun Java (tm) System Application Server Enterprise Edition 8.1 2005Q1 for details.

The following are simple instructions to configure Load Balancer, and HADB for an Application Server cluster for sample applications to demonstrate session persistence, high availability, and failover capabilities.

- Setting up a cluster
  - Setting up a ONE-machine cluster without configuring HADB
  - Setting up a ONE-machine cluster with HADB configuration
  - Configuring Database for a two machine setup
  - Setting up a TWO-machine cluster without configuring HADB
  - Setting up a TWO-machine cluster with HADB configuration
- Configuring the Load Balancer plugin
- Running the sample applications.
- Troubleshooting

### Setting up a Cluster

The file `<install_dir>``/samples/ee-samples/cluster.properties` contains cluster setup information. If required, you can modify the pre-populated values of names and port numbers in this file.

- Setting up a ONE-machine cluster without configuring HADB
  This section shows how to create a cluster on the machine that is running the Domain Administartion Server (DAS) without configuring the cluster to use HADB. Go to `<install_dir>``/samples/ee-samples/` and execute `asant setup-one-machine-cluster`. This command would do the following:
  1. Create a cluster with name `cluster.name*`
  2. Create a node-agent with name `nodeagent.name*`
  3. Start the created node-agent
  4. Create two instances (that will use the created node-agent) under the created cluster
  5. Start the created cluster
- Setting up a ONE-machine cluster with HADB configuration
  Note: Before executing the commands in this section make sure that the HADB server is running. To start the HADB server, open a new terminal window and go to `<install_dir>``/hadb/<version>/bin/` directory and execute `./ma ma.cfg`. Make sure you've configured your machine to run HADB server. See the EE Quickstart guide or the Administration guide for details on how to setup a machine to run HADB server.
  This section shows how to create a cluster on the machine that is running the Domain Administartion Server (DAS) and setup the cluster to use HADB server. Go to `<install_dir>``/samples/ee-samples/` and execute `asant setup-one-machine-cluster-with-ha`. This command would do the following:
  1. Create a cluster with name `cluster.name*`
  2. Create a node-agent with name `nodeagent.name*`
  3. Start the created node-agent
  4. Create two instances (that will use the created node-agent) under the created cluster
  5. Start the created cluster
  6. Configure the cluster to use HADB server
- Configuring Database for a two machine setup
  If you plan to create a two-machine cluster, execute the following steps on the machine running the DAS (Domain Administration Server) to configure the EE sample applications to use a Database server:
  1. Open the `<install_dir>/samples/database.properties` file for editing.
  2. Edit the value of the property `pointbase.server` from `localhost` to the `<hostname>` of the machine running pointbase server.
- Setting up a TWO-machine cluster without configuring HADB
  This section shows how to create a two-machine cluster. For convenience sake, the machine running the Domain Administration Server (DAS) will be called the local machine and the second machine will be called the remote machine. Two node-agents are created, one on each machine. Before creating the cluster on the local machine, we need to create and start the node-agent on the remote machine. To do this, first start DAS on the local machine (`asadmin start-domain domain1`). Then, log on to the remote machine and go to `<install_dir>``/samples/ee-samples/`. Open the file `cluster.properties` for editing and set the values of `das.host, das.port, das.adminuser` and `das.adminpassword` corresponding to your DAS installation. Now execute `asant setup-remote-machine-for-2-machine-cluster` in the same directory. This command would do the following:
  1. Create a node-agent with name `nodeagent-remote.name*`
  2. Start the created node-agent
  Now, on the local machine go to `<install_dir>``/samples/ee-samples/` and execute `asant setup-local-machine-for-2-machine-cluster`. This command will do the following:
  1. Create a cluster on the local machine with name `cluster.name*`
  2. Create a node-agent on the local machine with name `nodeagent.name*`
  3. Start the created node-agent on the local machine
  4. Create `instance1*` (that will use the node-agent created on the local machine) under the created cluster
  5. Create `instance2*` (that will use the node-agent created on the remote machine) under the created cluster
  6. Start the created cluster
- Setting up a TWO-machine cluster with HADB configuration
  Note: Before executing the commands in this section make sure that the HADB server is running. To start the HADB server, open a new terminal window and go to `<install_dir>``/hadb/<version>/bin/` directory and execute `./ma ma.cfg`. Make sure you've configured your machine to run HADB server. See the EE Quickstart guide or the Administration guide for details on how to setup a machine to run HADB server.
  This section shows how to create a two-machine cluster and setup the cluster to use HADB server. For convenience sake, the machine running the Domain Administration Server (DAS) will be called the local machine and the second machine will be called the remote machine. Two node-agents are created, one on each machine. Before creating the cluster on the local machine, we need to create and start the node-agent on the remote machine. To do this, first start DAS on the local machine (`asadmin start-domain domain1`). Then, log on to the remote machine and go to `<install_dir>``/samples/ee-samples/`. Open the file `cluster.properties` for editing and set the values of `das.host, das.port, das.adminuser` and `das.adminpassword` corresponding to your DAS installation. Now execute `asant setup-remote-machine-for-2-machine-cluster` in the same directory. This command would do the following:
  1. Create a node-agent with name `nodeagent-remote.name*`
  2. Start the created node-agent
  Now, on the local machine go to `<install_dir>``/samples/ee-samples/` and execute `asant setup-local-machine-for-2-machine-cluster-with-ha`. This command will do the following:
  1. Create a cluster on the local machine with name `cluster.name*`
  2. Create a node-agent on the local machine with name `nodeagent.name*`
  3. Start the created node-agent on the local machine
  4. Create `instance1*` (that will use the node-agent created on the local machine) under the created cluster
  5. Create `instance2*` (that will use the node-agent created on the remote machine) under the created cluster
  6. Start the created cluster
  7. Configure the cluster to use HADB server
  * = value of this property is read from the `<install_dir>/samples/ee-samples/cluster.properties` file.

### Configuring the Load Balancer plugin

After installing the Load Balancer Plugin, configure the `loadbalancer.xml` file as follows:

> `<!DOCTYPE loadbalancer PUBLIC "-//Sun Microsystems Inc.//DTD Sun ONE Application Server 8.1//EN" "sun-loadbalancer_1_1.dtd">`
> `<loadbalancer>`
> `<cluster name="cluster1">`
> `<instance name="instance-ONE" enabled="true" disable-timeout-in-minutes="60" listeners="http://instance-ONE-host:instance-ONE-port"/>`
> `<instance name="instance-TWO" enabled="true" disable-timeout-in-minutes="60" listeners="http://instance-TWO-host:instance-TWO-port"/>`
> `<web-module context-root="clusterjsp" enabled="true" disable-timeout-in-minutes="60" error-url="./sun-http-lberror.html"/>`
> `<web-module context-root="dukesbookstore" enabled="true" disable-timeout-in-minutes="60" error-url="./sun-http-lberror.html"/>`
> `<web-module context-root="SessionStorage" enabled="true" disable-timeout-in-minutes="60" error-url="./sun-http-lberror.html"/>`
> `<web-module context-root="productClient" enabled="true" disable-timeout-in-minutes="60" error-url="./sun-http-lberror.html"/>`
> `<web-module context-root="RosterClient" enabled="true" disable-timeout-in-minutes="60" error-url="./sun-http-lberror.html"/>`
> `<web-module context-root="sfsbFailover" enabled="true" disable-timeout-in-minutes="60" error-url="./sun-http-lberror.html"/>`
> `<health-checker url="/" interval-in-seconds="10" timeout-in-seconds="30"/>`
> `</cluster>`
> `<property name="reload-poll-interval-in-seconds" value="60"/>`
> `<property name="response-timeout-in-seconds" value="30"/>`
> `<property name="https-routing" value="true"/>`
> `<property name="require-monitor-data" value="false"/>`
> `</loadbalancer>`

Note:

1. If you'd like to turn on the load balancer plug-in log messages, set the `require-monitor-data` property's value to true. The load balancer plug-in logs record the following information:
   * Request start/stop information is logged for every request.
   * Failed over request information is logged when the request fails over from an unhealthy instance to a healthy instance.
   * List of unhealthy instances is logged at the end of every health check cycle.
2. To enhance the availability of your applications deployed on a Sun Java System Application Server cluster, you can configure the load balancer to retry failed idempotent HTTP requests on all the application server instances in a cluster. For example, in the `clusterjsp` sample bundled with this application server, add the following tag to the `<install_dir>/samples/ee-samples/highavailability/apps/clusterjsp/clusterjsp-war/web/WEB-INF/sun-web.xml` file:

   > `.
   > .
   > <sun-web-app>
   > <idempotent-url-pattern url-pattern="/clusterjsp/*" num-of-retries="5"/>
   > <session-config>
   > .
   > .
   > `

For more information see the Sun Java System Application Server Administration Guide.

### Running the sample applications

For documentaion on how to deploy and run each EE samples, refer to the individual documents for those samples. A list of EE samples and links to their documentation can be found here.
While accessing a deployed sample application, failover capability of the Application server can be simulated by shutting down the application server instance that is servicing a current request. The instance that served a request can be found out by one of the following two ways:

1. Re-start the webserver (that has the Load balancer plugininstalled on it) before deploying a sample: This would ensure that the requests are served by instances in the order set in the `loadbalancer.xml`. In our case, from the above `loadbalancer.xml` the instance-ONE will be the appserver instance that serves the first request. In such cases, after the first request is served, the instance-ONE can be shutdown by executing the following command from the machine running Domain Administartion Server (DAS):

   > `asadmin stop-instance --user <adminuser> --password <adminpassword> instance-ONE`

2. Checking access logs of appserver instances: You can also check which appserver instance served a request by checking the the access logs of both the appserver instances. This file is called `server_access_lof` and can be found in `<install_dir>/nodeagents/<nodeagent.name>/<instance.name>/logs/` directory. Once you find out which instance served a client request, execute

   > `asadmin stop-instance --user <adminuser> --password <adminpassword> <instance-that-serverd-request>`

A request from client is now served by the other appserver instance.

### Troubleshooting

1. If `setup-one-machine-cluster-with-ha` or `setup-local-machine-for-2-machine-cluster-with-ha` asant tasks throw exceptions of this type:
   `Operation 'createHACluster' failed in 'hadb-config' Config Mbean.
   CLI137 Command configure-ha-cluster failed.
   Target exception message: HADBMGMT007:hadbm create command failed. Return value: 1, Message from hadbm: hadbm:Error 22176: The host <hostname> is not registered in the HADB management domain. Use hadbm createdomain to set up the management domain or hadbm extenddomain to include new hosts in an existing domain
   `

   Try the following steps:
   `# cd <install_dir>/hadb/<version>/bin
   # ./hadbm listdomain --adminpassword <adminpassword>
   ` == Sample Output ==
   `Hostname Enabled? Running? Release Interfaces
   abc.def.com Yes Yes V4-4-1-2 10.12.156.119
   `

   Now, in `<install_dir>/samples/ee-samples/cluster.properties` set the property `database.hosts` to `abc.def.com,abc.def.com` instead of `localhost,localhost` and execute `asant configure_hadb` .

Back to EE Samples table

Company Info | Contact | Copyright 2004-2005 Sun Microsystems