javax.jws.WebService

The purpose of this annotation is to mark a endpoint implementation as implementing a web service or to mark that a service endpoint interface as defining a web service interface. All endpoint implementation classes MUST have a WebService annotation and must meet the requirements of section 3.3 of the JAX-WS 2.0 specification.

Example 1:

								
@WebService(name="AddNumbers", targetNamespace="http://duke.example.org", name="AddNumbers")
public class AddNumbersImpl {

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

								

Example 2:

@WebService(endpointInterface = "com.example.AddNumbersIF")
public class AddNumbersImpl {

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

								

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
public interface AddNumbersIF {
    public int addNumbers(int number1, int number2);
}

								

NOTE: The following rules apply for methods on classes annotated with the @WebService annotation:

javax.jws.WebMethod

The purpose of this annotation is to expose a method as a web service operation. The method must meet all the requirements of section 3.4 of the JAX-WS 2.0 specification.

Example:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
public interface AddNumbersIF {
    @WebMethod(operationName="add", action="urn:addNumbers")
    public int addNumbers(int number1, int number2);
}
								

NOTE: Apply this annotation to methods on a client or server Service Endpoint Interface (SEI) or a server endpoint implementation class.

NOTE: The @WebMethod annotation is only supported on classes that are annotated with the @WebService annotation.

javax.jws.OneWay

The purpose of this annotation is to mark a method as a web service one-way operation. The method must meet all the requirements of section 3.4.1 of the JSR 224 spec.

Example:

@WebService(name="CheckIn")
public interface CheckInIF {
    @WebMethod
    @OneWay
    public void checkIn(String name);
}
								

javax.jws.WebParam

This annotation is used to customize the mapping of a single parameter to a message part or element.

Example 1:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
public interface AddNumbersIF {
    @WebMethod(operationName="add", action="urn:addNumbers")
    @WebResult(name="return")
    public int addNumbers(
        @WebParam(name="num1")int number1,
        @WebParam(name="num2")int number2
    );
}

								

Example 2:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
public interface AddNumbersIF {
    @WebMethod(operationName="add", action="urn:addNumbers")
    @WebResult(name="return")
    public void addNumbers(
        @WebParam(name="num1")int number1,
        @WebParam(name="num2")int number2,
        @WebParam(name="result" mode=WebParam.Mode.OUT) Holder<Integer> result)
            throws AddNumbersException;
}

								

javax.jws.WebResult

This annotation is used to customize the mapping of the method return value to a WSDL part or XML element.

Example:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
public interface AddNumbersIF {
    @WebMethod(operationName="add", action="urn:addNumbers")
    @WebResult(name="return")
    public int addNumbers(
        @WebParam(name="num1")int number1,
        @WebParam(name="num2")int number2
    );
}
								

javax.jws.HandlerChain

This annotation is used to specified an externally defined handler chain.

Example:

@WebService
@HandlerChain(file="handlers.xml")
public class AddNumbersImpl {

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

								

<jws:handler-config xmlns:jws="http://java.sun.com/xml/ns/javaee">
    <jws:handler-chains>
        <jws:handler-chain>
            <jws:handler>
                <jws:handler-class>handler.common.LoggingHandler</jws:handler-class>
            </jws:handler>
        </jws:handler-chain>
    </jws:handler-chains>
</jws:handler-config>

								

You can only configure the server side handler by using the @HandlerChain annotation on the Service Endpoint Interface (SEI) or the server endpoint implementation class.

Use one of several ways to configure a client side handler. You can configure a client side handler by using the @HandlerChain annotation on the generated service class or SEI. Additionally, you can programmatically register your own implementation of the HandlerResolver interface on the Service, or programmatically set the handler chain on the Binding object.

javax.jws.soap.SOAPBinding

JSR 181 also allows you to specify a SOAPBinding annotation on a endpoint implementation or service endpoint interface. This annotation lets the developer choose between document/literal wrapped, document/literal bare, rpc/literal and rpc/encoded endpoints with the default being document/literal wrapped. JAX-WS 2.1 does not support rpc/encoded.

The main difference between document/literal bare and document/literal wrapped is that methods on a document/literal wrapped endpoint can have multiple parameters bound to the body of a SOAP message, while a document/literal bare can only have one such parameter.

The main difference between document/literal wrapped and rpc/literal is that a document/literal invocation can be fully validated by a standard validating XML parser, while an rpc/literal invocation cannot because of the implied wrapper element around the invocation body.

Example:

@WebService(targetNamespace="http://duke.example.org", name="AddNumbers")
@SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL)
public interface AddNumbersIF {
    @WebMethod(operationName="add", action="urn:addNumbers")
    @WebResult(name="return")
    public int addNumbers(
        @WebParam(name="num1")int number1,
        @WebParam(name="num2")int number2
    );
}
								

javax.xml.ws.BindingType

The BindingType annotation is used to specify the binding to use for a web service endpoint implementation class. As well as specify additional features that may be enabled.

This annotation may be overriden programmatically or via deployment descriptors, depending on the platform in use.

Example 1: Given the web service defined, the deployed endpoint would use the SOAP1.2 over HTTP binding:

@WebService
@BindingType(value="http://www.w3.org/2003/05/soap/bindings/HTTP/")
public class AddNumbersImpl {
    public int addNumbers(int number1, int number2) {
        return number1 + number2;
    }
}

								

Example 2: Here is another sample use of the BindingType annotation that specifies use of the SOAP1.1/HTTP binding, it enables both the AddressingFeature and the MTOMFeature and also sets the threshold feature parameter on the MTOMFeature:

@WebService
@BindingType(value=SOAPBinding.SOAP11HTTP_BINDING,
    features={
        @Feature(AddressingFeature.ID),
        @Feature(value=MTOMFeature.ID,
        parameters={@FeatureParameter(name=MTOMFeature.THRESHOLD, value="1000")})
     }
)
public class MyWebService { 
    ... 
}

								

NOTE: You can use the @BindingType annotation on the JavaBeans endpoint implementation class to enable MTOM by specifying either javax.xml.ws.soap.SOAPBinding.SOAP11HTTP_MTOM_BINDING or javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_MTOM_BINDING as the value for the annotation.

javax.xml.ws.RequestWrapper

This annotation annotates methods in the Service Endpoint Interface with the request wrapper bean to be used at runtime.

When starting from Java this annotation is used resolve overloading conflicts in document literal mode. Only the className is required in this case.

Example:

public interface AddNumbersImpl {
    @WebMethod
    @WebResult(targetNamespace = "")
    @RequestWrapper(localName="addNumbers", 
        targetNamespace="http://server.fromjava/", 
        className="fromjava.client.AddNumbers")
    @ResponseWrapper(localName="addNumbersResponse", 
        targetNamespace="http://server.fromjava/", 
        className="fromjava.client.AddNumbersResponse")
    public int addNumbers(
        @WebParam(name = "arg0", targetNamespace = "")
        int arg0,
        @WebParam(name = "arg1", targetNamespace = "")
        int arg1);
}

								

javax.xml.ws.ResponseWrapper

This annotation annotates methods in the Service Endpoint Interface with the response wrapper bean to be used at runtime.

When starting from Java this annotation is used resolve overloading conflicts in document literal mode. Only the className is required in this case.

Example:

public interface AddNumbersImpl {
    @WebMethod
    @WebResult(targetNamespace="")
    @RequestWrapper(localName="addNumbers", 
        targetNamespace="http://server.fromjava/", 
        className="fromjava.client.AddNumbers")
    @ResponseWrapper(localName="addNumbersResponse", 
        targetNamespace="http://server.fromjava/", 
        className="fromjava.client.AddNumbersResponse")
    public int addNumbers(
        @WebParam(name = "arg0", targetNamespace = "")
        int arg0,
        @WebParam(name = "arg1", targetNamespace = "")
        int arg1);
}

								

javax.xml.ws.ServiceMode

This annotation allows the Provider developer to indicate whether a Provider implementation wishes to work with entire protocol messages or just with protocol message payloads.

Example:

@WebServiceProvider(wsdlLocation="WEB-INF/wsdl/AddNumbers.wsdl")
@ServiceMode(value=Service.Mode.PAYLOAD)
public class AddNumbersImpl implements Provider<Source> {

