Sun ONE logo     
Lifecycle RMIServer Application



Lifecycle RMIServer Application


This document describes how to utilize the Lifecycle (RMIServer) sample application in conjunction with the Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

This sample is based on the LifecycleListener interface support provided by Sun ONE Application Server. This sample demonstrates the capability to bring up and shutdown a remote service (in this sample, an RMI server) from a custom lifecycle module in the Sun ONE Application server.

The following instructions describe how to assemble, deploy on the Application Server, and how to run the application. Although the sample application offers minimal functionality, this sample should provide you with a basic understanding of startup class support in the Sun One Application Server.


Configuration

The server.policy file located under <install_dir>/domains/domain1/server1/config needs to be manually modified for the sample to work.

Old: permission java.net.SocketPermission ""*", "connect";;

New: permission java.net.SocketPermission ""*", "connect,accept,resolve,listen";

Old: permission java.io.FilePermission "<<ALL FILES>>", "read,write";

New: permission java.io.FilePermission "<<ALL FILES>>", "read,write, execute";



Compiling and Assembling the Application



This Command Line Based Compilation and Assembly procedure describes how to assemble and compile the sample using a Command Line Interface (CLI).


Command Line Based Compilation and Assembly


To rebuild the entire application from scratch:

  1. Compile and Assemble.

    Execute the asant command under <install_dir>/samples/lifecycle/rmiserver/src/

    [please add <install_dir>/bin to your path]

    The default target core is executed to rebuild the .jar file.

  2. For this sample we need to create a policy file lifecycle-rmi.policy. Content of this file looks as follows:

    grant { permission java.security.AllPermission; };

  3. Modify property named policy.file in build.xml to point it to the lifecycle-rmi.policy file location.

  4. Deploy the application.

    When you have re-created the sample application from scratch, proceed to Deploying the application.

  5. Clean the application project area.

    Execute the asant clean command to remove the sample application's assemble and build directories.

    Now you are ready to use this .jar file for deployment.



Deploying the Sample Application

Select one of the following approaches to deploy the application:

  • Command Line Based Deployment describes how to manually register the application in a Sun ONE Application Server using a Command Line Interface (CLI). This is the fastest means of deploying the application.

  • GUI Based Deployment describes how to use the Sun ONE Deployment Tool to import and deploy the sample application.


Command Line Based Deployment

Since a complete .jar file is supplied, the fastest means of setting up the application is to use the command line utilities as described in this section.

If you want to deploy through a GUI tool, follow the instructions for GUI Based Deployment.

The pre-built lifecycle-rmiserver.jar file contains the Java Archive (JAR) files of the application.

Deploy using either the asant script or the asadmin command.


Using the asant Script

  1. Go to the src directory of the sample:

    <install_dir>/samples/lifecycle/rmiserver/src

  2. Execute the asant deploy command.


Using the asadmin Command

  1. Go to the root of the sample directory:

    <install_dir>/samples/lifecycle/rmiserver/

  2. Execute the asadmin command to deploy the application to the local application server instance:

    asadmin create-lifecycle-module -u <user-name> -w <password> -H <hostname> -p <admin server port> --classname samples.lifecycle.rmiserver.LifecycleListenerImpl --classpath <install_dir>/samples/lifecycle/rmiserver/src/../lifecycle-rmiserver.jar lifecycle-rmiserver

The deployment process involves the following operations:

  • It authenticates against the local application server's administrative server.

  • The .jar file is transferred to the administrative server.

  • The administrative server begins the registration process:

    • Parses the .jar file.

    • Explodes the bits into the repository.

    • Registers the J2EE application lifecycle-rmiserver by updating the server.xml file.

      If you want to verify the registration of the application, proceed to the Verifying Registration section.

      Otherwise, you are ready to exercise the application by Running the Sample Application.


GUI Based Deployment

