test

Sun Java System Application Server Platform Edition 9 Administration Guide

Chapter 12 Managing Web Services

This chapter describes web services management with Application Server. Admin Console and the asadmin tool enable you deploy, test, and manage web services. You can view, manage, and monitor all web services deployed in a domain just as you see Java EE applications and application components such as EJBs.

You can also:

This chapter contains the following topics:

For information on securing web services, see Chapter 9, Configuring Message Security.

Overview of Web Services

Extensible Markup Language (XML), developed by the World Wide Web Consortium (W3C) is one of the foundations of web services technology. XML enables web services and clients to communicate with each other in a common language. XML is a simple, flexible, text-based markup language in which data are marked using tags enclosed in angle brackets. Such markup allows different systems to easily exchange data with each other.

A web service is an application accessed by clients using XML-based protocols, such as Simple Object Access Protocol (SOAP), sent over internet protocols such as Hypertext Transfer Protocol (HTTP). Clients access a web service application through its interfaces and bindings, defined using XML artifacts such as a web services Definition Language (WSDL) file.

A Document Type Definition (DTD) or XML Schema Definition (XSD) describes the structure of an XML document. It has the tags an XML document can have, the order of those tags, and so on.

Extensible Stylesheet Language Transformation (XSLT) transforms XML documents from one format to another.

Web Services Standards

Simple Object Access Protocol (SOAP) provides a common messaging format for web services. SOAP enables objects not known to one another to exchange messages. SOAP uses an XML-based data encoding format and HTTP to transport messages. SOAP is independent of both the programming language and the operational platform, and it does not require any specific technology at its endpoints.

ebXML (Electronic Business using eXtensible Markup Language) is a set of specifications that enables enterprises to conduct business over the Internet. OASIS (Organization for the Advancement of Structured Information Standards) controls the ebXML specifications. Similar to a telephone system's yellow pages, an ebXML registry enables providers to register their services and requestors to find services. Once a requestor finds a service, the registry has no more role to play between the requestor and the provider.

Universal Description, Discovery, and Integration (UDDI) provides a standard way to register, de-register, and look up web services.

Web Services Description Language (WSDL) defines a standard way to specify the details of a web service. It is a general-purpose XML schema that can specify details of web service interfaces, bindings, and other deployment details. By having such a standard way to specify details of a service, clients who have no prior knowledge of a web service can use it.

Java EE Web Service Standards

Java API for XML-based remote procedure calls (JAX-RPC) uses an XML-based protocol for client-server remote procedure calls. JAX-RPC enables SOAP-based interoperable and portable web services. Developers use the JAX-RPC programming model to develop SOAP-based web service endpoints, along with corresponding WSDL descriptions, and clients. A JAX-RPC based web service can interact with clients that are not based on Java. Conversely, a JAX-RPC based client can interact with a non-Java-based web service implementation.

Java API for XML Web Services (JAX-WS) 2.0 is the successor to JAX-RPC that provides an “integrated stack” of APIs for developing web services, including:

SOAP with Attachments API for Java (SAAJ) enables developers to produce and consume messages conforming to the SOAP 1.1 specification and SOAP with Attachments note. SAAJ provides an abstraction for handling SOAP messages with attachments. Advanced developers can use SAAJ to have their applications operate directly with SOAP messages. Attachments may be complete XML documents, XML fragments, or MIME-type attachments. In addition, SAAJ allows developers to enable support for other MIME types. JAX technologies, such as JAX-RPC, internally use SAAJ to hide SOAP complexities from developers. SAAJ enables:

JSR 109 (Implementing Enterprise Web Services) facilitates building interoperable web services in the Java EE environment. It standardizes the deployment of Web services in a Java EE container. JSR-109 builds upon JAX-RPC to define a standard mechanism for deploying a web service in Enterprise JavaBean (EJB) and servlet containers. Application Server supports managing JSR 109 applications based on either JAX-RPC or JAX WS 2.0.

JSR 181 (Web Services Metadata for the Java Platform) defines an annotated Java format that uses Java Language Metadata to enable easy definition of Java web services in a Java EE container.

Deploying and Testing Web Services

Application Server enables you to easily deploy and test web services. Admin Console automatically generates a test web page that makes it very easy to verify a web service's operation without writing a client application.

Deploying Web Services

You can deploy a web service:

A web service can also be implemented by a POJO (plain old Java Object). Deploy a POJO web service using the auto-deploy feature by dragging and dropping it into the auto-deploy directory. Application Server will automatically generate the appropriate deployment descriptor files and deploy the web service.

In Admin Console, you can view a list of deployed web services under Application Server > Web Services | General.

You can also use the deploy(1) command to deploy a web service.

Viewing Deployed Web Services

To view a list of all deployed web services with Admin Console, select Application Server > Web Services. The General tab displays a table containing the following information:

To view details of a web service with Admin Console, select Web Services > web-service-name | General. Admin Console displays the attributes of the web service:

You can also view deployed web services with the list-components(1) command with the --type webservice option.

Testing Web Services

Admin Console enables you to test web services and diagnose problems.

