MQ Failover Sample Application |
MQ Failover Sample Application
This document describes how to utilize the MQ Failover Sample Application in conjunction with Sun Java System Application Server Enterprise Edition 8.1 2005Q1. This document also describes how to test the high availability feature in appserver for Message Driven Bean bean with application client.
This sample application document contains the following sections:
Overview
- Overview
- Compiling and Assembling the Sample Application
- Deploying the Sample Application
- Running the Sample Application
- Troubleshooting
The JMS Failover sample demonstrates the use of Message Driven bean. Typical use of a Message Driven bean is a Topic or Queue receiving messages. The Message Driven bean (MQFailoverTestMDB) represents a message bean recieving incoming messages to a Topic. The sample is comprised of an MJB and a application client. The appserver makes the MDB highly available. If one server goes down the conversational state (i.e the message sent to Topic) is migrated transparently to another available server instance in the cluster.
Compiling and Assembling the Sample Application
To recompile, assemble, and deploy the application, see the Sample Application Build Facility document for details on using a build facility to quickly perform these tasks.To rebuild the entire application from scratch, follow these steps:
Deploying the Sample Application
- Compile and Assemble Application. For example:
- Execute asant under <install_dir>/samples/ee-samples/failover/apps/mqfailover/
- The default target core will be executed to rebuild the .jar and .ear files.
- Deploy the application.
- Once you have re-created the sample application from scratch proceed to Deploying the Sample Application.
- Clean the application project area. For example:
- Execute asant clean
- This will remove the sample application assemble and build directories.
Before deploying or rebuilding this application on an instance of Sun Java System Application Server 8.1 that was installed as part of JES, please follow the steps listed in Section 10 of this file.
A pre-built mqFailover.ear file is supplied with the application server installation. The pre-built mqFailover.ear file is an Enterprise Archive (.ear) file that contains, the EJB .jar file, and the client jar file of the application. Within each file resides the XML deployment descriptor files, application class files, and other content required by the application. You can use the pre-built .ear file to deploy the application. If you want to experience compiling and assembling the application from scratch, follow the instructions in Compiling and Assembling the Sample Application.To deploy the application, the administrative server needs to be running. To start the administrative server if it is not already started, do one of the following, depending on your oeprating system.
Select one of the following approaches to deploying the application:
- UNIX
- Execute <install_dir>/bin/asadmin start-domain domain1
- Windows
- Start->Programs->Sun Java(TM) System Application Server->Start Application Server
Command Line-based Deployment
- Command Line-based Deployment describes how to manually register the application in Sun Java (tm) System Application Server using a Command Line Interface (CLI). This is the fastest means of deploying the sample application.
- GUI-based Deployment describes how to use the Sun Java(TM) System Application Server Deployment Tool to import and deploy the sample application.
Command Line Interface is the fastest means of deploying the application. If you want to deploy through a GUI tool, follow the instructions for GUI Based Deployment. CLI deployment of the application can be done by either the Using the asant script or by Using the asadmin command.
Using the asadmin command
- Go to the src directory of the sample. For example:
- cd <install_dir>/samples/ee-samples/failover/apps/mqfailover
- Run asant using deploy task. For example:
- % asant deploy
- It is an interactive command that may prompt you for the admin-server host, admin-server port, admin user name, admin password, and appserv instance. This also registers the resources to the Sun Java(TM) System Application Server.
- Go to the root of the sample directory. For example:
- cd <install_dir>/samples/ee-samples/failover/apps/mqfailover
- Execute asadmin to deploy application to the local application server instance. For example:
- asadmin deploy --user <adminuser> --password <adminpassword> --host <DAShost> -port <admin server port> --target <cluster-name> mqFailover.ear
Where <adminuser> is the Domain Administration Server's admin username, <adminpassword> is the admin user's password, <DAShost> is the machine on which Domain Administration Server is installed and running, <DASport> is port at which Domain Administration Server is running and <target> is the application cluster on which the sample application is to be deployed. If you would like to verify the registration of the application, you may proceed to Verifying Deployment. Otherwise, proceed to Running the Sample Application.
Since a pre-built Enterprise Archive (EAR) file for the sample application is included with the application server, you can use the Sun Java (tm) System Application Server Administration Tool to quickly deploy it to the Application Server.
- From your web browser, access the Sun Java (tm) System Application Server by entering the URL. For example:
- https://<DAShost>:<DASport>
- Enter the server administrator's username and password to access the admin server.
- On the left panel, navigate the tree by clicking on the following:
- Cluster -> <cluster-name>
- On the right panel, the Applications tab will be pre-selected. In the " --New--" drop down list select "Enterprise Application". The "Deployment Page" will load in the right frame.
- Set "Upload" to "Yes" and click on `Browse' to select the .ear file (from disk) to be deployed (mqFailover.ear) Click `Next' on the top right hand corner of the frame. .
- Enter the application name as mqFailover. Enable "Availability" checkbox and add a target cluster to deploy the application on from the displayed list in the "Targets" section.
- Click OK
If the deployment succeeds, you will see the `Enterprise Applications' panel and under `Deployed Enterprise Applications' you will see the mqFailover application as deployed.
As an optional step, you can use the Sun Java(TM) System Application Server Administration Tool to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.
To verify the registration of the application, follow these steps:
- Execute the command asadmin list-components to look at applications deployed with a server instance. For example:
- asadmin list-components --user <adminuser> --password <adminpassword> --host <DAShost> --port DASport> --target <cluster-name>
Generating Javadocs
To better understand the sample application source code, you can refer to the related javadocs.
To generate javadocs run one of the following commands:
After javadocs are generated, you can access them at <install_dir>/samples/ee-samples/failover/apps/mqfailover/javadocs/index.html
Running the Sample Application
1. Application client.
To see the failover of the MQFailover application happening, use 4 consoles for running this sample:
Console 1
cd <install_dir>/samples/ee-samples
asant start-mq-master-broker1
Console 2
cd <install_dir>/samples/ee-samples
asant start-mq-cluster-broker1
Console 3
cd <install_dir>/samples/ee-samples
asant start-mq-cluster-broker2
Console 4
cd <install_dir>/samples/ee-samples
asadmin start-domain domain1
If you have already executedasant setup-one-machine-cluster-without-ha
orasant setup-one-machine-cluster-with-ha
for any other EE sample, then execute: asant configure-mq
otherwise execute: asant setup-one-machine-cluster-and-configure-mq
cd failover/apps/mqfailover/
asant deploy
Modify sun-acc.xml
Now modify <install_dir>/domains/domain1/config/sun-acc.xml
from:
<target-server name="<host.name>" address="<host.name>" port="3700"/>
to make port point to ${instance1.orblist.port} [default 3330]
<target-server name="<host.name>" address="<host.name>" port="3330"/>
Run appclient:
appclient -client ./mqFailoverClient.jar
-xml <install_dir>/domains/domain1/config/sun-acc.xml -name MQFailoverTestClient
-textauth -user j2ee -password j2ee
Note: How to run if appclient was rebuilt:
If you have first executed asant core to rebuild the application client, then you should execute this command below, instead of the one shown above, to run the client:
appclient -client ./mqfailover-client/build/assemble/client/mqFailoverClient.jar
-xml <install_dir>/domains/domain1/config/sun-acc.xml -name MQFailoverTestClient
-textauth -user j2ee -password j2ee
When a dialog is thrown, go to console 2, press Ctrl+C to kill broker2/or kill the broker2
process [In *nix: ps -efa | grep "port 7679"] and execute :
asant start-mq-cluster-broker2
again to simulate broker restart
Observe all messages are received in client inspite of the MQ broker stop/restart. You can check the instance server logs [or wait for the dialog box messages to indicate receipt of messages] for the reply messages to verify that they are received properly.
To stop all AS/MQ processes:
stop MQ brokers - press CTRL+C on consoles 1 and 2
asadmin stop-cluster cluster1
asadmin stop-node-agent cluster1-nodeagent
asadmin stop-domain domain1
Troubleshooting
- Make certain that you run the asant undeploy command before redeploying this sample to make sure that all modules are undeployed properly.
- If you encounter problems when running the application, review the server log file at <install_dir>/domains/domain1/logs/server.log to learn what went wrong.
Other logs are located here:
instance-one: <install_dir>/nodeagents/cluster1-nodeagent/instance-ONE/logs/server.log
instance-two: <install_dir>/nodeagents/cluster1-nodeagent/instance-TWO/logs/server.log
MQ broker1 log: <install_dir>/domains/domain1/imq/instances/samplesbroker1/log/log.txt
MQ broker2 log: <install_dir>/domains/domain1/imq/instances/samplesbroker2/log/log.txt
MQ master broker log: <install_dir>/domains/domain1/imq/instances/samplesmasterbroker/log/log.txt
Copyright © 2004-2005 Sun Microsystems, Inc. All rights reserved.