Remote Management of Application-Server Domains

Print-friendly Version

The Management Specification for the Java 2 Platform, Enterprise Edition (J2EE platform)—Java Specification Request (JSR) 77—describes how an application server that complies with that platform exposes its model and the relationships between its managed objects. The implementation of those objects are known as Java Management Extensions (JMX) Managed Beans, MBeans for short. The exposed version of the MBeans for the application server performs the operations on the components that make up the domain.

This paper describes how to manage a domain of application-server instances by exporting the hierarchy of the J2EE Management Model and cites Sun Java System Application Server 8.1 (henceforth, Application Server) as an example. Two major steps are involved:

• Deploy a Web service that exposes aggregate management functions for use by Web-service clients. For demonstration, this paper cites a J2ME mobile client, AppserverAdminMobile, that uses the Web service through the Java 2 Platform, Micro Edition (J2ME platform) Web Service (JSR 172) component in Wireless Took Kit 2.2.
  
  
• Run the J2ME client to take advantage of the Web service.

When working extensively with MBeans, you would be prudent to invoke their methods with a dynamic proxy to ensure compile-time checking. In our experience, you can save a lot of debugging time that way.

Instead of using advanced patterns, we opted for a simple approach to emphasize how the application interacts with the MBean's attributes and operations. We chose to use direct MBeanServer invocations in this article; you can use a Dynamic proxy with an interface that is bundled with the source in the class com.sun.admin.util.MBeanProxy.

Figure 1 illustrates the relationships and logic flow. For details, see a description on java.net.

Figure 1: Topology of Remotely Managing an Application Server Domain

First, install Application Server Standard Edition (SE) or Enterprise Edition (EE) at $J2EE_HOME. Both editions use the same installation bits; the only difference is that the High Availability Database (HADB) component is available in EE.

In addition, install the following software:

• J2ME Wireless Toolkit (WTK) 2.2 or a later version — For running the J2ME Web-service client in the emulator. In this article, the WTK installation directory is referred to as J2ME_WTK_install_dir.
  
  
• (Optional) A Web server to hold the Load Balancer plug-in — For load-balancing the Application Server instances. We suggest the free trial version of Sun Java System Web Server 6.1 (henceforth, Web Server); just follow the installation instructions. You can install the plug-in and Application Server in one cycle.

Next, let's walk through the execution of Ant tasks to run most of the commands to build, package, and deploy the AppserverAdminWS Web archive (WAR) file.

First, download the Java archive (JAR) file (AppserverAdminWS.jar) for Appserver AdminWS and then install the demonstration bundle by executing the java command, as follows:

Java_install_dir/bin/java -jar AppserverAdminWS.jar

You are then prompted to agree to the license terms. Afterwards, you'll see a ZIP file in the directory where you ran the command. The rest of this document refers to that directory as app_install_dir.

To set up the AppserverAdminWS Web module, set the J2EE_HOME environment variable. The scripts that invoke Ant look for the version included with Application Server. To start Ant, type asant at $J2EE_HOME/bin. Ant 1.5.4 or a later version will work.

Note: On Windows 2000, to bypass a bug in the asant script, either run $J2EE_HOME/lib/ant/bin/ant or install a separate version of Ant.

Ensure the following:

• J2EE_HOME points to the root directory of your Application Server installation. For example, if you installed Application Server in its default location of /opt/SUNWappserver/appserver, set the value of J2EE_HOME to that path.
  
  
• JAVA_HOME points to the root directory of your Java 2 Platform, Standard Edition (J2SE platform) Software Developer Kit (SDK) installation. For example:
  
  
  • If you installed the J2SE SDK in /jdk1.5, set the value of JAVA_HOME to that path.
    
    
  • If you are using the J2SE SDK that's bundled with the standalone version of Application Server EE, set JAVA_HOME to $J2EE_HOME/jdk.

Your PATH value must include the $JAVA_HOME/bin and $J2EE_HOME/bin directories as the first two elements.

Configure your environment by revising the settings of the following properties in the app_install_dir/AppserverAdminWS/src/com/sun/admin/server/ AppserverAdmin.properties file. The examples serve as a point of reference.

Property Name	Description	Example
lbWebServerConfigDir	The location of the Web Server's config directory, in which the loadbalancer.xml file resides, to be read by the Load Balancer plug-in. If you do not use that plug-in and none of your servers are part of a Load Balancer configuration, this value is dormant. See the details on the AppserverAdminWS commands. Note: Grant the user who runs the Domain Administration Server both read and write permissions to the Web Server's config directory.	/opt/SUNWwbsvr/https-hostname/config
adminHost	The name of the server in which Application Server's Domain Administration Server is installed.	localhost
adminPort	The number of the server port to which Application Server's Domain Administration Server listens.	4849
adminUser	The ID of the Domain Administration Server user.	admin
adminPassword	The password for accessing the Domain Administration Server.	adminadmin
secureFlag	The flag that denotes whether the Domain Administration Server is secure. As a default for Application Server SE or EE, set this flag to true.	true

