Advertisement

Applying annotations

The JAX-RPC reference implementation relies on the annotation processing tool apt that debuted in JDK 1.5. apt operates on the Java source files to create additional code elements specified by annotations. The JAX-RPC 2.0 early access reference implementation includes an Ant task for running apt. Detailed documentation for apt is part of the JDK 1.5 documentation bundle, and instructions for using the apt Ant task are included in the JAX-RPC early access download package.

The next step is to run apt on the above Java code, resulting in several artifacts:

HelloServiceImpl.wsdl
schema1.xsd
classes/server/HelloImpl.class
classes/server/jaxrpc/SayHello.class
classes/server/jaxrpc/SayHelloResponse.class
classes/server/jaxrpc/SayHello.java
classes/server/jaxrpc/SayHelloResponse.java

The meaning of these items becomes clear from the WSDL document that resulted from running apt on the Web service definition. The generated WSDL is as follows:

<?xml version="1.0" encoding="UTF-8"?>

<definitions 
    name="HelloImplService" 
    targetNamespace="http://server/jaxrpc"    
    xmlns:tns="http://server/jaxrpc" 
    xmlns="http://schemas.xmlsoap.org/wsdl/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">

<types>
    <xsd:schema>
       <xsd:import namespace="http://server/jaxrpc"  
           schemaLocation="schema1.xsd"/>
    </xsd:schema>
</types>

<message name="sayHello">
    <part name="parameters" element="tns:sayHello"/>
</message>

<message name="sayHelloResponse">
    <part name="result" element="tns:sayHelloResponse"/>
</message>

<portType name="HelloImpl">
   <operation name="sayHello">
      <input message="tns:sayHello"/>
      <output message="tns:sayHelloResponse"/>
   </operation>
</portType>

<binding name="HelloImplBinding" type="tns:HelloImpl">
    <soap:binding 
       transport="http://schemas.xmlsoap.org/soap/http" 
         style="document"/>

    <operation name="sayHello">
      <soap:operation soapAction=""/>
      <input>
         <soap:body use="literal"/>
      </input>
      <output>
         <soap:body use="literal"/>
      </output>
    </operation>

 </binding>

<service name="HelloImplService">
    <port name="HelloImplPort" binding="tns:HelloImplBinding">
     <soap:address location="REPLACE_WITH_ACTUAL_URL"/>
     </port>
</service>

</definitions>

The WSDL's type definition imports an external schema file, schema1.xsd. That external schema file was also generated automatically, and it defines two complex types for the WSDL's message elements, sayHelloResponse and sayHello. Here is the generated schema:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" 
    targetNamespace="http://server/jaxrpc"    
      xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="sayHelloResponse" 
            type="ns1:sayHelloResponse" 
            xmlns:ns1="http://server/jaxrpc"/>

   <xs:complexType name="sayHelloResponse">
     <xs:sequence>
        <xs:element name="return" type="xs:string" minOccurs="0"/>
     </xs:sequence>
   </xs:complexType>

   <xs:element name="sayHello" 
               type="ns2:sayHello" 
               xmlns:ns2="http://server/jaxrpc"/>

   <xs:complexType name="sayHello">
     <xs:sequence>
        <xs:element name="name" type="xs:string" minOccurs="0"/>
     </xs:sequence>
   </xs:complexType>

</xs:schema>

The two Java classes, automatically defined by apt, define the beans JAXB uses to marshal and unmarshal the Web service messages. The apt tool compiles these sources, along with the service definition, into class files.

package server.jaxrpc;

import javax.xml.bind.annotation.*;
import javax.xml.rpc.ParameterIndex;

@XmlRootElement(name="sayHelloResponse", 
                namespace="http://server/jaxrpc")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name="sayHelloResponse", 
         namespace="http://server/jaxrpc", 
         propOrder={"_return"})
public class SayHelloResponse {
    @XmlElement(namespace="", name="return")
    @ParameterIndex(value=-1)
    public java.lang.String _return;

    public SayHelloResponse(){}
}

package server.jaxrpc;

import javax.xml.bind.annotation.*;
import javax.xml.rpc.ParameterIndex;

@XmlRootElement(name="sayHello",
                namespace="http://server/jaxrpc")
@XmlAccessorType(AccessType.FIELD)
@XmlType(name="sayHello", 
         namespace="http://server/jaxrpc", 
         propOrder={"name"})
public class SayHello {
    @XmlElement(namespace="", name="name")
    @ParameterIndex(value=0)
    public java.lang.String name;

    public SayHello(){}
}

Looking at these two bean source files reveals several further annotations defined in the JAXB 2.0 specification. Those annotations are used, in turn, to produce several additional classes to support the runtime marshaling and unmarshaling operations. We will not discuss those annotations in this article.