Sun GlassFish Enterprise Server 2.1 Developer's Guide

Chapter 6 Developing Web Services

This chapter describes Enterprise 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 Enterprise 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 14, Managing Web Services, in Sun GlassFish Enterprise Server 2.1 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 GlassFish Enterprise Server 2.1 Reference Manual.

Deploying a Web Service

You deploy a web service endpoint to the Enterprise 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 GlassFish Enterprise Server 2.1 Application Deployment Guide. For more information about the asadmin deploy command, see the Sun GlassFish Enterprise Server 2.1 Reference Manual.

Web Services Registry

You deploy a registry to the Enterprise 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 Enterprise Server in the as-install/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/index.jsp.

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 GlassFish Enterprise Server 2.1 Application Deployment Guide.

JBI Runtime

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.

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 distribution of the JBI runtime includes a Java EE service engine, an HTTP SOAP binding component, a WSDL shared library, and Ant tasks described in JBI Tasks. For information about JBI administration in the Enterprise Server, see the Sun GlassFish Enterprise Server 2.1 Administration Guide.

Additional components, tools, and documentation are available for download. Refer to Project Open ESB for more information on the additional components, tools, and documentation that are available.

The Java EE Service Engine acts as a bridge between the Java EE and JBI runtime environments for web service providers and web service consumers. The Java EE Service Engine provides better performance than a SOAP over HTTP binding component due to in-process communication between components and additional protocols provided by JBI binding components such as JMS, SMTP, and File.

The JSR 208 specification allows transactions to be propagated to other components using a message exchange property specified in the JTA_TRANSACTION_PROPERTY_NAME field. The Java EE Service Engine uses this property to set and get a transaction object from the JBI message exchange. It then uses the transaction object to take part in a transaction. This means a Java EE application or module can take part in a transaction started by a JBI application. Conversely, a JBI application can take part in a transaction started by a Java EE application or module.

Similarly, the JSR 208 specification allows a security subject to be propagated as a message exchange property named javax.jbi.security.subject. Thus a security subject can be propagated from a Java EE application or module to a JBI application or the reverse.

To deploy a Java EE application or module as a JBI service unit, use the Admin Console or the asadmin deploy-jbi-service-assembly command. For more information about the asadmin deploy-jbi-service-assembly command, see the Sun GlassFish Enterprise Server 2.1 Reference Manual.

Using the jbi.xml File

Section 6.3.1 of the JSR 208 specification describes the jbi.xml file. This is a deployment descriptor, located in the META-INF directory. To deploy a Java EE application or module as a JBI service unit, you need only specify a small subset of elements in the jbi.xml file. Here is an example provider:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi" xmlns:ns0="http://ejbws.jbi.misc/">
  <services binding-component="false">
    <provides endpoint-name="MiscPort" interface-name="ns0:Misc" service-name="ns0:MiscService"/>
  </services>
</jbi>

Here is an example consumer:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<jbi version="1.0" xmlns="http://java.sun.com/xml/ns/jbi" xmlns:ns0="http://message.hello.jbi/">
  <services binding-component="false">
    <consumes endpoint-name="MsgPort" interface-name="ns0:Msg" service-name="ns0:MsgService"/>
  </services>
</jbi>

The Java EE Service Engine enables the endpoints described in the provides section of the jbi.xml file in the JBI runtime. Similarly, the Java EE Service Engine routes invocations of the endpoints described in the consumes section from the Java EE web service consumer to the JBI runtime.

Using Application Server Descriptors

To determine whether a web service endpoint is enabled in the JBI runtime environment, you can set a jbi-enabled attribute in the Enterprise Server. This attribute is set to false (disabled) by default. To enable an endpoint for JBI, set the attribute to true 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=true

Determining whether requests from a web service consumer are routed through the Java EE Service Engine is unnecessary and deprecated, but supported for backward compatibility. 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 true (enabled) 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 GlassFish Enterprise Server 2.1 Application Deployment Guide.

Using the Woodstox Parser

The default XML parser in the Enterprise Server is the Sun GlassFish XML Parser (SJSXP). Using the Woodstox parser, which is bundled with the Enterprise Server, may improve performance. Woodstox and SJSXP both provide implementations of the StAX API. To enable the Woodstox parser, set the following system properties for the default server-config configuration in the domain.xml file, then restart the server:

<config name=server-config>
 ...
   <system-property name="javax.xml.stream.XMLEventFactory" 
      value="com.ctc.wstx.stax.WstxEventFactory"/>
   <system-property name="javax.xml.stream.XMLInputFactory" 
      value="com.ctc.wstx.stax.WstxInputFactory"/>
   <system-property name="javax.xml.stream.XMLOutputFactory" 
      value="com.ctc.wstx.stax.WstxOutputFactory"/>
</config>

In addition, set these properties for any other configurations referenced by server instances or clusters on which you want to use the Woodstox parser. For more information about the domain.xml file and system properties, see the Sun GlassFish Enterprise Server 2.1 Administration Reference.


Note –

If you are using a stand-alone client, you must set these same properties for the client on the java command line as follows:


-Djavax.xml.stream.XMLInputFactory=com.ctc.wstx.stax.WstxInputFactory
-Djavax.xml.stream.XMLOutputFactory=com.ctc.wstx.stax.WstxOutputFactory
-Djavax.xml.stream.XMLEventFactory=com.ctc.wstx.stax.WstxEventFactory

Setting these properties is not necessary if you are using an application client, which is recommended and supported.


For more information about the Woodstox parser, see http://woodstox.codehaus.org/. For more information about the StAX API, see Chapter 17: Streaming API for XML in the Java EE 5 Tutorial.