JAX-RPC 2.0 Early Access
Annotations


Last Modified: 04/04/2005

Contents

1. Overview
2. JSR 181 (Web Services Metadata) Annotations
    2.1 javax.jws.WebService
    2.2 javax.jws.WebMethod
    2.3 javax.jws.OneWay
    2.4 javax.jws.WebParam
    2.5 javax.jws.WebResult
    2.6  javax.jws.HandlerChain
    2.7  javax.jws.soap.SOAPBinding
3. JSR 224 (JAX-RPC) Annotations
    3.1 javax.xml.rpc.ParameterIndex
    3.2 javax.xml.rpc.ServiceMode
    3.3 javax.xml.rpc.WebFault
4. JSR 222 (JAXB) Annotations
    4.1 javax.xml.bind.annotation.XmlRootElement 
    4.2 javax.xml.bind.annotation.XmlAccessorType
    4.3 javax.xml.bind.annotation.XmlType
    4.4 javax.xml.bind.annotation.XmlElement

1. Overview

Annotations play a critical role in JAX-RPC 2.0. First, annotations are used in mapping Java to WSDL and schema. Second, annotations are used a runtime to control how the JAX-RPC runtime processes and responds to web service invocations. Currently the annotations utilized by JAXR-RPC 2.0 are defined in separate JSRs: 1) JSR 181: Web Services Metadata for the JavaTM Platform, 2) JSR 222: JavaTM Architecture for XML Binding (JAXB) 2.0 and 3) JSR 224: JavaTM API for XML-Based RPC (JAX-RPC) 2.0. In the future annotations from JSR 250: Common Annotations for the JavaTM Platform may also used.

2. JSR 181 (Web Services Metadata) Annotations

Because JSR 181 has been written to work with JAX-RPC 1.1, we have made slight changes in the use and interpretation of these annotations to work better with JAX-RPC 2.0. We are working with the 181 expert group to align the next release with JAX-RPC 2.0 and we hope that all of the changes we have made will be folded in.

2.1 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-RPC 2.0 specification.

Property

Description

Default

name

The name of the wsdl:portType

The unqualified name of the Java class or interface

targetNamespace

The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules.

The namespace mapped from the package name containing the web service according to section 3.2 of the JAX-RPC 2.0 specification.

serviceName

The Service name of the web service: wsdl:service

The unqualified name of the Java class or interface + “Service

endpointInterface

The qualified name of the service endpoint interface. This annotation allows the separation of interface contract from implementation. If this property is specified, all other WebService properties are ignored as are all other 181 annotations. Only the annotations on the service endpoint interface will be taken into consideration. The endpoint implementation class is not required to implement the endpointInterface.

None – If not specified, the endpoint implementation class is used to generate the web service contract. In this case, a service endpoint interface is not required.

wsdlLocation

Not currently used by JAXR-RPC 2.0




Annotation Type Definition

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

Example 1

@WebService(name = "AddNumbers",
            targetNamespace = "http://duke.org", name="AddNumbers")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException
     *             if any of the numbers to be added is negative.
     */
     public int addNumbers(int number1, int number2) throws AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be added!",
                                         "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
     }
}


If you are familiar with JAX-RPC 1.1, you will notice that the AddNumbersImpl implementation class does not implement a service endpoint interface. In JAX-RPC 2.0 a service endpoint interface is no longer required. If a service endpoint interfaces is desired, then the @WebService annotation on the endpoint implementation is modified to specify the endpoint interface and the actual service endpoint interface must also have a @WebService annotation. The following is the above AddNumbersImpl modified to use a service endpoint interface.

Example 2

@WebService(endpointInterface = "annotations.server.AddNumbersIF")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException
     *             if any of the numbers to be added is negative.
     */
     public int addNumbers(int number1, int number2) throws AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be added!",
                                         "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
     }
}


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


2.2 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-RPC 2.0 specification.

Property

Description

Default

operationName

The name of the wsdl:operation matching this method. For operations using the mode defined by SOAPBinding.Style.DOCUMENT, SOAPBinding.Use.LITERAL, and SOAPBinding.ParameterStyle.BARE, this name is also used for the global XML element representing the operations body element. The namespace of this name is taken from the value WebService.targetNamespace or its default value.

The name of the Java method

action

The XML namespace of the the WSDL and some of the XML elements generated from this web service. Most of the XML elements will be in the namespace according to the JAXB mapping rules.

“”



Annotation Type Definition

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

Example

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

2.3 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.

