Chapter 8.  Create a SOAP based web service using Java SE platform.

8.1.  Create a web service starting from a WSDL file using JAX-WS.

8.1.1.  Use wsimport tool to generate artifacts and use customization files for wsimports if needed.

The wsimport command-line tool processes an existing Web Services Description Language (WSDL) file and generates the required portable artifacts for developing Java API for XML-Based Web Services (JAX-WS) web service applications.

The wsimport command-line tool supports the top-down approach to developing JAX-WS web services. When you start with an existing WSDL file, use the wsimport command-line tool to generate the required JAX-WS portable artifacts.

The wsimport tool reads an existing WSDL file and generates the following portable artifacts:

  • Service Endpoint Interface (SEI) - The SEI is the annotated Java representation of the WSDL file for the web service. This interface is used for implementing JavaBeans endpoints or creating dynamic proxy client instances.

  • extension class - This is a generated class that extends the class. This class is used to configure and create both dynamic proxy and dispatch instances.

  • Java Architecture for XML Binding (JAXB) beans that are required to model the web service data.

  • Exception class mapped from wsdl:fault (if any).

  • Async Reponse Bean derived from response wsdl:message (if any).


wsimport [options] <wsdl>


  • -d directory

    Specify where to place generated output files.

  • -b path

    Specifies the external JAX-WS or JAXB binding files. You can specify multiple JAX-WS and JAXB binding files by using the -b option; however, each file must be specified with its own -b option.

  • -keep

    Keep generated files.

  • -p

    Specifying a target package via this command-line option, overrides any wsdl and schema binding customization for package name and the default package name algorithm defined in the specification.

  • -s directory

    Specify where to place generated source files.

  • -wsdllocation location

    The wsdl URI passed thru this option will be used to set the value of @WebService.wsdlLocation and @WebServiceClient.wsdlLocation annotation elements on the generated SEI and Service interface.

Multiple JAX-WS and JAXB binding files can be specified using -b option and they can be used to customize various things like package names, bean names, etc.


This command generates JAX-WS portable artifacts for in to the generated directory:

wsimport -d generated

This command generates JAX-WS artifacts for stock.wsdl and uses the customization files stock.xml (JAX-WS customization file) and stock.xjb (JAXB customization file) in the process:

wsimport stock.wsdl -b stock.xml -b stock.xjb

8.1.2.  Build the web service implementation using the above artifacts.

For SOAP-based services, the WSDL represents the contract. This model has a single overarching paradigm: the WSDL defines the primary features of the contract for the service, and implementation-independent contracts are one of the cornerstone necessities of SOA. The contract is not an afterthought, but rather a central concern. With this model, you write the WSDL yourself by hand, generate a Java code shell for the service implementation, and then fill in the business logic for the service implementation. This method is also sometimes referred to as "Contract First."

You start by taking a preexisting abstract WSDL and pointing it to a tool such as wsimport that produces a service endpoint interface in addition to Java classes that represent the schema definitions and message parts specified in the WSDL. Once the endpoint interface has been generated, write a Java class that implements that interface. The basic steps are as follows:

  1. Write a WSDL representing the service you want to deploy.

  2. Generate client-side code using wsimport. Among other things, this will generate a service interface for each portType.

  3. Implement each interface by writing your web service implementation class. That means doing something like this:

    public class MyService implements MyGeneratedInterface {

  4. Deploy the service endpoint implementation to a JAX-WS-compatible container.

In this example, the endpoint interface is specified as a fully qualified name of the interface that wsimport generated, written as a string. The WSDL location property allows you to specify either a relative or an absolute URI. If relative, it must be in META-INF/wsdl.

On a practical level, your organization might benefit from having a published WSDL released early in the project, so that client- and server-side development teams can work independently.

Another key benefit to starting from WSDL is that XML schema affords a far richer set of data types than many programming languages. Starting from WSDL, you can offer a set of type options, maximizing interoperability.

8.1.3.  Use Endpoint API to configure and deploy it in Java SE 6 platform.

The Endpoint class can be used to create and publish web service endpoints.

An endpoint consists of an object that acts as the web service implementation (called here implementor) plus some configuration information, e.g. a Binding. Implementor and binding are set when the endpoint is created and cannot be modified later. Their values can be retrieved using the getImplementor and getBinding methods respectively. Other configuration information may be set at any time after the creation of an Endpoint but before its publication.

Endpoints can be created using the following static methods on Endpoint:

  • create(Object implementor)

    Creates and returns an Endpoint for the specified implementor. If the implementor specifies a binding using the annotation it MUST be used else a default binding of SOAP 1.1 / HTTP binding MUST be used.

    Endpoint endpoint = Endpoint.create(new ExamplePort());

  • create(Object implementor, WebServiceFeature... features)

    Same as the above create() method. The created Endpoint is configured with the web service features. These features override the corresponding features that are specified in WSDL, if present.

  • create(String bindingID, Object implementor)

    Creates and returns an Endpoint for the specified binding and implementor. If the bindingID is null and no binding information is specified via the annotation then a default SOAP 1.1 / HTTP binding MUST be used.

  • create(String bindingID, Object implementor, WebServiceFeature... features)

    Same as the above create() method. The created Endpoint is configured with the web service features. These features override the corresponding features that are specified in WSDL, if present.

  • publish(String address, Object implementor)

    Creates and publishes an Endpoint for the given implementor. The binding is chosen by default based on the URL scheme of the provided address (which must be a URL). If a suitable binding if found, the endpoint is created then published as if the Endpoint.publish(String address) method had been called. The created Endpoint is then returned as the value of the method.

    The following code provides an example of its use:

    // assume Test is an endpoint implementation class annotated with @WebService
    Test test = new Test();
    Endpoint e = Endpoint.publish("http://localhost:8080/test", test);

  • publish(String address, Object implementor, WebServiceFeature... features)

    Same as the above publish() method. The created Endpoint is configured with the web service features. These features override the corresponding features that are specified in WSDL, if present.

An Endpoint is in one of three states: not published (the default), published or stopped. Published endpoints are active and capable of receiving incoming requests and dispatching them to their implementor. Non published endpoints are inactive. Stopped endpoint were in the published until some time ago, then got stopped. Stopped endpoints cannot be published again. Publication of an Endpoint can be achieved by invoking one of the following methods:

  • publish(String address)

    Publishes the endpoint at the specified address (a URL). The address MUST use a URL scheme compatible with the endpoint's binding.

  • publish(Object serverContext)

    Publishes the endpoint using the specified server context. The server context MUST contain address information for the resulting endpoint and it MUST be compatible with the endpoint's binding.

    The following example shows the use of the publish(Object) method using a hypothetical HTTP server API that includes the HttpServer and HttpContext classes:

    // assume Test is an endpoint implementation class annotated with @WebService
    Test test = new Test();
    HttpServer server = HttpServer.create(new InetSocketAddress(8080), 10);
    HttpContext context = server.createContext("/test");
    Endpoint endpoint = Endpoint.create(SOAPBinding.SOAP11HTTP_BINDING, test);

Professional hosting         'Oracle Certified Expert Web Services Developer 6' Quiz     Free SCDJWS 5.0 Guide