JAX-WS Services Integration

Introduction

This whitepaper captures the current thinking within the Open Service Oriented Architecture (OSOA) collaboration on SCA-enabling a JAX-WS runtime. This whitepaper may be updated or become obsolete by other documents in the future. This whitepaper should be cited only as work in progress.

The Java API for XML Based Web Services (JAX-WS) 2.0 was developed by the Java Specification Request (JSR) 224 group as an update to the Java API for XML-Based RPC (JAX-RPC) specification. The name was changed from JAX-RPC to JAX-WS because of the extent of the new features added, such as support for asynchronous messaging, non-HTTP transports, and the Java Architecture for XML Binding (JAXB). JAX-WS therefore represents the most recent evolution of the standard set of Java APIs for Web services and a popular choice for the creation of Java-based Web service providers and Web service consumers.

SCA complements JAX-WS and other Web Service creation approaches by standardizing service assemblies, which contains information about service components, their dependencies and their deployment into various runtimes. A JAX-WS compliant runtime is one of the runtimes which SCA supports, primarily through the addition of assembly metadata to programming language artifacts. Just as with other supported runtimes, the SCA assembly metadata describes how JAX-WS compliant components combine with other components to provide and to consume service interfaces within various SOA scopes.

While JAX-WS deals directly with Web Services, the SCA view of a service is more diverse, addressing the issue of language independence for components and providing for the use of multiple access mechanisms for connecting components. This paper describes how pure JAX-WS components relate to the wider SCA model and how they are described in SCA assemblies.

JAX-WS components are represented in SCA using a specific implementation type, implementation.jaxws. An SCA assembly which has JAX-WS components deploys and runs those components using a JAX-WS compatible runtime. JAX-WS components can be derived from WSDL or Java, supporting both the top-down and bottom-up service development approaches. In both cases the JAX-WS related annotations are mapped to SCA specific metadata to which additional SCA metadata can be added, such as policies and deployment information.

Integrating JAX-WS Services

Supplying the inclusiveness required to assemble services from many different service creation approaches implies great flexibility on the part of the SCA Assembly specification. To achieve this goal of extensibility, the specification includes the concepts of implementation, interface and binding, which act as extension points in the architecture.

In terms of JAX-WS the implementation is an annotated Java class, the interface is a WSDL file, and the binding is the Web services binding.

Integrating SCA with JAX-WS Web Service components involves specifying these extension points.

Describing JAX-WS based SCA Components

JAX-WS supports the development of Java Web Services using two alternative approaches: 1) starting with a WSDL interface and 2) starting with a Java interface. In terms of extensions to SCA, these two approaches are distinct and appear as two different forms in the SCA assembly metadata.

Start with WSDL Interface

This approach to the development of a Web service involves the creation of an interface for a service, rendered as WSDL, which is then used as the basis for construction of language-specific stubs for consumers and skeletons for providers. JAX-WS prescribes the details of the Java stubs and skeletons. This approach is commonly used when the elements of a complex software system, or one with diverse implementation languages, is to be migrated to a Web services-based service-oriented architecture.
The example below shows an implementation of a trivial Web service that implements the interface specified in a WSDL description AddNumbers.wsdl. The WSDL source is displayed first. The Web service is called AddNumbers, which simply adds two integers, returning the integer result.

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
   xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
   xmlns:ns="http://example.org/AddNumbers"
   xmlns:ns2="http://example.org/AddNumbers/types"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   targetNamespace="http://example.org/AddNumbers">
   <wsdl:types>
         <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:types="http://example.org/AddNumbers/types"
               targetNamespace="http://example.org/AddNumbers/types"
               elementFormDefault="unqualified"
               attributeFormDefault="unqualified">
               <xs:element name="addNumbers">
                     <xs:complexType>
                           <xs:sequence>
                                 <xs:element type="xs:int" name="number1" />
                                 <xs:element type="xs:int" name="number2" />
                           </xs:sequence>
                     </xs:complexType>
               </xs:element>
               <xs:element name="addNumbersResponse">
                     <xs:complexType>
                           <xs:sequence>
                                 <xs:element type="xs:int" name="return" />
                           </xs:sequence>
                     </xs:complexType>
               </xs:element>
         </xs:schema>
   </wsdl:types>
   <wsdl:messagename="addNumbersMessage">
         <wsdl:part element="ns2:addNumbers"name="part1" />
   </wsdl:message>
   <wsdl:messagename="addNumbersResponseMessage">
         <wsdl:part element="ns2:addNumbersResponse"name="part1" />
   </wsdl:message>
   <wsdl:portTypename="AddNumbersPortType">
         <wsdl:operationname="addNumbers">
               <wsdl:input message="ns:addNumbersMessage"/>
               <wsdl:outputmessage="ns:addNumbersResponseMessage" />
         </wsdl:operation>
   </wsdl:portType>
   <wsdl:bindingtype="ns:AddNumbersPortType"
         name="AddNumbersSOAP12Binding">
         <soap12:bindingstyle="document"
               transport="http://schemas.xmlsoap.org/soap/http" />
         <wsdl:operationname="addNumbers">
               <soap12:operationstyle="document"
                     soapAction="urn:addNumbers"/>
               <wsdl:input>
                     <soap12:body namespace="http://example.org/AddNumbers"
                           use="literal" />
               </wsdl:input>
               <wsdl:output>
                     <soap12:body namespace="http://example.org/AddNumbers"
                           use="literal" />
               </wsdl:output>
         </wsdl:operation>
   </wsdl:binding>
   <wsdl:servicename="AddNumbers">
         <wsdl:port binding="ns:AddNumbersSOAP12Binding"
               name="AddNumbersSOAP12port">
               <soap12:address
                     location="http://localhost:8080/axis2/services/AddNumbers"/>
         </wsdl:port>
      </wsdl:service>
