Chapter 6 Developing Web Services

This chapter describes Sun GlassFish^TM Enterprise Server support for web services. Java^TM API for XML-Based Web Services (JAX-WS) version 2.2 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:

• Creating Portable Web Service Artifacts

• Deploying a Web Service

• The Web Service URI, WSDL File, and Test Page

• Sun Java EE Engine

If you installed the Web Profile, web services are not supported unless the optional Metro Web Services Stack add-on component is downloaded from the Update Tool. Without the Metro add-on component, a servlet or EJB component cannot be a web service endpoint, and the sun-web.xml and sun-ejb-jar.xml elements related to web services are ignored. For information about the Update Tool, see Update Tool in Sun GlassFish Enterprise Server v3 Administration Guide.

Part III, Web Services, in The Java EE 6 Tutorial, Volume I shows how to deploy simple web services to the Enterprise Server.

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.

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:

• Java Web Services Developer Pack 1.6 Release Notes

• Fast Infoset in Java Web Services Developer Pack, Version 1.6

• Fast Infoset Project

Creating Portable Web Service Artifacts

For a tutorial that shows how to use the wsimport and wsgen commands, see Part III, Web Services, in The Java EE 6 Tutorial, Volume I. For reference information on these commands, see the Sun GlassFish Enterprise Server v3 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.

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 the 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 v3 Application Deployment Guide. For more information about the asadmin deploy command, see the Sun GlassFish Enterprise Server v3 Reference Manual.

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

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 v3 Application Deployment Guide.

Sun Java EE Engine

Enterprise Server v3 provides the Sun Java EE Engine (Java EE Service Engine), a JSR 208 compliant Java Business Integration (JBI) runtime component that connects Java EE web services to JBI components. The Java EE Service Engine is installed as an add-on component using the Update Tool. Look for the JBI component named Java EE Service Engine. A JBI runtime is not installed with or integrated into Enterprise Server v3 and must be obtained separately. For more information about using the Update Tool to obtain the Java EE Service Engine and other add-on components, see Update Tool in Sun GlassFish Enterprise Server v3 Administration Guide.

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 asadmin deploy command, or autodeployment. For more information about the asadmin deploy command, see the Sun GlassFish Enterprise Server v3 Reference Manual. For more information about autodeployment, see To Deploy an Application or Module Automatically in Sun GlassFish Enterprise Server v3 Application Deployment Guide.

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.