There are no properties on the OneWay annotation.

Annotation Type Definition

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

Example

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

2.4 javax.jws.WebParam

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

Property

Description

Default

name

For RPC bindings, this name is the name of the wsdl:part representing the parameter. For DOCUMENT/LITRERAL WRAPPED bindings, this name is the local name of the XML element representing this parameter. This property is not used for DOCUMENT/LITERAL BARE bindings.

Name of the parameter as it appears in the parameter list for DOCUMENT/LITERAL WRAPPED operations. For RPC/LITERAL operations, the default value will be “argX” where X is the parameter positions within the parameter list starting at position 0.

targetNamespace

The XML namespace of the XML element for the parameter. Only used with DOCUMENT/LITRERAL WRAPPED bindings.

The targetNamespace for the web service.

mode

Represents the direction the parameter flows for this method. Possible values are IN, INOUT and OUT. INOUT and OUT modes can only be used with parameters that meet the requirements for a holder as classified by section 3.5 of the JAX-RPC 2.0 specification. OUT and INOUT parameters can be used by all RPC and DOCUMENT bindings.

IN for non-holder parameters INOUT for holder parameters.

header

Specifies whether the parameter should be carried in a header.

FALSE



Annotation Type Definition

@Retention(value=RetentionPolicy.RUNTIME)
@Target({PARAMETER})
public @interface WebParam {
    public enum Mode {
        IN,
        OUT,
        INOUT
    };

    String name() default "";
    String targetNamespace() default "";
    Mode mode() default Mode.IN;
    boolean header() default false;
}

Example 1

@WebService(targetNamespace = "http://duke.org", name="AddNumbers")
public interface AddNumbersIF 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 2

@WebService(targetNamespace = "http://duke.org", name="AddNumbers")
public interface AddNumbersIF extends Remote {
    @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) GenericHolder<Integer> result)
        throws RemoteException, AddNumbersException;
}

2.5 javax.jws.WebResult

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

Property

Description

Default

name

The name of the return value in the WSDL and on the wire. For RPC bindings this is the part name of the return value in the response message. For DOCUMENT bindings this is the local name of the XML element representing the return value.

return” for RPC and DOCUMENT/WRAPPED bindings. Method name + “Response” for DOCUMENT/BARE bindings.


targetNamespace

The XML namespace of the return value. Only used with DOCUMENT bindings where the return value maps to an XML element.

The targetNamespace for the web service.



Annotation Type Definition

@Retention(value=RetentionPolicy.RUNTIME)
@Target({METHOD})
public @interface WebResult {
    String name() default "result";
    String targetNamespace() default "";
}

Example

@WebService(targetNamespace = "http://duke.org", name="AddNumbers")
public interface AddNumbersIF 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;
}

2.6 javax.jws.HandlerChain

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

Property

Description

Default

file

Location of the file containing the handler chain definition. The location can be relative or absolute with in a classpath system. If the location is relative, it is relative to the package of the web service. If it is absolute, it is absolute from some path on the classpath.

None

name

The handler chain name from within the handler chain file.

None


Annotation Type Definition

@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE})
public @interface HandlerChain {
    String file();
    String name();
}

Example

@WebService
@HandlerChain( file="handlers.xml", name="Chain1")
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException
     *     if any of the numbers to be added is negative.
     */
    public int addNumbers(int number1, int number2) throws AddNumbersException {
        if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be added!",
                "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
    }
}

/*  handlers.xml */
<jws:handler-config xmlns:jws="http://www.bea.com/xml/ns/jws">
   <jws:handler-chain>
      <jws:handler-chain-name>Chain1</jws:handler-chain-name>
      <jws:handler>
         <jws:handler-name>fromjavahandler.common.LoggingHandler</jws:handler-name>
         <jws:handler-class>fromjavahandler.common.LoggingHandler</jws:handler-class>
      </jws:handler>
   </jws:handler-chain>
</jws:handler-config>


IMPORTANT NOTE:

When using a handler chain file, it is important that the file is store in the appropriate place in the classpath so that the file can be found. This means that when a raw WAR file is created that the file must be place in the proper directory. Please refer to the fromjavahandlers sample application and the handlers documentation for more information.

2.7 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-RPC 2.0 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.

Property

Description

Default

style

Defines the style for messages used in a web service. The value can be either DOCUMENT or RPC.

DOCUMENT

use

Defines the encoding used for messages used in web service. Can only be LITERAL for JAX-RPC 2.0

LITERAL

parameterStyle

