Managing and Monitoring Web Services in Project GlassFish

One of the new technologies on the Java Platform, Enterprise Edition (J2EE platform) 1.4 is J2EE Management (JSR 77), a standard for disseminating and accessing management information, operations, and attributes for J2EE components. Along with other technologies, such as Java Management Extensions (JMX), J2EE Management offers a vendor-neutral way for managing and monitoring resourcesin particular, Web servicesthat reside on J2EE servers.

In general, however, tools have not taken advantage of those technologies to enhance the management and monitoring tasks for Web services. One recent exception is Project GlassFish, an open-source, application-server implementation of Java EE 5. In Project GlassFish, Web services are first-class objects that can easily be monitored and managed.

This article explains the management capabilities in Project GlassFish for Web services that are based on the Java API for XML Web Services (JAX-WS) 2.0 according to JSR 224 or JSR 109 and JAX-RPC 1.1. Project GlassFish supports the management capabilities through a combination of the command-line interface (CLI) called asadmin, the Administration Console, and programmatic Application Server Management Extensions (AMX) API. AMX, a superset of the JSR 77 interfaces built on JMX, further simplifies and smooths out the management and monitoring process.

In particular, this article shows you with an example how to develop, deploy, and debug a Web service on Project GlassFish.without any knowledge of the underlying, often complicated concepts. Here, you learn how to do the following:

• Deploy a simple, annotated Plain Old Java Object (POJO) as a Web service. You need not pay attention to the deployment descriptors or packaging.
• Test the POJO by pinging the Web service with the test forms that are automatically generated by Project GlassFish.
• Turn on the monitoring and message trace to browse the statistics and content of the Simple Object Access Protocol (SOAP) requests and responses. With the Call Flow capability, you can acquire a detailed view of how Project GlassFish handles the requests in the containers.

Lastly, this article explains more advanced topics, such as security, virtualization, and governance of Web services.

Note: In this article, the term Application Server denotes the Application Server build by the GlassFish community led by Sun. Regular builds of this artifact are available from java.net at http://glassfish.dev.java.net.

Contents

• Initial Setup
• Development and Deployment of POJO
• Web Services as First-Class Objects
  • Listing of Web Services
  • Details on Web Services
  • Test Forms
  • Web Services as JBI Service Providers
• Monitoring
  • Configuration
  • Monitoring With Statistics and Graphs
  • Self-Management of Web Services

Initial Setup

Note: Notwithstanding the line wraps for the CLI in this article, type all the commands in one line.

First, configure the environment:

Set up the appropriate environment variables, as follows:

You can now start Application Server by typing this command:

$AS_HOME/bin/asadmin start-domain domain1

Here is an example of the output:

Starting Domain domain1, please wait.

Log redirected to $AS_HOME/domains/domain1/logs/server.log.
Domain domain1 is ready to receive client requests. Additional services are
being started in the background.

Development and Deployment of POJO

Annotations are a breakthrough technique for developing and deploying Web services in Java EE 5. Let's take a simple Java file with one method that prints hello and convert it into a Web service. Do the following:

Import the javax.jws.WebService class.

Add the @WebService annotation to mark the class as a Web service. The class then reads like this:

package server;


import javax.jws.WebService;

@WebService
public class HelloImpl {
    /**
     * @param name
     * @return Say hello to the person.
     */
    public String sayHello(String name) {
        return "Hello, " + name + "!";
    }
}

For details on annotations, see JSR 181: Web Services Metadata for the Java Platform.

Save the file as HelloImpl.java.

Compile the file. Type:

javac -classpath $AS_HOME/lib/javaee.jar -d $AS_HOME/domains/domain1/autodeploy HelloImpl.java

Note: Your CLASSPATH variable must include the javaee.jar file.

Because it recognizes that the compiled HelloImpl class in the autodeploy directory contains annotations, Application Server immediately proceeds with two steps:

Process the annotations and generate the appropriate deployment descriptors.

So you need not run apt, the tool for processing annotations.

Deploy the class as a JAX-WS 2.0 Web service.

The Web service contains the sayHello operation with one input parameter, similar to the content of the POJO.

At the end of deployment, Application Server creates an empty file called HelloImpl.class_deployed in the autodeploy directory. In addition, the server log ( $AS_HOME/domains/domain1/logs/server.log) also contains information on the deployment. Here is a sample:

