Samples

This document explains the samples that are bundled along with Eclipse Implementation of XML Web Services. The samples included with Eclipse Implementation of XML Web Services documents how to use Eclipse Implementation of XML Web Services in a non-Jakarta EE servlet container using a proprietary deployment descriptor sun-jaxws.xml and servlet com.sun.xml.ws.transport.http.servlet.WSServlet. This means that you can run these applications in any servlet container that has been enabled with Eclipse Implementation of XML Web Services. Applications that use the proprietary DD and servlet will run in a XML-WS enabled Jakarta EE servlet container, but they will be non-portable. If you wish to use these XML-WS samples in a Jakarta EE container in a Jakarta EE portable manner you need to modify them to use the standard Jakarta EE deployment descriptor; please refer to the Jakarta EE or Glassfish documentation/samples.

All these samples are tested to run on Glassfish 7.x and on Apache Tomcat 10.1.x.

1.0 Directory Structure

This section explains the directory structure of the samples directory in the bundle:
index.html this file
fromjava-wsaddressing Starting from Java endpoint how to develop W3C WS-Addressing endpoint
fromwsdl-wsaddressing Starting from WSDL how to develop a WS-Addressing endpoint
fromjava Demonstrates how to build, deploy, and invoke a simple Web service starting from a Java service endpoint implementation using annotations.
fromjavahandler Same as fromjava sample but with a simple logging handler on the client and server.
fromwsdl Demonstrates how to build, deploy, and invoke a simple Web service starting from a WSDL using external customizations.
fromwsdl_secure Same as fromwsdl sample but demonstrates how to build, deploy, and invoke an HTTPS Web service and client from a WSDL.
fromwsdlhandler Same as fromwsdl sample but with a simple logging handler on the client and server.
dispatch Demonstrates how to dynamically invoke web service endpoints.
provider Demonstrates how to build, deploy, and invoke jakarta.xml.ws.Provider based Web service endpoint.
asyncprovider Demonstrates how to build, deploy, and invoke a server side asynchronous Provider based Web service endpoint.
annotations Same as fromjava but shows how to specify a different parameter name, operation name, targetNamespace, and other similar features.
async Demonstrates how to generate async operations in a client SEI from a WSDL and invoke it from the client application.
external-customize Demonstrates how a client client application can customize a published WSDL using external binding file.
inline-customize Demonstrates how a client application and server endpoint can be generated from a WSDL with embedded binding declarations.
mtom Demonstrates how to enable MTOM and swaRef.
mtom-soap12 Same as mtom sample but shows how to specify SOAP 1.2 binding.
fromjava-soap12 Same as fromjava sample but shows how to specify SOAP 1.2 binding.
fromwsdl-soap12 Same as fromwsdl sample but shows how to specify SOAP 1.2 binding.
supplychain Same as fromjava sample but using JavaBeans as parameter and return types.
Also the service can be built and deployed using Endpoint API.
mime Demonstrates how a MIME binding is defined in the WSDL to send wsdl:part as MIME attachments. This requires that the development model is 'starting from WSDL'.
wsimport_catalog Demonstrates a how a WSDL and schema URI's can be resolved using catalog mechanism using wsimport ant tasks' catalog attribute and also using ant's core type xmlcatalog.
catalog Shows the catalog capability on the client side; Catalog is used every time the implementation tries to access a resource identified by URI that is believed to contain either a WSDL document or any other document on which it depends .
restful Shows an example of a REST Web Service implemented as a XML-WS Provider and accessed via a XML-WS Dispatch client. The Request uses an HTTP GET Request Method and uses the XML-WS MessageContext properties PATH_INFO and QUERY_STRING.
stateful This sample shows the stateful webservice support feature.

2.0 Prerequisites

Here is the list of prerequisites that needs to be met before any of the samples can be invoked:

  1. Download Java SE 11 or later. Set JAVA_HOME to the Java SE installation directory.

  2. Download GlassFish 7 or later application server and install it.

  3. Make sure that the Application Server is configured for port 8080 (which is the default HTTP port for a Glassfish installation) as samples hard-coded with this port info. Should you want to use different port instead, you need to manually update samples to use the correct port.

  4. Set up the environment,

    1. Set AS_HOME to point to the Application Server installation directory.

    2. Set JAXWS_HOME to the XML-WS installation directory.

  5. GlassFish integrates Eclipse Implementation of XML Web Services. So you may just start using it and skip step 6 below.

  6. If you have installed a standalone Eclipse Implementation of XML Web Services bundle,

    1. refer to the readme.html in $JAXWS_HOME for information how to install standalone XML-WS on an application server or a servlet container.

3.0 Invoking the sample

Each sample can be built, deployed and invoked using the $ANT_HOME/bin/ant and build.xml ant script in the root directory of the sample. Each ant script supports the following set of targets:
server Builds and deploy the service endpoint WAR
client Builds the client
run Runs the client


Some samples(e.g. fromjava, supplychain) can be built, deployed using jakarta.xml.ws.Endpoint API. These samples support extra targets:
server-j2se Builds and deploys the Endpoint API based service endpoint(doesn't terminate until server-j2se-stop is called)
server-j2se-stop Stops the Endpoint API based service endpoint (need to run from a different window)


It is essential for the service endpoint to be deployed on Application Server before clients can be built because clients use the WSDL exposed from the service endpoint deployed in the Application Server. So please make sure that your Application Server is either running before the server target is invoked or run it after the server target is invoked. You will have to wait a few minutes for the Application Server to deploy the service endpoint correctly before building the client.

Running Samples with Tomcat:

  1. Set CATALINA_HOME to your Tomcat installation.

  2. Make sure that the Tomcat is configured for port 8080 as samples hard-coded with this port info. Should you want to use different port instead, you need to manually update samples to use the correct port.

  3. If you have installed a standalone Eclipse Implementation of XML Web Services bundle,

    1. refer to the readme.html in $JAXWS_HOME for information how to install standalone XML-WS on an application server or a servlet container.

  4. Make sure the Tomcat container is up and running before running sample.

  5. While running the ant targets in samples, specify “-Dtomcat=true”. For example:

ant clean server -Dtomcat=true, this will build the service and deploy the war to /webapps.

ant clean client, this would create client-side artifacts and compiles the files.

ant run

We appreciate your feedback, please send it to metro-dev@eclipse.org.