To test a web service with Admin Console, select Web Services > web-service-name | General, then click the Test button. For JAX-WS 2.0–compliant web services, Application Server generates a test page when a JAX-WS 2.0 web service is deployed. You can launch the test web page from Admin Console to easily verify a web service's operation without writing a client application.

The automatically-generated test page contains a form that enables you to invoke all the web service's methods and display the SOAP messages for each method invocation. The test page also contains a link that displays the WSDL file returned from the sever instance; that is, the runtime version of the WSDL file, not the packaged version.

Web Services Security

Application Server supports SOAP message layer security based on the SAML token profile of WS-Security. Application Server also provides tamper-proof auditing for web services. For more information, see Auditing Authentication and Authorization Decisions and Audit Modules.

You can use default message security providers to provide web services security. Use the following commands to customize the message security providers:

For more information about configuring security for web services, see Chapter 9, Configuring Message Security

Publishing to Web Services Registries

A web service registry is like a “phone book” for web services. It enables client applications to look up and find web services. Application Server supports two widely-used registry standards: ebXML (Electronic Business using XML) and Universal Description, Discovery, and Integration (UDDI). A company can host an internal registry for use by web services within the corporate firewall, or externally for use by customers, business partners, and other external entities.

Note –

Application Server does not have an internal registry. To publish web services to an internal registry, you must download and install the registry on the application server. To publish a web service to an external registry, specify the address of the external registry.

Adding a Connector Module for a Registry

Application Server has client-side implementations to enable you to communicate with registry servers plugged in as connector resource adapters. This enables Application Server to transparently connect to multiple registry types by using different resource adapters.

Before you can add a registry to which to publish web services, you must deploy an appropriate connector module. With Admin Console, add a connector module at Application Server > Applications > Connector Modules. Click the Deploy button to deploy a new connector module, then choose the appropriate resource adapter archive (RAR) file.

Application Server comes with a pre-deployed resource adapter for a UDDI registry. So, you do not need to deploy a resource adapter to use a UDDI registry.

Setting up a Registry for use with Application Server

Application Server does not currently provide a web services registry. If you want to use an ebXML registry, downolad the Java Web Services Developer Pack (JWSDP) 1.6, which includes an ebXML registry. To run JWSDP, you must use Application Server 8.2 or another web container such as Tomcat.

To set up your own registry to work with Application Server, follow the procedures in this section.

ProcedureTo Create a Registry

  1. Download Java Web Services Developer Pack (JWSDP) 1.6: http://java.sun.com/webservices/downloads/1.6/index.html.

  2. Install JWSDP 1.6 on your system.

  3. Download and install the desired web container.

    JWSDP 1.6 works with Application Server 8.2, J2EE 1.4 SDK, and Tomcat 5.0 for JWSDP. You cannot use Application Server 9 as the web container with JWSDP 1.6.

  4. Change the default port that the web container uses.

    Application Server 9 uses port 8080 by default, so you must change the port that the web container uses to avoid conflicts. Change the port, for example, to 7080. With Tomcat, you can do this in the server.xml file. In Sun Java System Application Server 8.2 you can do this using Admin Console.

  5. Start the container.

    This starts the installed registry by default. JWSDP 1.6 comes with the registry preconfigured.

  6. Configure the resource adapter to work with Application Server, as described in the next section.

ProcedureTo Configure a Resource Adapter for an ebXML Registry

The result of this procedure will be to create a soar.rar resource adapter file that you can deploy to Application Server.

Before You Begin

Set the JWSDP_HOME environment variable to the directory where JWSDP 1.6 is installed and the JAVA_HOME environment variable to the directory where J2SE is installed.

  1. Download the ra.xml file from the Glassfish site: https://glassfish.dev.java.net/javaee5/ws-mgmt/registry/ra.xml.

    Save the file in the /tmp directory (C:\tmp on Windows).

  2. You can either download and execute a script, or perform the steps manually.

    • To use a script:

      1. Download one of the following scripts:

        Save the script to the /tmp directory (C:\tmp on Windows).

      2. Execute the script.

    • To perform the steps manually:

      1. Enter the following commands:

        cd $JWSDP_HOME/registry/lib
mkdir tmp
cp soar-jaxr-ra.jar ./tmp
cd tmp
jar xvf soar-jaxr-ra.jar
rm soar-jaxr-ra.jar ra.xml ./META-INF/SUN* ./META-INF/pack.properties
cp ra.xml META_INF .
cp $JWSDP_HOME/registry/lib/oasis-* .
cp $JWSDP_HOME/registry/lib/omar-common.jar .
cp $JWSDP_HOME/registry/lib/jaxr-ebxml.jar .
cp $JWSDP_HOME/jwsdp-shared/lib/commons-logging.jar .
        Note –

        The commands shown are for Unix or Linux. Use the equivalent commands on Windows.

        Now, the tmp directory should contain the following files and directories:

        • META-INF directory

        • com directory

        • jaxr-ebxml.jar

        • oasis-regrep.jar

        • omar-common.jar

        • oasis-saml1.1.jar

        • oasis-saml2.0.jar

        • commons-logging.jar

      2. Enter this command to create resource adapter file soar.rar:


        jar cvf soar.rar META-INF com jaxr-ebxml.jar oasis-regrep.jar omar-common.jar oasis-saml1.1.jar oasis-saml2.0.jar commons-logging.jar
        Note –

        To use the jar command on Windows, you must have the JAVA_HOME\bin directory on your path.

