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:
Track response times and invocation counts for web services in real time.
Generate alerts on boundary conditions including response time and throughput failures. For more information, see Chapter 17, Configuring Management Rules.
View web service invocation content in XML.
Transform messages at runtime using XSLT.
This chapter contains the following topics:
For information on securing web services, see Chapter 9, Configuring Message Security.
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.
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 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:
JAXB 2.0-based data binding.
Support for the latest W3C and WS-I standards such as SOAP 1.2 and WSDL 1.2.
Ease-of-development features using annotations.
An improved handler framework, support for asynchronous RPC and non-HTTP transports.
JSR 109 support.
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:
Synchronous request-response messaging: the client sends a message and then waits for the response.
One-way asynchronous messaging: the client sends a message and continues with its processing without waiting for a response.
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.
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.
In a web application, packaged as a web archive (WAR) file. Using Admin Console, go to Application Server > Applications > Web Applications, then click Deploy.
In an enterprise Java Bean (EJB), packaged as an EJB-JAR file. Using Admin Console, go to Application Server > Applications > EJB Modules, then click Deploy.
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.
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:
Name of the web service. Click on it to display details.
Application to which the web service belongs. Click on the name to display details of the web application or EJB module.
WSDL file for the web service. Click on the file name to display the contents of the file.
Type of the web service (SERVLET or EJB)
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:
Name: The name of the web service.
Endpoint Address URI: The URI of the web service endpoint.
Application: The name of the web service application. Click on the link to display the properties of the web application or EJB module.
WSDL: The name of the WSDL file. Click on the link to display the WSDL file for the web service.
Module name: the name of the WAR or JAR file for the web service.
Mapping File: The name of the mapping file. Click on the link to display the Java WSDL mapping file. This only applies to JSR 109 applications. The file will be empty for JAX-WS 2.0 applications.
Webservices.xml: Click on the link to display the webservices.xml file.
Implementation Type: SERVLET or EJB
Implementation Class Name: Java class implementing the web service.
Deployment Descriptors: For servlet implementations, displays web.xml and sun-web.xml; for EJB implementations, ejb-jar.xml and sun-ejb-jar.xml. Click on the links to display the files' contents.
You can also view deployed web services with the list-components(1) command with the --type webservice option.
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.
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
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.
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.
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.
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.
Download Java Web Services Developer Pack (JWSDP) 1.6: http://java.sun.com/webservices/downloads/1.6/index.html.
Install JWSDP 1.6 on your system.
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.
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.
Start the container.
This starts the installed registry by default. JWSDP 1.6 comes with the registry preconfigured.
Configure the resource adapter to work with Application Server, as described in the next section.
The result of this procedure will be to create a soar.rar resource adapter file that you can deploy to Application Server.
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.
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).
You can either download and execute a script, or perform the steps manually.
To use a script:
To perform the steps manually:
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 .
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
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 |
To use the jar command on Windows, you must have the JAVA_HOME\bin directory on your path.
Once you have created the soar.rar file, deploy it to create a registry as described in the next section.
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:
JNDI Name: the connection resource pool (JNDI) name of the registry. The JNDI Name of this connector resource is the JNDI Name of the registry.
Choose the type of the registry to add: UDDI 3.0 or ebXML.
Publish URL and Query URL: the addresses for publishing and querying the registry, respectively. The format is: http://hostname/path-to-registry—installation. For example, http://localhost:7080/soar/registry/soap.
User name and password for the registry (not required for ebXML; fields are disabled).
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:
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:
LOW: Monitors response time, throughput, total number of requests, faults, average response time, and response time for last request to the web service.
HIGH: In addition to the metrics monitored at LOW level, also monitors SOAP request and response messages.
OFF: Disables monitoring.
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.
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:
Response time in milliseconds on any successful or unsuccessful operation (maximum, minimum, and average).
Response time is the time the sever took to process the web service request, not including any network transmission time.
Throughput.
Total number of requests.
Total number of faults.
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:
Remote user name
Client host information
Timestamp
Response information (success or failure)
Size of the 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.
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:
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.