You can use the @WebService and @WebMethod annotations on a service endpoint implementation to specify Java methods that you want to expose as Java API for XML-Based Web Services (JAX-WS) web services.

JAX-WS technology enables the implementation of web services based on both the standard service endpoint interface and a Provider interface. When developing a JAX-WS Web service starting from existing Java classes, known as the bottom-up approach, you must annotate the class with either the @WebService or @WebServiceProvider annotation to initially define the class as a web service.

Using the Provider interface is the dynamic approach to defining your JAX-WS services. To use the Provider interface, your class must implement the javax.xml.ws.Provider interface, and contain the @WebServiceProvider annotation. The Provider interface has one method, the invoke method, which uses generics in the Java programming language to control both the input and output types when working with various messages or message payloads.

To describe your web services using the service endpoint interface (SEI) approach, initially define a web service, annotate the Java class with the @WebService annotation. However, you can also selectively annotate the individual methods with @WebMethod annotation to control how these methods are exposed as web services operations.

@javax.jws.WebService marks a Java class as implementing a web service, or a Java interface as defining a web service interface:

@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface WebService {
    String name() default "";
    String targetNamespace() default "";
    String serviceName() default "";
    String wsdlLocation() default "";
    String endpointInterface() default "";
    String portName() default "";
};
						

Example:

/**
 * Annotated Implementation Object
 */
@WebService(
    name = "EchoService",
    targetNamespace = "http://www.openuri.org/2004/04/HelloWorld"
)
public class EchoServiceImpl {
    @WebMethod
    public String echo(String input) {
        return input;
    }
}
						

Use the following best practices for defining web services:

@javax.jws.WebMethod customizes a method that is exposed as a web wervice operation.

@Retention(value=RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface WebMethod {
    String operationName() default "";
    String action() default "" ;
};
						

The @WebMethod annotation includes the following member-value pairs:

Java source:

@WebService
public class MyWebService {
    @WebMethod(operationName = "echoString", action="urn:EchoString")
    public String echo(String input) {
        return input;
    }
}
						

Resulting WSDL:

<definitions>
    <portType name="MyWebService">
        <operation name="echoString"/>
            <input message="echoString"/>
            <output message="echoStringResponse"/>
        </operation>
    </portType>

    <binding name="PingServiceHttpSoap">
        <operation name="echoString">
            <soap:operation soapAction="urn:EchoString"/>
        </operation>
    </binding>
</definitions>

						

NOTE: Beginning with Sun and HP JDK Version 1.6 containing JAX-WS tooling Version 2.1.6, the behavior of the JAX-WS runtime environment and tooling has changed how it interprets the JAX-WS specification regarding exposing methods as web services operations. When the web service does not specify a pre-existing WSDL file, the JAX-WS tooling behavior that generates a WSDL file has changed. This change does not affect web services that reference a WSDL file. The change in semantics might affect web services that do not reference a WSDL file or a SEI, and they rely on the JAX-WS runtime environment to create a WSDL file.

Using the NEW interpretation, a method in an implicit SEI and its superclasses are only exposed under the following conditions:

Using the LEGACY interpretation, a method in an implicit SEI and its superclasses are only exposed under the following conditions:

Example:

public class Base {

    @WebMethod(exclude=false)
    public void superMethod1(String s) {...}

    public String superMethod2(String s) {...}
}
						

@WebService(targetNamespace="foo")
public class BeanImpl extends Base {

    @WebMethod(exclude=false)
    public void method1(String s) {...}

    public String method2(String s) {...}
}
						

Before JAX-WS 2.1.6, the only exposed method would be:

public void method1(String s) {...}
						

In JAX-WS 2.1.6 and later the following methods will be exposed:

public void superMethod1(String s) {...}
public void method1(String s) {...}
public String method2(String s) {...}
						

@javax.jws.soap.SOAPBinding specifies the mapping of the web service onto the SOAP message protocol. The SOAPBinding annotation has a target of TYPE and METHOD. The annotation may be placed on a method if and only if the SOAPBinding.style is DOCUMENT. Implementations MUST report an error if the SOAPBinding annotation is placed on a method with a SOAPBinding.style of RPC. Methods that do not have a SOAPBinding annotation accept the SOAPBinding behavior defined on the type.

The @SOAPBinding annotation includes the following member-value pairs:

@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE, METHOD})

public @interface SOAPBinding {
    public enum Style {
        DOCUMENT,
        RPC
    };

    public enum Use {
        LITERAL,
        ENCODED
    };

    public enum ParameterStyle {
        BARE,
        WRAPPED
    }

    Style style() default Style.DOCUMENT;
    Use use() default Use.LITERAL;
    ParameterStyle parameterStyle() default ParameterStyle.WRAPPED;
}
						

The @javax.jws.Oneway annotation indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method. A JSR-181 processor is REQUIRED to report an error if an operation marked @Oneway has a return value, declares any checked exceptions or has any INOUT or OUT parameters.

