test

Sun Java System Application Server Platform Edition 9 Developer's Guide

Chapter 6 Developing Web Services

This chapter describes Application Server support for web services. JavaTM API for XML-Based Web Services (JAX-WS) version 2.0 is supported. Java API for XML-Based Remote Procedure Calls (JAX-RPC) version 1.1 is supported for backward compatibility. This chapter contains the following sections:

“Part Two: Web Services” in the Java EE 5 Tutorial shows how to deploy simple web services to the Application Server. “Chapter 20: Java API for XML Registries” explains how to set up a registry and create clients that access the registry.

For additional information about JAX-WS and web services, see Java Specification Request (JSR) 224 and JSR 109.

For information about web services security, see Configuring Message Security for Web Services.

For information about web services administration, monitoring, logging, and registries, see Chapter 12, Managing Web Services, in Sun Java System Application Server Platform Edition 9 Administration Guide.

The Fast Infoset standard specifies a binary format based on the XML Information Set. This format is an efficient alternative to XML. For information about using Fast Infoset, see the following links:

Creating Portable Web Service Artifacts

For a tutorial that shows how to use the wsimport and wsgen commands, see “Part Two: Web Services” in the Java EE 5 Tutorial. For reference information on these commands, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Deploying a Web Service

You deploy a web service endpoint to the Application Server just as you would any servlet, stateless session bean (SLSB), or application. After you deploy the web service, the next step is to publish it. For more information about publishing a web service, see Web Services Registry.

You can use the autodeployment feature to deploy a simple JSR 181 annotated file. You can compile and deploy in one step, as in the following example:


javac -cp javaee.jar -d domain-dir/autodeploy MyWSDemo.java
Note –

For complex services with dependent classes, user specified WSDL files, or other advanced features, autodeployment of an annotated file is not sufficient.

The Sun-specific deployment descriptor files sun-web.xml and sun-ejb-jar.xml provide optional web service enhancements in their webservice-endpoint and webservice-description elements, including a debugging-enabled subelement that enables the creation of a test page. The test page feature is enabled by default and described in The Web Service URI, WSDL File, and Test Page.

For more information about deployment, autodeployment, and deployment descriptors, see the Sun Java System Application Server Platform Edition 9 Application Deployment Guide. For more information about the asadmin deploy command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Web Services Registry

You deploy a registry to the Application Server just as you would any connector module, except that if you are using the Admin Console, you must select a Registry Type value. After deployment, you can configure a registry in one of the following ways:

After you deploy a web service, you can publish it to a registry in one of the following ways:

The Sun Java Enterprise System (Java ES) includes a Sun-specific ebXML registry. For more information about the Java ES registry and registries in general, see “Chapter 20: Java API for XML Registries” in the Java EE 5 Tutorial.

A connector module that accesses UDDI registries is provided with the Application Server in the install-dir/lib/install/applications/jaxr-ra directory.

You can also use the JWSDP registry available at http://java.sun.com/webservices/jwsdp/index.jsp or the SOA registry available at http://www.sun.com/products/soa/registry/index.html.

The Web Service URI, WSDL File, and Test Page

Clients can run a deployed web service by accessing its service endpoint address URI, which has the following format:


http://host:port/context-root/servlet-mapping-url-pattern

The context-root is defined in the application.xml or web.xml file, and can be overridden in the sun-application.xml or sun-web.xml file. The servlet-mapping-url-pattern is defined in the web.xml file.

In the following example, the context-root is my-ws and the servlet-mapping-url-pattern is /simple:


http://localhost:8080/my-ws/simple

You can view the WSDL file of the deployed service in a browser by adding ?WSDL to the end of the URI. For example:


http://localhost:8080/my-ws/simple?WSDL

For debugging, you can run a test page for the deployed service in a browser by adding ?Tester to the end of the URL. For example:


http://localhost:8080/my-ws/simple?Tester

You can also test a service using the Admin Console. Open the Web Services component, select the web service in the listing on the General tab, and select Test. For details, click the Help button in the Admin Console.

Note –