</wsdl:definitions>

Example 1: AddNumbers.wsdl file

package org.example;
import javax.jws.WebService;
@WebService(wsdlLocation="AddNumbers.wsdl")

public class AddNumbers {

   public int addNumbers( int number1, int number2 )
      { return number1 + number2; }

}

Example 2: AddNumbers.java class

To participate in an SCA service assembly, the interface, implementation and binding parts of the AddNumbers service must be defined in SCA terms. The implementation code defines its SCA configurable elements as a set of services, references and properties, which can be represented as a componentType in SCA. In the case of the AddNumbers Java component in Example 2, the componentType simply consists of a single service called AddNumbers, which references the portType in the WSDL document that describes the service interface via an interface.wsdl XML element.

<interface.wsdl interface="http://www.example.org/AddNumbersService#wsdl.interface(AddNumbers)"/>

</service>

</componentType>

Example 3: ComponentType of the AddNumbers.java class

The interface attribute of the interface.wsdl element references the WSDL portType for WSDL 1.1 documents, and the service interface for WSDL 2.0 documents.

The JAX-WS implementation class is referenced by an SCA component declaration which is part of an SCA composite file. SCA supports many different implementation types. For components which adhere to the JAX-WS programming model, an implementation type called <implementation.jaxws> is used:

<implementation.jaxws class="org.example.AddNumbers"/>

</component>

Example 4: Declaration for Component using AddNumbers class

Start with Java Interface

The alternate JAX-WS approach to the development of a Web service involves the creation of a Java interface for a service, represented as a set of Java 5 annotations decorating a Java class. This approach is commonly used when an existing Java service is to be quickly migrated to a Web service with a Java implementation, or when a monolithic Java application is being refactored using a Web services-based service-oriented architecture.

In this approach, the interface for the service is initially described as a set of annotations in the Java code, which are used to guide the creation of a WSDL description for the interface via a Java to WSDL tool.

The example below shows a version of the AddNumbers service, implemented as a JAX-WS service. Responsibility for the service interface and the service implementation has been assigned to two separate Java class artifacts, IAddNumbers and AddNumbersImpl, respectively.

// Interface Declaration
package org.example;

// imports have been elided for clarity

@WebService(targetNamespace = "http://example.org", name="AddNumbers")

@SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL)

public interface IAddNumbers extends Remote {

   @WebMethod(operationName="add", action="urn:addNumbers")

   @WebResult(name="return")

   public int addNumbers(

      @WebParam(name="num1")int number1,

      @WebParam(name="num2")int number2) throws RemoteException, AddNumbersException;

}

Example 5: IAddNumbers Java service interface

// Implementation Definition

package org.example;{color}

@WebService(endpointInterface="IAddNumbers")

public class AddNumbersImpl implements IAddNumbers {

   public int addNumbers( int number1, int number2 )
      { return number1 + number2; }

}

Example 6: AddNumbersImpl Java class

Once the WSDL has been generated from the Java interface, the corresponding SCA componentType for the AddNumbersImpl class has a service called AddNumbers and the interface for the service is described in terms of the generated WSDL as shown in Example 5:

<interface.wsdl interface="http://www.example.org/AddNumbersService#wsdl.interface(AddNumbers)"/>

</service>

</componentType>

Example 7: Component Type of the AddNumbersImpl class

Within the SCA composite file, the component description of a component using the AddNumberImpl class refers to the implementation class, using the <implementation.jaxws> implementation type:

<implementation.jaxws class="org.example.AddNumbersImpl"/>

</component>

Example 8: Declaration for Component using AddNumbersImpl class

Service Component Properties

SCA implementations may have any number of properties associated with them, whose values are set by the component that uses the implementation. In the case of a JAX-WS component implementation, the properties correspond to JSR-250 @Resource annotated fields in the Java implementation class. The name of the SCA property is the same as the name of the annotated field or the name specified on the @Resource annotation (if present), while its type is derived from type of the Java field following the Java-to-XML mapping rules defined by the JAX-WS specification.

