5 Developing Web Services

Creating Portable Web Service Artifacts

For a tutorial that shows how to use the wsimport and wsgen commands, see "Web Services" in The Java EE 6 Tutorial.

Deploying a Web Service

You deploy a web service endpoint to the GlassFish Server just as you would any servlet, stateless session bean (SLSB), or application.

The GlassFish Server deployment descriptor files glassfish-web.xml and glassfish-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 Oracle GlassFish Server Application Deployment Guide. For more information about the asadmin deploy command, see the Oracle GlassFish Server 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 glassfish-application.xml or glassfish-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.

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 glassfish-web.xml and glassfish-ejb-jar.xml deployment descriptor to false. For more information, see the Oracle GlassFish Server Application Deployment Guide.

The Databinding Provider

The JAX-WS reference implementation (RI) used to be dependent on the JAXB RI for databinding. JAXB and JAX-WS implementations have been decoupled, and databinding is modular.

The EclipseLink JAXB implementation, plus EclipseLink extensions, is called MOXy. The org.eclipse.persistence.moxy.jar file is bundled with GlassFish Server, which supports the JAXB RI and MOXy as databinding providers.

To specify the databinding provider for the JVM, set the com.sun.xml.ws.spi.db.BindingContextFactory JVM property to one of the following values:

com.sun.xml.ws.db.glassfish.JAXBRIContextFactory

Specifies the JAXB reference implementation. This is the default.

com.sun.xml.ws.db.toplink.JAXBContextFactory

Specifies Eclipselink MOXy JAXB binding.

For example:

asadmin create-jvm-options -Dcom.sun.xml.ws.spi.db.BindingContextFactory=com.sun.xml.ws.db.toplink.JAXBContextFactory

To specify the databinding provider for a web service endpoint:

• Set the org.jvnet.ws.databinding.DatabindingModeFeature feature during WebServiceFeature initialization or using the add method. Allowed values are as follows:

  org.jvnet.ws.databinding.DatabindingModeFeature.GLASSFISH_JAXB

  Specifies the JAXB reference implementation. This is the default.

  com.sun.xml.ws.db.toplink.JAXBContextFactory.ECLIPSELINK_JAXB

  Specifies Eclipselink MOXy JAXB binding.

  For example:

  import javax.xml.ws.WebServiceFeature;
  import org.jvnet.ws.databinding.DatabindingModeFeature;
  import com.sun.xml.ws.db.toplink.JAXBContextFactory;
  ...
  WebServiceFeature[] features = {new DatabindingModeFeature(JAXBContextFactory.ECLIPSELINK_JAXB)};
  ...
  

• Set the org.jvnet.ws.databinding.DatabindingModeFeature feature using the @DatabindingMode annotation. For example:

  import javax.jws.WebService;
  import org.jvnet.ws.databinding.DatabindingMode;
  import com.sun.xml.ws.db.toplink.JAXBContextFactory;
  ...
  @WebService()
  @DatabindingMode(JAXBContextFactory.ECLIPSELINK_JAXB);
  ...
  

• Set the databinding attribute of the endpoint element in the sun-jaxws.xml file. Allowed values are glassfish.jaxb or eclipselink.jaxb. For example:

  <endpoint
  name='hello'
  implementation='hello.HelloImpl'
  url-pattern='/hello'
  databinding='eclipselink.jaxb'/>
  

The EclipseLink JAXB compiler is not included but can be used with GlassFish Server. Download the EclipseLink zip file at http://www.eclipse.org/eclipselink/downloads/ and unzip it. The compiler files are located here:

bin/jaxb-compiler.cmd
bin/jaxb-compiler.sh

GlassFish Java EE Service Engine

GlassFish Server 3.1.2 provides the GlassFish 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 GlassFish Server 3.1.2 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 Oracle GlassFish Server 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 Oracle GlassFish Server Reference Manual. For more information about autodeployment, see "To Deploy an Application or Module Automatically" in Oracle GlassFish Server Application Deployment Guide.

<?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>

<?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>