@Retention(value=RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface Oneway {
};
						

Java source:

@WebService
public class PingService {
    @WebMethod
    @Oneway
    public void ping() {
        ...
    }
}
						

Resulting WSDL:

<definitions>
    <message name="ping"/>
    ...
    <portType name="PingService">
        <operation name="ping">
            <input message="ping"/>
        </operation>
    </portType>
</definitions>

						

WebParam

The @javax.jws.WebParam annotation customizes the mapping of an individual parameter to a web service message part and XML element.

Java Source:

@WebService(targetNamespace="http://www.openuri.org/jsr181/WebParamExample")
@SOAPBinding(style=SOAPBinding.Style.RPC)
public class PingService {

    @WebMethod(operationName = "PingOneWay")
    @Oneway
    public void ping(PingDocument ping) {
        ...
    }

    @WebMethod(operationName = "PingTwoWay")
    public void ping(
        @WebParam(mode=WebParam.Mode.INOUT)
        PingDocumentHolder ping) {
        ...
    }

    @WebMethod(operationName = "SecurePing")
    @Oneway
    public void ping(
        PingDocument ping,
        @WebParam(header=true)
        SecurityHeader secHeader) {
        ...
    }
}
						

Resulting WSDL:

<definitions
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://www.openuri.org/jsr181/WebParamExample"
    xmlns:wsdl="http://www.openuri.org/jsr181/WebParamExample"
    xmlns:s="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    targetNamespace="http://www.openuri.org/jsr181/WebParamExample">

    <types>
        <s:schema elementFormDefault="qualified" targetNamespace="http://www.openuri.org/jsr181/WebParamExample">
            <s:complexType name="PingDocument">
                . . .
            </s:complexType>

            <s:complexType name="SecurityHeader">
                . . .
            </s:complexType>

            <s:element name="SecurityHeader" type="SecurityHeader"/>
        </s:schema>
    </ types>

    <message name="PingOneWay">
        <part name="arg0" type="tns:PingDocument"/>
    </message>

    <message name="PingTwoWay">
        <part name="arg0" type="tns:PingDocument"/>
    </message>

    <message name="PingTwoWayResponse">
        <part name="arg0" type="tns:PingDocument"/>
    </message>

    <message name="SecurePing">
        <part name="arg0" type="tns:PingDocument"/>
        <part name="arg1" element="tns:SecurityHeader"/>
    </message>

    <portType name="PingService">
        <operation name="PingOneWay">
            <input message="tns:PingOneWay"/>
        </operation>

        <operation name="PingTwoWay">
            <input message="tns:PingTwoWay"/>
            <output message="tns:PingTwoWayResponse"/>
        </operation>

        <operation name="SecurePing">
            <input message="tns:SecurePing"/>
        </operation>
    </portType>

    <binding name="PingServiceHttpSoap" type="tns:PingService">

        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>

        <operation name="PingOneWay">
            <soap:operation soapAction="http://openuri.org/PingOneWay" />
            <input>
                <soap:body parts="arg0" use="literal"/>
            </input>
        </operation>

        <operation name="PingTwoWay">
            <soap:operation soapAction="http://openuri.org/PingTwoWay"/>
            <input>
                <soap:body parts="arg0" use="literal"/>
            </input>
            <output>
                <soap:body parts="arg0" use="literal"/>
            </output>
        </operation>

        <operation name="SecurePing">
            <soap:operation soapAction="http://openuri.org/SecurePing"/>
            <input>
                <soap:body parts="arg0" use="literal"/>
                <soap:header message="SecurePing" part="arg1" use="literal"/>
            </input>
        </operation>

    </binding>
</definitions>

						

WebResult

Use the @javax.jws.WebResult annotation to map to an existing wsdl:output or to customize how it's generated.

Java Source:

@WebService
public class CustomerService {

    @WebMethod
    @WebResult(name="CustomerRecord")
    public CustomerRecord locateCustomer(
        @WebParam(name="FirstName") String firstName,
        @WebParam(name="LastName") String lastName,
        @WebParam(name="Address") USAddress addr) {
        ...
    }
}
						

Resulting WSDL:

<definitions>

    <types>
        <complexType name="CustomerRecord">
            ...
        </complexType>

        <complexType name="USAddress">
            ...
        </complexType>

        <element name="locateCustomer">
            <complexType>
                <sequence>
                    <element name="FirstName" type="xs:string" />
                    <element name="LastName" type="xs:string" />
                    <element name="Address" type="USAddress"/>
                </sequence>
            </complexType>
        </element>

        <element name="locateCustomerResponse">
            <complexType>
                <sequence>
                    <element name="CustomerRecord" type="CustomerRecord"/>
                </sequence>
            </complexType>
        </element>
    </types>

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

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

    <portType name="CustomerService">
        <operation name="locateCustomer">
            <input message="tns:locateCustomer"/>
            <output message="tns:locateCustomerResponse"/>
        </operation>
    </portType>

</definitions>

						

blah-blah

blah-blah

blah-blah

blah-blah

blah-blah