The following example has a version of the JAX-WS Java AddNumberImpl class with a single field called myProperty which is annotated with @Resource. This is mapped to an SCA property of type xsd:string with name myProperty:

package org.example;

import javax.jws.WebService;

@WebService(wsdlLocation="AddNumbers.wsdl")

public class AddNumbersImpl implements IAddNumbers {

   @Resource

   String myProperty;
   public int addNumbers( int number1, int number2 )
      { return number1 + number2; }
}

Example 9: AddNumbersImpl class with a property defined through @Resource annotation

The AddNumbersImpl class is then used by an SCA component as follows:

<implementation.jaxws class="org.example.AddNumbersImpl"/>

XYZ_value

</property>

</component>

Example 10: SCA component declaration using a JAX-WS class with a settable property

In this case the myProperty property is given the value "XYZ_value", which is injected onto the component when it is started.

References in JAX-WS classes

SCA components may make references to services provided by other components - that is, they invoke operations on these references in order to obtain some business functionality. In this example, a component called Calculator depends upon the AddNumbers service described in the previous sections. For JAX-WS components, references to other service interfaces are represented using the @WebServiceRef JAX-WS annotation, which maps directly to an SCA reference element.

package org.example;
import javax.jws.WebService;

import javax.jws.WebServiceRef;
@WebService(wsdlLocation="Calculator.wsdl")

public class Calculator {

   @WebServiceRef
   IAddNumbers addNumbersService;

   ...

}

Example 11: Calculator class with a reference to the IAddNumbers service

The component type of the Calculator class would look something like the following:

<interface.wsdl interface="Calculator.wsdl"/>

</service>

<interface.wsdl interface="http://www.example.org/AddNumbersService#wsdl.interface(AddNumbers)"/>

</reference>

</componentType>

Example 12: Implied Component Type for the Calculator class

Bindings

SCA implementations and components do not need to describe the bindings used for either services or for references. However, when the components are used within an SCA composite, the wiring connecting to services and from references must ultimately describe the binding which will be used for the connection.

An SCA composite contains services and references, both of which contain binding elements. The binding element is extensible to permit provision of different types of bindings. SCA provides binding.ws for a Web services binding and it is this binding which is of most interest to a JAX-WS components.

Using binding.ws

The binding.ws Web Service binding is defined with a port attribute that references the port (WSDL 1.1) or the endpoint (WSDL 2.0) definitions.

<service name="Calculator">*

<interface.wsdl interface="Calculator.wsdl"/>

</service>

...

<interface.wsdl interface="AddNumbers.wsdl"/>

<binding.ws wsdlElement="http://www.example.org/AddNumbersService#wsdl.service(AddNumbers)" />

</reference>

</composite>

Example 13: Sample Composite showing use of binding.ws for a reference

The binding.ws binding is used when the JAX-WS service is defined in the WSDL-first manner and a WSDL description exists for the Java implementation. The WSDL may of course be automatically constructed from the Java artifacts.

For the convenience of developers, the JAX-WS specification describes a default binding that uses SOAP 1.1/HTTP 1.1. This is specified in the Java source using the @SOAPBinding annotation:

// Interface Declaration
package org.example;

// imports have been elided for clarity

@WebService(targetNamespace = "http://example.org", name="AddNumbers")

@SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL)

public interface IAddNumbers extends Remote {

   @WebMethod(operationName="add", action="urn:addNumbers")

   @WebResult(name="return")

   public int addNumbers(

      @WebParam(name="num1")int number1,

      @WebParam(name="num2")int number2) throws RemoteException, AddNumbersException;

}

Example 14: Java interface decorated with Annotations for the Web services Binding

The @SOAPBinding annotation does not need to be present in the Java implementation code - in the default case, JAX-WS will construct a wrapped, document-literal SOAP binding. The @SOAPBinding annotation may be parameterized to alter its behaviour, for example an unwrapped, or bare, parameter style may be specified. When using the annotations, the SCA JAX-WS runtime will create the WSDL required by binding.ws at runtime.

Summary

This paper describes the basis for the participation of components using pure JAX-WS programming model in SCA Assemblies. This basis is the use of an implementation.jaxws implementation type.

JAX-WS represents the most recent evolution of the JCP standard APIs for Web services and a popular choice for Java developers creating Web services. The inclusion of Java objects containing JAX-WS APIs and attributes is therefore important for SCA components and assemblies.

JAX-WS compliant Java objects are given their own implementation type: implementation.jaxws, so that an SCA runtime knows how to interpret the metadata within the object. JAX-WS objects also use binding.ws to wire their remote interfaces, and use the @Resource annotation to define settable properties.