[#|2006-01-18T15:15:06.110-0800|INFO|sun-appserver-ee9.0

|javax.enterprise.system.tools.deployment|_ThreadID=12;_ThreadName=Timer-4;
|[AutoDeploy] Successfully autodeployed : /export/satish/install/tip-aug-10/domains/
domain1/autodeploy/server/HelloImpl.class.|#]

Take a look at the log to verify whether the deployment is successful.

Web Services as First-Class Objects

Most J2EE platform-compliant application servers list the deployed archives, that is, the enterprise archive (EAR), the Web archive (WAR), the Java archive (JAR), and the resource adapter archive (RAR) files. The Web-service endpoints in a domain are usually difficult to locate, however. To locate them, you must first browse through the deployment descriptors.

In contrast, Application Server clearly displays all Web-service endpoints in its Administration Console, along with other enterprise resources, such as Enterprise JavaBeans (EJB) components and servlets.

Listing of Web Services

For a list of the deployed Web services, do the following:

From your browser, go to http://localhost:4848/ to start the Administration Console.

Log in with the administrator user name and password, after which the Welcome screen opens.

The default user name is admin; the default password is adminadmin.

On the left navigation, click to expand the Applications folder and select Web Services.

The right pane is replaced with a pane titled Web Services, which contains an entry for HelloImpl and other basic information: the associated application ( server_HelloImpl), the associated Web Services Description Language (WSDL) file ( HelloImplService.wsdl), and the type of implementation (servlet). See Figure 1.

Figure 1: Information on Deployed Web-Service Endpoints

Alternatively, type this command for a list of the deployed Web services:

asadmin list-components --type webservice

Here is an example of the output:

Server_HelloImpl#HelloImpl <webservice>

Command list-components executed successfully.

where server_HelloImpl#HelloImplof the syntax module_name#endpoint_nameis the fully qualified name of the Web-service endpoint. For Web services within an application, the syntax is application_name#bundle_name#endpoint_name.

Details on Web Services

For the details on the HelloImpl Web-service endpoint, click the HelloImpl node under Web Services in the left navigation. Displayed are the endpoint URI, the name of the module in which the Web service is packaged, a list of the associated descriptors, and other specifics. See Figure 2.

Figure 2: Details of a Web-Service Endpoint

Application Server lists the mapping files only for JSR 109-based Web services. JAX-WS 2.0 delegates the tasks that relate to data binding to Java Architecture for XML Binding (JAXB) 2.0.

See this AMX code segment that outputs a list of the deployed Web-service endpoints:

try {

    // src is object of type AppserverConnectionSource.
    final DomainRoot domainRoot = src.getDomainRoot();

    Map m = dr.getWebServiceMgr().getWebServiceEndpointKeys();

    System.out.println("Number of web services " + m.keySet().size());
    System.out.println("Fully qualified names...");
    for (Iterator iter = m.keySet().iterator(); iter.hasNext();) {
        System.out.println((String)iter.next() + "\n"));
    }

    } catch(...) {
    }
(From WebServiceMgrTest.java)

WebServiceMgrSingletongetWebServiceEndpointKeysjava.util.Map

To see the Java source code for the samples referred to in this article, check out the section Unit/Acceptance Tests on Application Server's AMX page, which also points to the procedures for compiling and running the tests ( glassfish/admin/mbeanapi-impl/tests/amx-unit-tests.html). The Web services management and sample test files reside in the com/sun/enterprise/management/ext/wsmgmt subdirectory under glassfish/admin/mbeanapi-impl/tests.

Test Forms

Recall that, for deployed Web services, Application Server generates test forms with which you can ping those services. On the Administration Console, select the HelloImpl node under Web Services node and click Test. Figure 3 is an example of the test form that's displayed.

Figure 3: An Example of a Generated Web Service Test Form

Here, you can view the WDL file and test the operations with sample parameter values. Try it out and see how the Web service responds.

Encoding refers to the way in which data are serialized and sent over the wire, as specified by the use attributeof the value encoded or literalin the WSDL. The parties in the Web services exchange can agree on a predefined encoding scheme or a definition of the data types through an XML schema.

Literal encoding complies with the standards published by Web Services Interoperability Organization (WS-I). A literal message indicates that an XML schema specifies the rules for encoding and interpreting the SOAP body. In Application Server, the default encoding type is literal in the generated WSDL. Test forms work with literal encoding only.

Web Services as JBI Service Providers

Note this capability in Application Server: By default, the Java EE Service Engine enables Web services to be exposed as Java Business Integration (JBI) service providers in an Open Enterprise Service Bus (ESB) environment. Afterwards, flexible protocol binding (JMS and such) and the components that are in the ESB can directly communicate with Java EE applications.

