Chapter 5 Developing Web Services

This chapter describes Enterprise Server support for web services. Java^TM API for XML-Based Web Services (JAX-WS) version 2.0 is supported. This chapter contains the following sections:

• Deploying a Web Service

• Web Services Registry

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

For GlassFish v3 Prelude, web services are not supported unless the optional Metro (JSR 109) add-on component is downloaded from the Update Tool. Without the Metro add-on component, a servlet cannot be a web service endpoint, and the sun-web.xml elements related to web services are ignored. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

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

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

Deploying a Web Service

You deploy a web service endpoint to the Enterprise Server just as you would any servlet. 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 webservices.jar -d domain-dir/autodeploy MyWSDemo.java

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

Web Services Registry

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

• In the Administration Console, open the Web Services component, and select the Registry tab. For details, click the Help button in the Administration Console.

• To configure a registry using the command line, use the following commands.

  • Set the registry type to com.sun.appserv.registry.ebxml or com.sun.appserv.registry.uddi. Use a backslash before each period as an escape character. For example:

    asadmin create-resource-adapter-config --user adminuser --property com\.sun\.appserv\.registry\.ebxml=true MyReg

  • Set any properties needed by the registry. For an ebXML registry, set the LifeCycleManagerURL and QueryManagerURL properties. In the following example, the system property REG_URL is set to http\\:\\/\\/siroe.com\\:6789\\/soar\\/registry\\/soap.

    asadmin create-connector-connection-pool --user adminuser --raname MyReg --connectiondefinition javax.xml.registry.ConnectionFactory --property LifeCycleManagerURL=${REG_URL}:QueryManagerURL=${REG_URL} MyRegCP

  • Set a JNDI name for the registry resource. For example:

    asadmin create-connector-resource --user adminuser --poolname MyRegCP jndi-MyReg

  For details on these commands, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

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

• In the Administration Console, open the Web Services component, select the web service in the listing on the General tab, and select the Publish tab. For details, click the Help button in the Administration Console.

• Use the asadmin publish-to-registry command. For example:

  asadmin publish-to-registry --user adminuser --registryjndinames jndi-MyReg --webservicename my-ws#simple

  For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.

For more information about registries, see “Chapter 20: Java API for XML Registries” in the Java EE 5 Tutorial.

A 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 SOA registry available at http://www.sun.com/products/soa/index.jsp.

For further information, see https://metro.dev.java.net/.

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 web.xml file, and can be overridden in the 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 Prelude Application Deployment Guide.