Since a pre-built (.jar) file for the sample application is included with the application server, you can use the Admin Tool to quickly read in the .jar file and deploy it to the application server.

  1. Start the admin server if it is not already started.

    UNIX

    1. Goto <install_dir>/domains/domain1/admin-server/bin.

    2. Execute the startserv command.

    Windows

    1. Goto <install_dir>\domains\domain1\admin-server\bin

    2. Run startserv.

  2. Open the .jar file.

    1. Navigate to the browser based admin server page [http://<server-host>:<admin-port>/index.html].

    2. Enter your username and password to access the admin server.

    3. Click App Server Instances>server1>Applications>Lifecycle Modules .

    4. In the right hand pane, click Deploy to deploy an application.

    5. Fill in the Module Name, Classname and Classpath.

    6. Fill in Load order(Optional). Load order expects integer value which can be used to force the order in which deployed lifecycle modules are loaded at server startup. Smaller numbered modules get loaded sooner. Order is unspecified if two or more lifecycle modules have the same load-order value.

    7. You may also choose the relevent boolean values for Fatal faliure.

    8. You must also set the Enable flag to true in order to load this module at the time of server startup.

    9. Click on properties and set one property, policy.file to lifecycle-rmi.policy.

    10. A typical set of values for these attributes will be:

      Name lifecycle-rmiserver

      ClassName samples.lifecycle.rmiserver.LifecycleListenerImpl

      ClassPath /samples/lifecycle/rmiserver/src/../lifecycle-rmiserver.jar

      Click OK.

      If the deployment goes through properly, you see the original pane with the lifecycle-rmiserver application as deployed.


Note Once the sample is deployed, server.xml should look as follows:

<lifecycle-module is-failure-fatal="false" enabled="true" class-name="samples.lifecycle.rmiserver.LifecycleListenerImpl" name=" lifecycle-rmiserver" classpath="<install_dir>/samples/lifecycle/rmiserver/src/../lifecycle-rmiserver.jar"> <property value="<install_dir>/domains/domain1/server1/config/lifecycle-rmi.policy" name="policy.file"/> </lifecycle-module>



Verifying Registration

As an optional step, you can use the Sun ONE Application Server Administration Tool to verify that the application has been registered.

If you do not want to verify that the application has been registered, proceed directly to Running the Sample Application.


To verify the registration of the application:

  1. Navigate the Admin tool GUI to App Server Instances>server1>Applications>Lifecycle Modules.

  2. Click Lifecycle modules on the left frame menu to display a list of applications deployed on the server.



Running the Sample Application

Prior to running the sample, ensure that you have performed the following steps:

  1. Run the rmiregistry.

    UNIX

    1. set your env variable CLASSPATH to<install_dir>/samples/lifecycle/rmiserver/lifecycle-rmiserver.jar.

    2. Goto <install_dir>/jdk/bin/.

    3. Execute the rmiregistry command.

    Windows

    1. set your env variable CLASSPATH to<install_dir>\samples\lifecycle\rmiserver\lifecycle-rmiserver.jar.

    2. Goto <install_dir>\jdk\bin\

    3. Execute start rmiregistry command.

  2. You must set the classpath for running the sample. Here is how you can do it:

    1. Login to admin using http://hostname:port-number/

    2. Click App Server Instances>server1>JVM Settings>Path Settings>Classpath Suffix

    3. Append lifecycle-rmiserver.jar to the classpath

  3. Since this is a startup class, you need to stop and start the application server instance.

    1. asadmin stop-instance - H <hostname> -p <admin server port> -u <user-name> -w <password> <server-instance name>

    2. asadmin start-instance -H <hostname> -p <admin server port> -u <user-name> -w <password> <server-instance name>


    After the server has started, go to the log file of the server instance and look for the following messages:

    ...
    Lifecycle rmiserver sample: STARTUP_EVENT
    Creating SampleRMIServer
    SampleRMIServer bound
    In start() of SampleRMIServer

    Then stop the server and go to the log file of the server instance and look for the following messages:

    ...
    Lifecycle rmiserver sample: SHUTDOWN_EVENT
    In stop() of SampleRMIServer
    Destroying SampleRMIServer




    Generating Javadocs

    To understand sample application source code better, you can refer to the related javadocs. To generate javadocs, run the command

    asant javadocs

    or

    asant all

    After javadocs are generated, you can access them at

    <install_dir>/samples/lifecycle/rmiserver/javadocs/index.html



    Troubleshooting



    • If you get a java.net.ConnectException, make sure that your server.policy is modified as defined. After modifying server.policy, you need to "Apply Changes" (AdminGUI->serverInstance->ApplyChanges) and restart the server instance.

    • If you get a java.rmi.NotBoundException, make sure that the CLASSPATH is set as defined before starting rmiregistry, and check the path of policy.file in build.xml.

    • review the log files at /domains/domain1//logs/server.log to see what went wrong.

    • Make certain that you run asant undeploy before redeploying this sample to make sure that all modules are undeployed and the resources are disabled.



Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated July 10, 2002