To deactivate HelloImpl from the JBI environment, type these two commands:

asadmin configure-webservice-management server_HelloImpl#HelloImpl


asadmin set server.applications.web-module.server_HelloImpl.web-service-endpoint.HelloImpl..jbi-enabled=false

Monitoring

Application Server can track and graphically display operational statistics, such as the number of requests per second, the average response time, and the throughput. You can enable monitoring for each of the Web services within an application and set the monitoring level to one of the following:

• HIGH Application Server monitors the response times, throughput, the total number of requests, the faults, and the details of the SOAP message trace.
• LOW Application Server monitors only the response times, throughput, the total number of requests, and the faults.
• OFF Application Server collects no monitoring data.

If monitoring is on for a Web service (that is, LOW or HIGH), it applies to all the operations in that Web service.

Configuration

To display monitoring information on the Administration Console, do the following:

Click the Monitor tab in the page that displays the details on a Web service, as shown in Figure 2.

Since monitoring is off by default, the message "No statistic is available for this web service" is displayed.

Click the Configuration tab to turn on monitoring. Afterwards, set the monitoring level to HIGH to collect statistics and messages and then click Save. See Figure 4.

Figure 4: Configurations for Monitoring ( Click image for larger view.)

Alternatively, to enable monitoring from the CLI, do the following:

Type:

asadmin configure-webservice-management -monitoring=HIGH server_HelloImpl#HelloImpl

Send a request to the Web service with the test form.

Monitoring With Statistics and Graphs

For the statistics on the HelloImpl Web service, click Statistics tab of the Monitor page. Alternatively, type:

asadmin get -m "server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.*"

Here is an example of the output:

server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.averageresponsetime-count = 269
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.averageresponsetime-
description = Average response time measured in milliseconds
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.averageresponsetime-
lastsampletime = 1136333211736
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.averageresponsetime-
name = AverageResponseTime
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.averageresponsetime-
starttime = 1135041961846
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.averageresponse-timeunit = count
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint.dotted-name =
server.applications.server_HelloImpl.HelloImpl.webservice-endpoint

The CLI outputs additional datafor example, a description of each of the statistics and its unit of measurementother than that from the Administration Console.

By using QueryMgr, this AMX code segment queries for information on the monitor object in HelloImpl. WebServiceEndpointAggregateStats contains all the operational statistics.

                try {
    // dr is the DomainRoot object
    final QueryMgr q = dr.getQueryMgr();

    String[] wildNames = new String[] { "j2eeType", "name","X-WebModuleVirtualServerMonitor",
    "X-ServerRootMonitor", "X-ApplicationMonitor" };
    String[] wildValues = new String[] { "X-WebServiceEndpointMonitor","HelloImpl", "//
    server/HelloImpl", "server", "server_HelloImpl" };

    final Set wsMonitors = q.queryWildSet(wildNames,wildValues);

    if ( wsMonitors.size() == 0 ){
        System.out.println("WARNING: no web services found to test.");
        } else {
        System.out.println("Found " + wsMonitors.size() + "web services to test.");
        final Iterator iter = wsMonitors.iterator();
        while ( iter.hasNext() ) {
            final WebServiceEndpointMonitor m = (WebServiceEndpointMonitor)iter.next();
            final WebServiceEndpointAggregateStats s = m.getWebServiceEndpointAggregateStats();

            final CountStatistic r1 = s.getTotalFaults();
            assert( r1 != null );
            System.out.println("Total number of faults is "+ r1.getCount());

            final CountStatistic r2 = s.getTotalNumSuccess() ;
            assert( r2 != null );
            System.out.println("Total number of successful executions is "+ r2.getCount());
        ...
} catch(Exception e) {
    throw e;
}
(From WebServiceMonitorTest.java)

Sun Java System Application Server Enterprise Edition 9 (henceforth, Application Server EE 9) displays real-time graphs on the statistics for a Web-service endpoint. Figure 5 is an example of a graph on the response time.

Figure 5: Example of Real-Time Graph on Response Time

By default, Application Server updates the graph once every five seconds and stores the data in memory for 60 minutes. You can revise the settings for those frequencies.

Self-Management of Web Services

With the statistics as background data, you can trigger alerts or configure Application Server to perform management tasks. Specifically, you can build management rules, each comprising an event and an optional action, according to the standard AMX infrastructure. Feel free to adopt the predefined actions or develop action classes and then deploy them as managed beans (MBeans).