Next Steps

Once you have created the soar.rar file, deploy it to create a registry as described in the next section.

Adding a Registry

Adding a registry is equivalent to creating a connector connection pool and adding a corresponding resource to the Application Server. This functionality is provided as a convenience, and enables Application Server to communicate to a registry, as described previously.

Add or remove a web services registry with Admin Console at Application Server > Web Services | Registry. Click Add to add a new registry to which to publish web services. The Add Registry Page appears. Use this page to create a Registry Access Point (RAP). For help on using Admin Console, click Help.

When you add a registry, specify the following parameters:

Publishing a Web Service to a Registry

To publish a web service with Admin Console, select Web Services > web-service-name | Publish.

In the Publish Web Service screen, select one or more registries to which you want to publish the web service, then click Publish. To publish to all the available registries, click the Add All button.

Enter categories under which this web service will show up in the registry. Use a comma to separate each category. The categories are defined in the registry you are using. Enter a description and the name of the organization for this web service.

If you are using a load balancer, enter the load balancer host name, port number, and the SSL port number. If you are publishing the web service to an external registry, where the WSDL can be found over the internet, these options will replace the hostname and port name specified in the WSDL to the one of the load balancer.

To un-publish a web service, In the Publish Web Service screen, select the registry from which you want to un-publish the web service, then click Unpublish.

You can also use the following commands to publish a web service, un-publish a web service, and list registry locations:

Monitoring Web Services

Admin Console can track operational statistics for web services, and can display messages sent and received by web services.

To enable monitoring for a web service, with Admin Console, select Web Services > web-service-name | Monitor | Configuration.

In the Monitoring Configuration page, set the monitoring level:

Enter a value for the Message History. The default is 25. Click the Reset button to clear all statistics and the running averages are restarted.

You can also configure web service monitoring with the configure-webservice-management(1) command.

Viewing Web Service Statistics

Application Server9 provides capabilities to track the operational statistics of a web service.

View monitoring statistics at Web Services > web-service-name | Monitor | Statistics. The statistics available are:

Viewing Web Service Messages

You can also configure a web service to view messages for a web service endpoint. Monitor web service messages at Web Services > web-service-name | Monitor | Messages.

By default, Admin Console retains the last 25 messages. Admin Console displays details of SOAP requests, responses, and HTTP header information. In addition, the following information is displayed for a web service request:

You can also select a filter to view only the success messages or the failure messages. If call flow monitoring is enabled, each message is linked to call flow information that enables you to look at the call stack information for each message.

Transforming Messages with XSLT Filters

You can apply XSLT transformation rules to a web service end point. This enables fine-grained control of web service requests and responses. You can apply multiple XSLT rules to a web service end point method, and you can configure the order in which you apply the transformations.

You can apply transformation rule to a SOAP request or response.

Before revising an application to apply transformation rules, evaluate the pros and cons of doing so: Applying XSLT can lengthen processing time for a web service. In other cases, XSLT makes sense, for example if a web service is exposed to partners with different XML data exchange formats or different security requirements. In such cases, transformation rules can act as a proxy for the web service and be advantageous.

To add a transformation rule to apply to a web service operation with Admin Console, select Web Services > web-service-name | Transformation. Click Add. Admin Console displays a list of transformation rules available for the web service endpoint. To add a new transformation rule, click Add, and then browse to the location of the XSLT file that contains the transformation rule.

To enable a transformation rule, in the Transformation Rules page select the check box corresponding to the rule, then click Enable. To disable the a rule, click Disable.

If you add multiple transformation rules for a web service endpoint, the transformation rules are applied in the order in which they are added.

To remove a transformation rule, in the Transformation Rules page select the check box corresponding to the rule, then click Remove. This removes the transformation rule from the list and removes the corresponding XSLT file.

Additionally, you can create, delete, and list transformation rules with the following asadmin commands:

Web Services as JBI Service Providers

By default, Application Server exposes web services as Java Business Integration (JBI) service providers for Open Enterprise Service Bus (ESB). Afterwards, flexible protocol binding and the components in the ESB can directly communicate with Java EE applications, using, for example, JMS.

You can disable this feature by using asadmin to set the endpoint's jbi-enabled property to false. For example, to deactivate HelloImpl from the JBI environment, use the commands: 

asadmin configure-webservice-management server_HelloImpl#HelloImpl 
asadmin set server.applications.web-module.server_HelloImpl.webservice-endpoint.HelloImpl.jbi-enabled=false

Open ESB implements an Enterprise Service Bus (ESB) runtime with sample service engines and binding components. Open ESB enables you to create composite applications by loosely coupling enterprise applications and web services. Additionally, you can easily recompose such composite applications, realizing the benefits of a true service oriented architecture (SOA). The core of the Open ESB SDK is based on Java Business Integration (JBI) technology, defined in the JSR 208 specification.

For more information on JBI and Open ESB, see Project Open ESB.