For the Web service to be ready, you must revise the domain's security policy to grant the relevant permissions to the AppserverAdminWS Web module. The file in question, called server.policy, resides at $J2EE_HOME/domains/domain_name/config. For example, the default server.policy file for domain1 is at $J2EE_HOME/domains/domain1/config/server.policy. Edit it and add the two grant statements, as follows:

// grant admin web module directory access to needed permissions
grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/
AppserverAdminWS/-"{
    permission java.io.FilePermission "<<ALL FILES>>", "execute";
    permission javax.net.ssl.SSLPermission "setHostnameVerifier";
    permission java.lang.RuntimePermission "setFactory";
    permission java.util.logging.LoggingPermission "control";
    permission javax.management.MBeanServerPermission "*";
    permission javax.management.MBeanPermission "*", "*";
};
// grant admin web module generated directory access to needed permissions
grant codeBase "file:${com.sun.aas.instanceRoot}/generated/ejb/j2ee-modules/
AppserverAdminWS/-" {
    permission java.io.FilePermission "<<ALL FILES>>", "execute";
    permission javax.net.ssl.SSLPermission "setHostnameVerifier";
    permission java.lang.RuntimePermission "setFactory";
    permission java.util.logging.LoggingPermission "control";
    permission javax.management.MBeanServerPermission "*";
    permission javax.management.MBeanPermission "*", "*";
};

Once you've set up the various properties, perform three Ant tasks to build, package, and deploy the Web module. Type the following commands—and remember to start the Domain Administration Server before deployment.

$J2EE_HOME/bin/asant build
$J2EE_HOME/bin/asant package
$J2EE_HOME/bin/asant deploy

To verify that you have properly deployed the Web service, check the Web module's WSDL page by accessing its URL:

http://das_hostname:das_portnumber/AppserverAdminWS/AppserverAdminWS?WSDL

For example:

http://localhost:8080/AppserverAdminWS/AppserverAdminWS?WSDL

The context root is protected by basic authentication by default; therefore, you'll be prompted to enter the administrator's user ID and password.

To deploy the Web-service client, copy the app_install_dir/AppserverAdminWS/AppserverAdminMobile directory under J2ME_WTK_install_dir/apps. Next, do the following:

1. Run the J2ME_WTK_install_dir/bin/ktoolbar executable.
   
   
2. Click Open Project in the top bar and, in the hierarchy, navigate to the apps/AppserverAdminMobile project that you just copied.
   
   
3. Click Open Project.
   
   The project opens.
   
   
4. Click Settings in the top bar to open the settings window.
   
   
5. Click User Defined and configure AppserverAdmin-Service-URL to point to your Domain Administration Server's host name and port number, for example, http://localhost:8080/AppserverAdminWS/AppserverAdminWS. Click OK.
   
   
6. Click Run in the top bar to run the J2ME emulator.
   
   The default emulator is displayed.

For details on the J2ME Wireless Toolkit, see its documentation (J2ME_WTK_install_dir/docs/UserGuide.pdf).

To run the J2ME Web-service client, do the following:

1. Start the AppserverAdminMobile application by right-clicking the emulator called Launch.
   
   
2. Log in with the administrator's user ID and password and then right-click the emulator called Login.
   
   The URL that connects with the Domain Administration Server is displayed at the bottom of the screen.
   
   
3. From the navigation mechanism that applies to your emulator, press the directional choices on the default SELECT key to choose the cluster or stand-alone server.

The server-specific screens contain options that vary according to whether the server is associated with a load-balancing configuration. If yes, the Quiesce and Unquiesce options are displayed.

Using the J2ME application is intuitive. For more information, see the section, "Detailed Use of the J2ME Web Service Client," in the document on the details of this article's subject.

Note: When you start a cluster or server, synchronization and launch of the component may not be complete by the time the response reaches the client. Also, when you navigate backwards, the screen state remains the same. You may need to refresh the screen in order to see the true state of the domain.

You can now move on to the following:

• Download and install the highly available version of Java BluePrints Adventure Builder, a robust application you can now manage remotely.
  
  
• Adopt a secure protocol for your J2ME client's transport. For the procedure, see the section, "J2ME Web Service Client with HTTPS," in the document that delves into the details of this article's subject.

Above all, take a look at the ongoing Java BluePrints Project on java.net!

• Reliability, Availability, and Serviceability (RAS) for J2EE1.4 Application Servers Project
  
  
• Sun Java System Application Server
  • Main page
  • Developer home
  • Software Forum
  
  
• Sun Java System Web Server
  • Main page
  • Developer home
  • Software Forum
  
  
• Java Wireless Toolkit
  
  
• J2EE Management Specification (JSR 77)
  
  
• J2ME Web Services Specification (JSR 172)