Determines if the method's parameters represent the entire message body or whether the parameters are wrapped in a body element named after the operation. Choice of WRAPPED or BARE. BARE can only be used with DOCUMENT style bindings.

WRAPPED


Annotation Type Definition

@Retention(value=RetentionPolicy.RUNTIME)
@Target({TYPE})
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;
}

IMPORTANT NOTE:

The original SOAPBinding annotation is only targeted for a TYPE. For this release we have added com.sun.ws.soap.SOAPBinding annotation defined as:

@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;
}

You may see the Sun version of this annotation on methods in service endpoint interfaces generated by JAX-RPC. This is because WSDLs are not always guaranteed to have the same bindings for each operation, especially when WRAPPED vs BARE comes into play.

Example

@WebService(targetNamespace = "http://duke.org", name="AddNumbers")
@SOAPBinding(style=SOAPBinding.Style.RPC, use=SOAPBinding.Use.LITERAL)
public interface AddNumbersIF 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;
}

3. JSR 224 (JAX-RPC) Annotations

The following are standard annotations needed by JAX-RPC that are not defined in 181. The developer may not ever use these annotations directly as some of them are generated by JAX-RPC tools but they will be presented here to avoid confusion.

3.1 javax.xml.rpc.ParameterIndex

This annotation is generated by the JAX-RPC and is used in the wrapper beans for DOCUMENT/LITERAL WRAPPED operations as described in section 3.5.2.1 of the JAX-RPC 2.0 specification. Developers should not use this annotation themselves. This annotation maps the annotated field/property to parameter at the parameter position within the corresponding method of the web service.

Property

Description

Default

value

The parameter position in the Java method that this wrapper bean represents. A value of -1 represents the return value. The parameter positions are zero based

-1

Annotation Type Definition

@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ParameterIndex {
  /**
   *  The index of the method parameter that the annotated program
   *  element (a field or a method) corresponds to.
  **/
  public int value() default -1;
}

Example

Given the web service defined by:

@WebService
public class AddNumbersImpl {
    /**
     * @param number1
     * @param number2
     * @return The sum
     * @throws AddNumbersException
     *             if any of the numbers to be added is negative.
     */
     public int addNumbers(int number1, int number2) throws AddNumbersException {
         if (number1 < 0 || number2 < 0) {
            throw new AddNumbersException("Negative number cant be added!",
                                          "Numbers: " + number1 + ", " + number2);
        }
        return number1 + number2;
     }
}

The generated request wrapper would be:

public class AddNumbers {
    @ParameterIndex(value=0)
    public int number1;
    @ParameterIndex(value=1)
    public int number2;

    public AddNumbers(){}
}


and the generated response wrapper would be:

public class AddNumbersResponse {
    @ParameterIndex(value=-1)
    public int _return;

    public AddNumbersResponse(){}
}

3.2 javax.xml.rpc.ServiceMode

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

Property

Description

Default

value

Convey whether the Provider endpoint wants to access then entire message (MESSAGE) or just the payload(PAYLOAD)

PAYLOAD

Annotation Type Definition

@Target({ElementType.TYPE})@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ServiceMode {
  /**
   * Service mode. PAYLOAD indicates that the Provider implementation
   * wishes to work with protocol message payloads only. MESSAGE indicates
   * that the Provider implementation wishes to work with entire protocol
   * messages.
  **/
  public Service.Mode value() default Service.Mode.PAYLOAD;
}

Example

@ServiceMode(value=Service.Mode.PAYLOAD)
public class AddNumbersImpl implements Provider<Source> {
    public Source invoke(Source source, JAXRPCContext context)
        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.org\"><return>"
            +sum
            +"</return></ns:addNumbersResponse>";
        Source source = new StreamSource(
            new ByteArrayInputStream(body.getBytes()));
        return source;
    }
}

3.3 javax.xml.rpc.WebFault

This annotation is generated by the JAX-RPC 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-RPC 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-RPC 2.0 specification.

Property

Description

Default

name

Defines the local name of the XML element representing the corresponding fault in the WSDL.

“”

targetNamespace

Defines the namespace of the XML element representing the corresponding fault in the WSDL.

“”

faultBean

The qualified name of the Java class that represents the detail of the fault message.

“”

Annotation Type Definition

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface WebFault {
  /**
   *  Elements local name.
  **/
  public String name() default "";

  /**
   *  Elements namespace name.
  **/
  public String targetNamespace() default "";

  /**
   *  Fault bean name.
  **/
  public String faultBean() default "";
}

Example