    public Source invoke(Source source) throws RemoteException {
        try {
            DOMResult dom = new DOMResult();
            Transformer trans = TransformerFactory.newInstance().newTransformer();
            trans.transform(source, dom);
            Node node = dom.getNode();
            Node root = node.getFirstChild();
            Node first = root.getFirstChild();
            int number1 = Integer.decode(first.getFirstChild().getNodeValue());
            Node second = first.getNextSibling();
            int number2 = Integer.decode(second.getFirstChild().getNodeValue());
            return sendSource(number1, number2);
        } catch(Exception e) {
            e.printStackTrace();
            throw new RemoteException("Error in provider endpoint");
        }
    }
    
    private Source sendSource(int number1, int number2) {
        int sum = number1+number2;
        String body =
            "<ns:addNumbersResponse xmlns:ns=\"http://duke.example.org\"><return>"
            +sum
            +"</return></ns:addNumbersResponse>";
        Source source = new StreamSource(
            new ByteArrayInputStream(body.getBytes()));
        return source;
    }
    
}

								

NOTE: The @ServiceMode annotation is only supported on classes that are annotated with the @WebServiceProvider annotation.

javax.xml.ws.WebEndpoint

Used to annotate the get PortName() methods of a generated service interface.

The information specified in this annotation is sufficient to uniquely identify a wsdl:port element inside a wsdl:service. The latter is determined based on the value of the @WebServiceClient annotation on the generated service interface itself.

Example:

@WebServiceClient(name="AddNumbersImplService", 
                  targetNamespace="http://server.fromjava/", 
                  wsdlLocation="http://localhost:8080/jaxws-fromjava/addnumbers?wsdl")
public class AddNumbersImplService extends Service {
    private final static URL WSDL_LOCATION;
    private final static QName ADDNUMBERSIMPLSERVICE = 
        new QName("http://server.fromjava/", "AddNumbersImplService");
        
