type=page status=published title=Developing Web Services next=jpa.html prev=securing-apps.html ~~
This chapter describes {productName} support for web services. The following topics are addressed here:
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
In addition, the as-install |
"Web Services" in The Jakarta EE Tutorial shows how to deploy simple web services to {productName}.
For additional information about JAXB (Java Architecture for XML Binding), see Java Specification Request (JSR) 222 and The Databinding Provider.
For additional information about JAX-WS (Java API for XML-Based Web Services), see Java Specification Request (JSR) 224 and Java Specification Request (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 more information about using Fast Infoset, see the Metro WSIT Guide
For a tutorial that shows how to use the wsimport
and wsgen
commands, see "
Web Services" in The Jakarta EE Tutorial.
You deploy a web service endpoint to the {productName} 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 {productName} 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
{productName} Application Deployment Guide.
For more information about the
asadmin deploy
command, see the
{productName} Reference Manual.
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.
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 {productName}
Application Deployment Guide.
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 Jakarta EE APIs.
The EclipseLink JAXB implementation, plus EclipseLink extensions, is
called MOXy. The org.eclipse.persistence.moxy.jar
file is bundled with
{productName}, 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 duringWebServiceFeature
initialization or using theadd
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 jakarta.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 jakarta.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 theendpoint
element in thesun-jaxws.xml
file. Allowed values areglassfish.jaxb
oreclipselink.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
{productName}. 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
{productName} 7 provides the GlassFish Jakarta EE Service Engine, a JSR 208 compliant Java Business Integration (JBI) runtime component that connects Jakarta EE web services to JBI components. The Jakarta EE Service Engine is installed as an add-on component using the Update Tool. Look for the JBI component named Jakarta EE Service Engine. A JBI runtime is not installed with or integrated into {productName} 7 and must be obtained separately. For more information about using the Update Tool to obtain the Jakarta EE Service Engine and other add-on components, see "Update Tool" in {productName} Administration Guide.
The Jakarta EE Service Engine acts as a bridge between the Jakarta EE and JBI runtime environments for web service providers and web service consumers. The Jakarta 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
(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 Jakarta 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 Jakarta 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 Jakarta 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 Jakarta EE application or module to a JBI application or the
reverse.
To deploy a Jakarta 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
{productName} Reference Manual.
For more information about autodeployment, see
"
To Deploy an Application or Module Automatically"
in {productName} Application Deployment Guide.
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 Jakarta 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 Jakarta EE Service Engine enables the endpoints described in the
provides
section of the jbi.xml
file in the JBI runtime. Similarly,
the Jakarta EE Service Engine routes invocations of the endpoints described
in the consumes
section from the Jakarta EE web service consumer to the
JBI runtime.