3.4. Generating Javadocs from WSDL documentation

wsimport can map the documentation inside the WSDL that can map as corresponding Javadoc on the generated classes. The documentation inside the WSDL should be done using standard WSDL 1.1 element: <wsdl:documentation>.

It is important to note that not everythign in the WSDL maps to Java class, the table below shows wsdl:documentation to Javadoc mapping for various WSDL compoenents that correspond to the generated Java class.

WSDL documentation (wsdl:docuemntation) Javadoc
wsdl:portType As a Javadoc on the generated Service Endpoint Interface (SEI) class
wsdl:portType/wsdl:operation As a Javadoc on the corresponding method of the generated SEI class
wsdl:service As a Javadoc on the generated Service class
wsdl:service/wsdlport As a Javadoc on the generated getXYZPort() methods of the Service class

Let us see a sample wsdl with documentation and the generated Java classes:

WSDL with documentation


<wsdl:portType name="HelloWorld">
    <wsdl:documentation>This is a simple HelloWorld service.</wsdl:documentation>
    <wsdl:operation name="echo">
        <wsdl:documentation>This operation simply echoes back whatever it receives</wsdl:documentation>
        <wsdl:input message="tns:echoRequest"/>
        <wsdl:output message="tns:echoResponse"/>
    </wsdl:operation>
</wsdl:portType>

<service name="HelloService">
    <wsdl:documentation>This is a simple HelloWorld service.</wsdl:documentation>
    <port name="HelloWorldPort" binding="tns:HelloWorldBinding">
        <wsdl:documentation>A SOAP 1.1 port</wsdl:documentation>
        <soap:address location="http://localhost/HelloService"/>
    </port>
</service>


        

In the above WSDL the documentation is mentioned using standard WSDL 1.1 element: <wsdl:documentation>. Running wsimport on this will generate Javadoc on the SEI and Service class.

Generated SEI - HellowWorld.java

/**
 * This is a simple HelloWorld service.
 *
 * This class was generated by the JAX-WS RI.
 * JAX-WS RI 2.1.3-11/27/2007 02:44 PM(vivekp)-
 * Generated source version: 2.1
 *
 */
@WebService(name = "HelloWorld", targetNamespace = "http://example.com/wsdl")
@XmlSeeAlso({
    ObjectFactory.class
})
public interface HelloWorld {


    /**
     * This operation simply echoes back whatever it receives
     *
     * @param reqInfo
     * @return
     *     returns java.lang.String
     */
    @WebMethod
    @WebResult(name = "respInfo", targetNamespace = "http://example.com/types")
    @RequestWrapper(localName = "echo", targetNamespace = "http://example.com/types", className = "sample.EchoType")
    @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://example.com/types", className = "sample.EchoResponseType")
    public String echo(
        @WebParam(name = "reqInfo", targetNamespace = "http://example.com/types")
        String reqInfo);

}
        
Generated Service class HelloWorldService.java

/**
* This is a simple HelloWorld service.
*
* This class was generated by the JAX-WS RI.
* JAX-WS RI 2.1.3-11/27/2007 02:44 PM(vivekp)-
* Generated source version: 2.1
*
*/
@WebServiceClient(name = "HelloService", targetNamespace = "http://example.com/wsdl", wsdlLocation = "file:/C:/issues/wsdl/sample.wsdl")
public class HelloService
extends Service
{

private final static URL HELLOSERVICE_WSDL_LOCATION;
private final static Logger logger = Logger.getLogger(sample.HelloService.class.getName());

static {
    URL url = null;
    try {
        URL baseUrl;
        baseUrl = sample.HelloService.class.getResource(".");
        url = new URL(baseUrl, "file:/C:/issues/wsdl/sample.wsdl");
    } catch (MalformedURLException e) {
        logger.warning("Failed to create URL for the wsdl Location: 'file:/C:/issues/wsdl/sample.wsdl', retrying as a local file");
        logger.warning(e.getMessage());
    }
    HELLOSERVICE_WSDL_LOCATION = url;
}

public HelloService(URL wsdlLocation, QName serviceName) {
    super(wsdlLocation, serviceName);
}

public HelloService() {
    super(HELLOSERVICE_WSDL_LOCATION, new QName("http://example.com/wsdl", "HelloService"));
}

/**
 * A SOAP 1.1 port
 *
 * @return
 *     returns HelloWorld
 */
@WebEndpoint(name = "HelloWorldPort")
public HelloWorld getHelloWorldPort() {
    return super.getPort(new QName("http://example.com/wsdl", "HelloWorldPort"), HelloWorld.class);
}

        

Terms of Use; Privacy Policy; Copyright ©2013-2014 (revision 20131025.e7cbc9d)
 
 
Close
loading
Please Confirm
Close