type=page
status=published
title=Developing Web Services
next=jpa.html
prev=securing-apps.html
~~~~~~
Developing Web Services
=======================

[[GSDVG00007]][[gaszn]]


[[developing-web-services]]
5 Developing Web Services
-------------------------

This chapter describes Oracle GlassFish Server support for web services.
The following topics are addressed here:

* link:#gbizi[Creating Portable Web Service Artifacts]
* link:#gbixz[Deploying a Web Service]
* link:#gbiyw[The Web Service URI, WSDL File, and Test Page]
* link:#CHDEBBCH[The Databinding Provider]
* link:#gcgzz[GlassFish Java EE Service Engine]


[NOTE]
=======================================================================

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
`glassfish-web.xml` and `glassfish-ejb-jar.xml` elements related to web
services are ignored. For information about the Update Tool, see
"olink:GSADG00701[Update Tool]" in GlassFish Server Open Source Edition
Administration Guide.

In addition, the as-install`/modules/webservices-osgi.jar` and
as-install`/modules/endorsed/webservices-api-osgi.jar` files must be in
the classpath of your web services application. IDEs such as NetBeans
and Eclipse do this automatically.

=======================================================================


"https://javaee.github.io/tutorial/partwebsvcs.html[Web Services]" in
The Java EE 8 Tutorial shows how to deploy simple web services to
GlassFish Server.

For additional information about JAXB (Java Architecture for XML
Binding), see
http://jcp.org/aboutJava/communityprocess/pfd/jsr222/index.html[Java
Specification Request (JSR) 222] and link:#CHDEBBCH[The Databinding
Provider].

For additional information about JAX-WS (Java API for XML-Based Web
Services), see
http://jcp.org/aboutJava/communityprocess/pfd/jsr224/index.html[Java
Specification Request (JSR) 224] and
http://jcp.org/en/jsr/detail?id=109[Java Specification Request (JSR)
109].

For information about web services security, see
link:securing-apps.html#beaca[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:

* http://download.oracle.com/docs/cd/E17802_01/webservices/webservices/docs/1.6/ReleaseNotes.html[Java
Web Services Developer Pack 1.6 Release Notes]
* http://download.oracle.com/docs/cd/E17802_01/webservices/webservices/docs/1.6/jaxrpc/fastinfoset/manual.html[Fast
Infoset in Java Web Services Developer Pack, Version 1.6]
* https://javaee.github.io/metro-fi/[Fast Infoset Project]
(`https://javaee.github.io/metro-fi/`

[[gbizi]][[GSDVG00126]][[creating-portable-web-service-artifacts]]

Creating Portable Web Service Artifacts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a tutorial that shows how to use the `wsimport` and `wsgen`
commands, see "https://javaee.github.io/tutorial/partwebsvcs.html[Web
Services]" in The Java EE 8 Tutorial.

[[gbixz]][[GSDVG00127]][[deploying-a-web-service]]

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.


[NOTE]
=======================================================================

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

=======================================================================


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
link:#gbiyw[The Web Service URI, WSDL File, and Test Page].

For more information about deployment, autodeployment, and deployment
descriptors, see the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server Open Source Edition
Application Deployment Guide]. For more information about the
`asadmin deploy` command, see the link:../reference-manual/toc.html#GSRFM[GlassFish Server Open
Source Edition Reference Manual].

[[gbiyw]][[GSDVG00128]][[the-web-service-uri-wsdl-file-and-test-page]]

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:

[source,oac_no_warn]
----
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`:

[source,oac_no_warn]
----
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:

[source,oac_no_warn]
----
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:

[source,oac_no_warn]
----
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.


[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 `glassfish-web.xml` and
`glassfish-ejb-jar.xml` deployment descriptor to `false`. For more
information, see the link:../application-deployment-guide/toc.html#GSDPG[GlassFish Server Open Source Edition
Application Deployment Guide].

[[CHDEBBCH]][[GSDVG536]][[the-databinding-provider]]

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. JAXB and JAX-WS are no longer
Java EE APIs.

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:

[source,oac_no_warn]
----
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: +
[source,oac_no_warn]
----
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: +
[source,oac_no_warn]
----
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: +
[source,oac_no_warn]
----
<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:

[source,oac_no_warn]
----
bin/jaxb-compiler.cmd
bin/jaxb-compiler.sh
----

[[gcgzz]][[GSDVG00129]][[glassfish-java-ee-service-engine]]

GlassFish Java EE Service Engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

GlassFish Server 5.0 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 5.0 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
"link:../administration-guide/toc.html#GSADG00701[Update Tool]" in GlassFish Server Open Source Edition
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 http://jcp.org/en/jsr/detail?id=208[JSR 208]
(`http://jcp.org/en/jsr/detail?id=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 link:../reference-manual/toc.html#GSRFM[GlassFish Server Open
Source Edition Reference Manual]. For more information about
autodeployment, see "link:../application-deployment-guide/deploying-applications.html#GSDPG00041[To Deploy an Application or Module
Automatically]" in GlassFish Server Open Source Edition Application
Deployment Guide.

[[gelxr]][[GSDVG00387]][[using-the-jbi.xml-file]]

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:

[source,oac_no_warn]
----
<?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:

[source,oac_no_warn]
----
<?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.