@javax.xml.rpc.WebFault(name="AddNumbersException",
    targetNamespace="http://server.fromjava/jaxrpc")
public class AddNumbersException_Exception extends Exception {
    private fromjava.client.AddNumbersException faultInfo;
    public AddNumbersException_Exception(String message, fromjava.client.AddNumbersException faultInfo) {
        super(message);
        this.faultInfo = faultInfo;
    }

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

    public fromjava.client.AddNumbersException getFaultInfo() {
        return faultInfo;
    }
}

4. JSR 222 (JAXB) Annotations

The following JAXB annotations are being documented because JAX-RPC generates them when generating wrapper beans and exception beans according to the JAX-RPC 2.0 spec. Please refer to sections 3.5.2.1 and 3.6 of the JAX-RPC 2.0 specification for more information on these beans. For more information on these and other JAXB annotations please refer to the JAXB 2.0 specification.

4.1 javax.xml.bind.annotation.XmlRootElement

This annotation is used to map a top level class to a global element in the XML schema used by the WSDL of the web service.

Property

Description

Default

name

Defines the local name of the XML element representing the annotated class

"##default" – the name is derived from the class 

namespace

Defines the namespace of the XML element representing the annotated class

"##default" – the namespace is derived from the package of the class 

Annotation Type Definition

@Retention(RUNTIME)
@Target({TYPE})
public @interface XmlRootElement {
    /**
     * namespace name of the XML element.
     *
     * If the value is "##default", then the XML namespace name is derived
     * from the package of the class ( {@link XmlSchema} ). If the
     * package is unnamed, then the XML namespace is the default empty
     * namespace.
     */
    String namespace() default "##default";

    /**
     * local name of the XML element.
     *
     * If the value is "##default", then the name is derived from the
     * class name.
     *
     */
    String name() default "##default";
}

Example

@XmlRootElement(name="addNumbers",
    namespace="http://server.fromjava/jaxrpc")
@XmlAccessorType(AccessType.FIELD)
public class AddNumbers {
    @XmlElement(namespace="", name="number1")
    @ParameterIndex(value=0)
    public int number1;
    @XmlElement(namespace="", name="number2")
    @ParameterIndex(value=1)
    public int number2;

    public AddNumbers(){}
}

4.2 javax.xml.bind.annotation.XmlAccessorType

This annotation is used to specify whether fields or properties are serialized by default.


Property

Description

Default

value

Specifies whether fields or properties are serialized by default. The value can be AccessType.FIELD or AccessType.PROPERTY

AccessType.PROPERTY

Annotation Type Definition

@Inherited @Retention(RUNTIME) @Target({PACKAGE, TYPE})
public @interface XmlAccessorType {
    /**
     * Specifies whether fields or properties are serialized. 
     * 
     * If the value is AccessType.PROPERTY, then properties are
     * serialized by default and fields are assumed to be annotated
     * with {@link XmlTransient}.
     *
     * If the value is AccessType.FIELD, then fields are serialized by
     * default and properties are assumed to be annotated with 
     * with {@link XmlTransient}.
     * 
     */
    AccessType value() default AccessType.PROPERTY;
}



public enum AccessType {
    /**
     * Every getter/setter pair in a JAXB-bound class will be automatically
     * bound to XML, unless annotated by {@link XmlTransient}.
     *
     * Fields are bound to XML only when they are explicitly annotated
     * by some of the JAXB annotations.
     */
    PROPERTY,

    /**
     * Every field in a JAXB-bound class will be automatically
     * bound to XML, unless annotated by {@link XmlTransient}.
     *
     * Getter/setter pairs are bound to XML only when they are explicitly annotated
     * by some of the JAXB annotations.
     */
    FIELD
}

Example

@XmlRootElement(name="addNumbers",
    namespace="http://server.fromjava/jaxrpc")
@XmlAccessorType(AccessType.FIELD)
public class AddNumbers {
    @XmlElement(namespace="", name="number1")
    @ParameterIndex(value=0)
    public int number1;
    @XmlElement(namespace="", name="number2")
    @ParameterIndex(value=1)
    public int number2;

    public AddNumbers(){}
}

4.3 javax.xml.bind.annotation.XmlType

This annotation is used to map a value class to an XML Schema type. A value class is a data container for values represented by properties and fields. A schema type is a data container for values represented by schema components within a schema type's content model (e.g. Model groups, attributes etc).

Property

Description

Default

name

Defines the local name of the XML type representing this class in the XML schema used by the WSDL of the web service