    private final static QName ADDNUMBERSIMPLPORT = 
        new QName("http://server.fromjava/", "AddNumbersImplPort");
    
    static {
        URL url = null;
        try {
            url = new URL("http://localhost:8080/jaxws-fromjava/addnumbers?wsdl");
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
        WSDL_LOCATION = url;
    }
    
    public AddNumbersImplService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }
    
    public AddNumbersImplService() {
        super(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE);
    }

    /**
     *
     * @return
     *     returns AddNumbersImpl
     */
    @WebEndpoint(name = "AddNumbersImplPort")
    public AddNumbersImpl getAddNumbersImplPort() {
        return (AddNumbersImpl)super.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.class);
    }
}

								

javax.xml.ws.WebFault

This annotation is generated by the JAX-WS tools into service specific exception classes generated from a WSDL to customize to the local and namespace name of the fault element and the name of the fault bean and to mark the service specific exception as one generated from WSDL. Developers should not use this annotation themselves. The reason that the JAX-WS needs to know if a service specific exception is generated from a WSDL or not is because these exceptions will already have a fault bean generated for them. The name of this fault bean is not the same name as on generated from a Java service specific exception class. For more information on this topic, please refer to section 3.6 of the JAX-WS 2.0 specification.

Example:

@javax.xml.ws.WebFault(name="AddNumbersException", 
                       targetNamespace="http://server.fromjava/jaxws")
public class AddNumbersException_Exception extends Exception {

    private fromjava.client.AddNumbersException faultInfo;
    