The test page works only for WS-I compliant web services. This means that the tester servlet does not work for services with WSDL files that use RPC/encoded binding.

Generation of the test page is enabled by default. You can disable the test page for a web service by setting the value of the debugging-enabled element in the sun-web.xml and sun-ejb-jar.xml deployment descriptor to false. For more information, see the Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

JBI Runtime with BPEL Support

The Java Business Integration runtime (JBI runtime) provides a distributed infrastructure used for enterprise integration. It consists of a set of binding components and service engines, which integrate various types of information technology assets. The binding components and service engines are interconnected with a normalized message router. Binding components and service engines adapt information technology assets to a standard services model, based on XML message exchange using standardized message exchange patterns. The JBI runtime provides services for transforming and routing messages, as well as the ability to centrally administer the distributed system.

The JBI Runtime with Business Process Execution Language (BPEL) Support is provided by the Project Open Enterprise Service Bus (ESB) Starter Kit. This JBI runtime incorporates the JSR 208 specification for JBI and other open standards. The JBI runtime allows you to integrate web services and enterprise applications as loosely coupled composite applications within a Service-Oriented Architecture (SOA).

The JBI runtime is available from the Java EE 5 SDK Update 1 and the Java Application Platform SDK distributions. In the Application Server bundled with the Java EE 5 SDK, the JBI runtime is installed but disabled by default. In the Application Server bundled with the Java Application Platform SDK, the JBI runtime is installed and enabled by default. The JBI runtime is also available as a separate download that can be installed into the stand-alone Application Server.

The distribution of the JBI runtime includes a BPEL service engine, a Java EE service engine, an HTTP SOAP binding component, and a getting started tutorial. Additional components, tools, and documentation are available for download. Refer to Project Open ESB Starter Kit for more information on the additional components, tools, and documentation that are available.

To enable the JBI runtime in the Application Server, use the following asadmin enable command, then restart the server:


asadmin enable --user adminuser JBIFramework

To disable the JBI runtime, use the equivalent asadmin disable command.

When you install the JBI runtime, the Java EE Service Engine is automatically installed on the Application Server. The Java EE Service Engine acts as a bridge between the Application Server and the JBI runtime environment for web service providers and web service consumers. The Java EE Service Engine provides better performance than the default SOAP over HTTP socket connection due to in-process communication between components and additional protocols such as JMS.

The Java EE Service Engine is enabled by default. To disable it without uninstalling it, set the com.sun.enterprise.jbi.se.disable JVM option to true using the asadmin create-jvm-options command as follows, then restart the server:


asadmin create-jvm-options --user adminuser -Dcom.sun.enterprise.jbi.se.disable=true

For more information about the asadmin create-jvm-options command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

To determine whether a web service endpoint is enabled in the JBI runtime environment, you can set a jbi-enabled attribute in the Application Server. This attribute is set to true (enabled) by default. To disable an endpoint for JBI, set the attribute to false using the asadmin set command. For example, if an endpoint is bundled as a WAR file named my-ws.war with an endpoint named simple, use the following command:


asadmin set --user adminuser 
server.applications.web-module.my-ws.web-service-endpoint.simple.jbi-enabled=false

To determine whether requests from a web service consumer are routed through the Java EE Service Engine, you can set a stub-property named jbi-enabled in the consumer's sun-web.xml or sun-ejb-jar.xml file. This property is set to false (disabled) by default. Here is an example of the sun-web.xml file:

<sun-web-app>
  <service-ref>
    <service-ref-name>sun-web.serviceref/calculator</service-ref-name>
    <port-info>
      <wsdl-port>
        <namespaceURI>http://example.web.service/Calculator</namespaceURI>
        <localpart>CalculatorPort</localpart>
      </wsdl-port>
      <service-endpoint-interface>service.web.example.calculator.Calculator</service-endpoint-interface>
      <stub-property name="jbi-enabled" value="true"/>
    </port-info>
  </service-ref>
</sun-web-app>

For more information about the sun-web.xml and sun-ejb-jar.xml deployment descriptor files, see the Sun Java System Application Server Platform Edition 9 Application Deployment Guide.