Sun GlassFish Enterprise Server v2.1.1 Administration Guide

Chapter 14 Managing Web Services

This chapter describes web services management with Enterprise Server. Admin Console and the asadmin tool enable you deploy, test, and manage web services. You can quickly visualize, understand, monitor, and manage complex web services. You can see 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:

Overview of Web Services

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 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.

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

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

XSLT, which stands for eXtensible Stylesheet Language Transformation, is used for transforming 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

Universal Description, Discovery, and Integration (UDDI) provides a standard way to register, de-register, and look up web services. Similar to a telephone system's yellow pages, a UDDI registry's 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.

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 specifies 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.

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.

Java EE Web Service Standards

Java APIs for XML processing (JAXP) is a vendor-neutral set of lightweight APIs for parsing or processing XML documents. JAXP enables a web service to “plug in” any conforming XML parser. If no external parser is “plugged in,” then JAXP uses its own XML parser implementation.

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. Similarly, a JAX-RPC based client can interact with a non-Java-based web service implementation.

Java API for XML registries (JAXR), a Java API for accessing business registries, has a flexible architecture that supports UDDI, and other registry specifications (such as ebXML). A JAXR client, which can be a stand-alone Java application or a J2EE component, uses an implementation of the JAXR API provided by a JAXR provider to access business registries. A JAXR provider consists of two parts: a registry--specific JAXR provider, which provides a registry-specific implementation of the API, and a JAXR pluggable provider, which implements those features of the API that are independent of the type of registry. The pluggable provider hides the details of registry-specific providers from clients.

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:

Deploying and Testing Web Services

Enterprise Server enables you to easily deploy and test web services.

Deploying Web Services

Deploy a web service in an enterprise archive (EAR) just as you would an enterprise application.

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. Enterprise Server will automatically generate the appropriate web XML files and deploy the web service.

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

Viewing Deployed Web Services

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

Testing Web Services

Admin Console enables you to test web services and diagnose problems. You can ping a deployed web service with a generic test Servlet. SOAP messages are displayed for each method invocation.

To test a web service with Admin Console, select Applications > Web Services > web-service-name | General, then click the Test button.

Web Services Security

Support for SOAP message layer security is based on the SAML token profile of WS-Security. Tamper-proof auditing for Web services is also provided.

Using Web Services Registries

Note –

Enterprise 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 Registry

Add or remove a web services registry with Admin Console at Application Server > Web Services | Registry. Use this page to create a Registry Access Point (RAP). When you add a registry, specify the following paramters:

The registry JNDI Name is created as a result of the following steps:

Publishing a Web Service to a Registry

To publish a web service with Admin Console, select Applications > 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 for this web service. Enter the name of the organization, if you are publishing to a UDDI registry.

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 unpublish the web service, then click Unpublish.

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. All the XSLT files are stored in the generated/xml/appOrModule directory of the central repository. These transformation rules are synchronized to the remote server instances.

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

To add a transformation rule to apply to a web service operation with Admin Console, select Applications > Web Services > web-service-name | Transformation. Click Add.

A list of transformation rule available for this web service end point is displayed.

Browse to the location of the XSLT file that contains the transformation rule. All the generated XSLT files are stored in the generated/xml/application or module name/ directory.

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 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.

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. If this transformation rule is applied to a web service endpoint, it is automatically disabled. However, the XSLT file remains in the file path location. Other web service endpoints can use this XSLT file.

Monitoring Web Services

Admin console can track and graphically display 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 Applications > 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.

Viewing Web Service Statistics

Enterprise Serverv2.1.1 provides capabilities to track and graphically display the operational statistics of a web service.

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

Monitoring Web Service Messages

You can also configure a web service to view messages (default is 25) for a web service endpoint. These messages are stored in the memory of remote server instances. Details of SOAP request, response, and HTTP header information are displayed.

Monitor web service messages at Applications > Web Services > web-service-name | Monitor | Messages.

When enabled, you can see the last few (default is 25) messages for a web service end point. These messages are kept in memory of the remote server instances, including details of SOAP requests and responses and HTTP header information.

Displays a list of messages received for the web service. The number of messages displayed depends on the monitoring configuration.

You can also select a filter to view only the success messages or the failure messages.