    public AddNumbersException_Exception(String message, AddNumbersException faultInfo) {
        super(message);
        this.faultInfo = faultInfo;
    }
    
    public AddNumbersException_Exception(String message, AddNumbersException faultInfo, Throwable cause) {
        super(message, cause);
        this.faultInfo = faultInfo;
    }
    
    public fromjava.client.AddNumbersException getFaultInfo() {
        return faultInfo;
    }
}

								

This annotation can only be applied to a fault implementation class on the client or server.

javax.xml.ws.WebServiceClient

The information specified in this annotation is sufficient to uniquely identify a wsdl:service element inside a WSDL document. This wsdl:service element represents the Web service for which the generated service interface provides a client view.

Example:

@WebServiceClient(name="AddNumbersImplService", 
                  targetNamespace="http://server.fromjava/", 
                  wsdlLocation="http://localhost:8080/jaxws-fromjava/addnumbers?wsdl")
public class AddNumbersImplService extends Service {
    private final static URL WSDL_LOCATION;
    private final static QName ADDNUMBERSIMPLSERVICE = 
        new QName("http://server.fromjava/", "AddNumbersImplService");
        
    private final static QName ADDNUMBERSIMPLPORT = 
        new QName("http://server.fromjava/", "AddNumbersImplPort");
    
    static {
        URL url = null;
        try {
            url = new URL("http://localhost:8080/jaxws-fromjava/addnumbers?wsdl");
        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
        WSDL_LOCATION = url;
    }
    
    public AddNumbersImplService(URL wsdlLocation, QName serviceName) {
        super(wsdlLocation, serviceName);
    }
    
    public AddNumbersImplService() {
        super(WSDL_LOCATION, ADDNUMBERSIMPLSERVICE);
    }
    
    /**
     *
     * @return
     *     returns AddNumbersImpl
     */
    @WebEndpoint(name = "AddNumbersImplPort")
    public AddNumbersImpl getAddNumbersImplPort() {
        return (AddNumbersImpl)super.getPort(ADDNUMBERSIMPLPORT, AddNumbersImpl.class);
    }
}
								
								

javax.xml.ws.WebServiceProvider

Annotation used to annotate a Provider implementation class.

Example:

@ServiceMode(value=Service.Mode.PAYLOAD)
@WebServiceProvider(wsdlLocation="WEB-INF/wsdl/AddNumbers.wsdl")
public class AddNumbersImpl implements Provider {

    public Source invoke(Source source) {
        try {
            DOMResult dom = new DOMResult();
            Transformer trans = TransformerFactory.newInstance().newTransformer();
            trans.transform(source, dom);
            Node node = dom.getNode();
            Node root = node.getFirstChild();
            Node first = root.getFirstChild();
            int number1 = Integer.decode(first.getFirstChild().getNodeValue());
            Node second = first.getNextSibling();
            int number2 = Integer.decode(second.getFirstChild().getNodeValue());
            return sendSource(number1, number2);
        } catch(Exception e) {
            e.printStackTrace();
            throw new RuntimeException("Error in provider endpoint", e);
        }
    }

    private Source sendSource(int number1, int number2) {
        int sum = number1+number2;
        String body = "" + sum + "";
        Source source = new StreamSource(new ByteArrayInputStream(body.getBytes()));
        return source;
    }
}

								

NOTE:

javax.xml.ws.WebServiceRef

The @WebServiceRef annotation is used to define a reference to a web service and (optionally) an injection target for it. Web service references are resources in the Java EE 5 sense.

Example:

import javax.xml.ws.WebServiceRef;
import com.techtip.jaxws.sample.CalculatorService;
import com.techtip.jaxws.sample.Calculator;

public class JAXWSClient {
    @WebServiceRef(wsdlLocation="http://localhost:8080/CalculatorService?WSDL")
    static CalculatorService service;
       