"##default"

namespace

Defines the namespace of the XML type representing this class in the XML schema used by the WSDL of the web service

"##default"

propOrder

Defines a list of names of JavaBean properties in the class. Each name in the list is the name of a Java identifier of the JavaBean property. The order in which JavaBean properties are listed is the order of XML Schema elements to which the JavaBean properties are mapped.

All of the JavaBean properties being mapped must be listed (i.e. if a JavaBean property mapping is prevented by @XmlTransient, then it does not have to be listed). Otherwise, it is an error.

By default, the JavaBean properties are ordered using a default order specified in the JAXB 2.0 specification.

{“”}

Annotation Type Definition

@Retention(RUNTIME) @Target({TYPE})
public @interface XmlType {
    /**
     * Name of the XML Schema type which the class is mapped.
     */
    String name() default "##default" ;

    /**
     * Specifies the order for XML Schema elements when class is
     * mapped to a XML Schema complex type.
     * 
     * Refer to the table for how the propOrder affects the
     * mapping of class 
     * 
     *     The propOrder is a list of names of JavaBean properties in
     *     the class. Each name in the list is the name of a Java
     *     identifier of the JavaBean property. The order in which
     *     JavaBean properties are listed is the order of XML Schema
     *     elements to which the JavaBean properties are mapped. 
     *     All of the JavaBean properties being mapped must be
     *     listed (i.e. if a JavaBean property mapping is prevented
     *     by @XmlTransient, then it does not have to be
     *     listed). Otherwise, it is an error.
     *     By default, the JavaBean properties are ordered using a
     *     default order specified in the JAXB 2.0 specification.
     */
    String[] propOrder() default {""};

    /**
     * Name of the target namespace of the XML Schema type. By
     * default, this is the target namespace to which the package
     * containing the class is mapped.
     */
    String namespace() default "##default" ;
}

Example

@XmlRootElement(name="addNumbers",
    namespace="http://server.fromjava/jaxrpc")
@XmlAccessorType(AccessType.FIELD)
public class AddNumbers {
    @XmlElement(namespace="", name="number1")
    @ParameterIndex(value=0)
    public int number1;
    @XmlElement(namespace="", name="number2")
    @ParameterIndex(value=1)
    public int number2;

    public AddNumbers(){}
}


4.4 javax.xml.bind.annotation.XmlElement

This annotation is used to map a property contained in a class to a local element in the XML Schema complex type to which the containing class is mapped.

Property

Description

Default

name

Defines the local name of the XML element representing the property of a JavaBean

"##default” - the element name is derived from the JavaBean property name.

namespace

Defines the namespace of the XML element representing the property of a JavaBean

"##default” - the namespace of the containing class

nillable

Not generated by JAX-RPC


type

Not generated by JAX-RPC


Annotation Type Definition

@Retention(RUNTIME) @Target({FIELD, METHOD})
public @interface XmlElement {
    /**
     *
     * Name of the XML Schema element. 
     * If the value is "##default", then element name is derived from the
     * JavaBean property name. 
     */
    String name() default "##default";

    /**
     * Customize the element declaration to be nillable. 
     * If nillable() is true, then the JavaBean property is
     * mapped to a XML Schema nillable element declaration. 
     * If nillable() is false and the JavaBean property type is a
     * collection type, then the JavaBean property is mapped to
     * repeating occurrence. 
     * Otherwise, the JavaBean property is mapped to an an 
     * XML Schema element declaration with occurrence range of 0..1.
     */
    boolean nillable() default false;

    /**
     * Specifies the XML target namespace of the XML Schema
     * element. The namespace must be a valid namespace URI.
     * 
     * It the value is "##default", then the namespace is the
     * namespace of the containing class.
     * 
     */
    String namespace() default "##default" ;

    /**
     * The Java class being referenced.
     */
    Class type() default DEFAULT.class;

    /**
     * Used in {@link XmlElement#type()} to
     * signal that the type be inferred from the signature
     * of the property.
     */
    static final class DEFAULT {}
}

Example

@XmlRootElement(name="addNumbers",
    namespace="http://server.fromjava/jaxrpc")
@XmlAccessorType(AccessType.FIELD)
public class AddNumbers {
    @XmlElement(namespace="", name="number1")
    @ParameterIndex(value=0)
    public int number1;
    @XmlElement(namespace="", name="number2")
    @ParameterIndex(value=1)
    public int number2;

    public AddNumbers(){}
}

Copyright © 2005 Sun Microsystems, Inc. All rights reserved.