    public void doTest() {
        try {
            Calculator port = service.getCalculatorPort();
            int ret = port.add(2, 2);
        } catch(Exception e) {
            e.printStackTrace();
        }
    }
}
								

NOTE: The @WebServiceRef annotation can be used to inject instances of JAX-WS services and ports.

NOTE: The @WebServiceRef annotation is only supported in certain class types. Examples are JAX-WS endpoint implementation classes, JAX-WS handler classes, Enterprise JavaBeans classes, and servlet classes. This annotation is supported in the same class types as the @Resource annotation. See the Java Platform, Enterprise Edition (Java EE) 5 specification for a complete list of supported class types.

javax.xml.ws.Feature

The @Feature annotation is used to enable/disable a feature to use for a web service endpoint implementation class. This annotation is used with @BindingType annotation.

Here is a sample use of the @BindingType annotation that specifies use of the SOAP1.1/HTTP binding, it enables both the AddressingFeature and the MTOMFeature and also sets the threshold feature parameter on the MTOMFeature:

@BindingType(
    value=SOAPBinding.SOAP11HTTP_BINDING,
    features={
        @Feature(AddressingFeature.ID),
        @Feature(value=MTOMFeature.ID,
        parameters={@FeatureParameter(name=MTOMFeature.THRESHOLD, value="1000")})
    }
)
public class MyWebService { 
    ... 
}

								

javax.xml.ws.FeatureParameter

The @FeatureParameter annotation is used to specify paramaters for a feature. This annotation is used with @Feature.

javax.xml.ws.Action

The @Action annotation allows explicit association of Action message addressing property with input, output, and fault messages of the mapped WSDL operation.

This annotation can be specified on each method of a service endpoint interface or implementation. For such a method, the mapped operation in the generated WSDL contains explicit wsaw:Action attribute on the WSDL input, output and fault messages of the WSDL operation based upon which attributes of the Action annotation have been specified.

Example: Specify explicit values for Action message addressing property for input and output messages:

								
@javax.jws.WebService
public class AddNumbersImpl {
    @javax.xml.ws.Action(
        input="http://example.com/inputAction",
        output="http://example.com/outputAction")
    public int addNumbers(int number1, int number2) {
        return number1 + number2;
    }
}

								

<definitions targetNamespace="http://example.com/numbers" ...>
  ...
  <portType name="AddNumbersPortType">
    <operation name="AddNumbers">
      <input message="tns:AddNumbersInput" name="Parameters" wsaw:Action="http://example.com/inputAction"/>
      <output message="tns:AddNumbersOutput" name="Result" wsaw:Action="http://example.com/outputAction"/>
    </operation>
  <portType>
  ...
<definitions>       
								
								

javax.xml.ws.FaultAction

The @FaultAction annotation is used inside an @Action annotation to allow an explicit association of Action message addressing property with the fault messages of the WSDL operation mapped from the exception class.

The fault message in the generated WSDL operation mapped for className class contains explicit wsaw:Action attribute.

Example: Specify explicit values for Action message addressing property for the input, output and fault message if the Java method throws only one service specific exception:

@javax.jws.WebService
public class AddNumbersImpl {
    @javax.xml.ws.Action(
        input="http://example.com/inputAction",
        output="http://example.com/outputAction",
        fault = {@javax.xml.ws.FaultAction(className=AddNumbersException.class, 
            value="http://example.com/faultAction")}
    )
    public int addNumbers(int number1, int number2) throws AddNumbersException {
        return number1 + number2;
    }
}

								

<definitions targetNamespace="http://example.com/numbers" ...>
  ...
  <portType name="AddNumbersPortType">
    <operation name="AddNumbers">
      <input message="tns:AddNumbersInput" name="Parameters" wsaw:Action="http://example.com/inputAction"/>
      <output message="tns:AddNumbersOutput" name="Result" wsaw:Action="http://example.com/outputAction"/>
      <fault message="tns:AddNumbersException" name="AddNumbersException" wsaw:Action="http://example.com/faultAction"/>
    </operation>
  <portType>
  ...
<definitions>