Web Service - Start from Java

This section provides guidelines for designing an XML schema exported
by a Java web service designed starting from Java. JAXB 2.0 provides a rich
set of annotations and types for mapping Java classes to different XML Schema
constructs. The guidelines provide guidance on using JAXB 2.0 annotations
and types so that developer friendly bindings may be generated by XML serialization
mechanisms (svcutil) on WCF client.

Not all JAXB 2.0 annotations are included here; not all are relevant
from an interoperability standpoint. For example, the annotation @XmlAccessorType provides control over default serialization of fields and properties
in a Java class but otherwise has no effect on the on-the-wire XML representation
or the XML schema generated from a Java class. Select JAXB 2.0 annotations
are therefore not included here in the guidance.

The guidance includes several examples, which use the following conventions:

The prefix xs: is used to represent XML
Schema namespace.

JAXB 2.0 annotations are defined in javax.xml.bind.annotation package but, for brevity, the package name has been omitted.

BigDecimal Type

Guideline: Limit decimal values to
the range and precision of .NET’s System.decimal.

java.math.BigDecimal maps to xs:decimal.
.NET maps xs:decimal to System.decimal.
These two data types support different range and precision. java.math.BigDecimal supports arbitrary precision. System.decimal does
not. For interoperability use only values within the range and precision of System.decimal. (See System.decimal.Minvalue and System.decimal.Maxvalue.) Any values outside of this range require
a customized .NET client.

java.net.URI Type

Guideline: Use the @XmlSchemaType annotation for a strongly typed binding to a .NET client generated
with the DataContractSerializer.

java.net.URI maps to xs:string.
.NET maps xs:string to System.string.
Annotation @XmlSchemaType can be used to define a more
strongly typed binding to a .NET client generated with the DataContractSerializer. @XmlSchemaType can be used to map java.net.URI to xs:anyURI. .NET’s DataContractSerializer and XmlSerializer bind xs:anyURI differently:

DataContractSerializer binds xs:anyURI to .NET type System.Uri.

XmlSerializer binds xs:anyURI to
.NET type System.string.

Thus, the above technique only works if the WSDL is processed using DataContractSerializer.

XMLGregorianCalendar Type

Guideline: Use java.xml.datatype.XMLGregorianCalendar instead of java.util.Date and java.util.Calendar.

XMLGregorianCalendar supports the following XML schema
calendar types: xs:date, xs:time, xs:dateTime, xs:gYearMonth, xs:gMonthDay, xs:gYear, xs:gMonth, and xs:gDay.
It is statically mapped to xs:anySimpleType, the common
schema type from which all the XML schema calendar types are dervived. .NET
maps xs:anySimpleType to System.string.

java.util.Date and java.util.Calendar map
to xs:dateTime, but don’t provide as complete XML
support as XMLGregorianCalendar does.

Guideline: Use the annotation @XmlSchemaType for a strongly typed binding of XMLGregorianCalendar to
one of the XML schema calendar types.

UUID Type

Guideline: Use Leach-Salz variant
of UUID at runtime.

java.util.UUID maps to schema type xs:string.
.NET maps xs:string to System.string.
The constructors in java.util.UUID allow any variant of
UUID to be created. Its methods are for manipulation of the Leach-Salz variant.

Collections Types

Java collections types (java.util.Collection and
its subtypes, array, List, and parameterized collection types such as List<Integer>) can be mapped to XML schema in different ways and can be serialized
in different ways. The following examples show .NET bindings.

List of Nillable Elements

Guideline: By default, a collection
type such as List<Integer> maps to an XML schema
construct that is a repeating unbounded occurrence of an optional and nillable
element. .NET binds the XML schema construct to System.Nullable<int>[]. The element is optional and nillable. However, when marshalling
JAXB marshaller will always marshal a null value using xsi:nil.

List of Optional Elements

Guideline: This is the same as above
except that a collection type such as List<Integer> maps
to a repeating unbounded occurrence of an optional (minOccurs="0")
but not nillable element. This in turn binds to .NET type int[].
This is more developer friendly. However, when marshalling, JAXB will marshal
a null value within the List<Integer> as a value
that is absent from the XML instance.

List of Values

Guideline: A collection such as List<Integer> can be mapped to a list of XML values (that
is, an XML schema list simple type) using annotation @XmlList.
.NET maps a list simple type to a .NET System.string.

Fields and Properties

The following guidelines apply to mapping of JavaBeans properties and
Java fields, but for brevity Java fields are used.

@XmlElement Annotation

Guideline: The @XmlElement annotation
maps a property or field to an XML element. This is also the default mapping
in the absence of any other JAXB 2.0 annotations. The annotation parameters
in @XmlElement can be used to specify whether the element
is optional or required, nillable or not. The following examples illustrate
the corresponding bindings in the .NET client.

@XmlElementRefs Annotation

Guideline:@XmlElementRefs maps
to a xs:choice. This binds to a property with name item in the C# class. If there is another field/property named item in the Java class, there will be a name clash that .NET will resolve
by generating name. To avoid the name clash, either change the name or use
customization, for example @XmlElement(name="foo").

Java Classes

A Java class can be mapped to different XML schema type and/or an XML
element. The following guidelines apply to the usage of annotations at the
class level.

@XmlType Annotation - Anonymous
Type

Guideline: Prefer mapping class to
named XML schema type rather than an anonymous type for a better .NET type
binding.

The @XmlType annotation is used to customize the
mapping of a Java class to an anonymous type. .NET binds an anonymous type
to a .NET class - one per reference to the anonymous type. Thus, each Java
class mapped to an anonymous type can generate multiple classes on the .NET
client.

@XmlType Annotation - xs:all

Guideline: Avoid using XmlType(propOrder=:{}).

@XmlType(propOrder={}) maps a Java class to an XML
Schema complex type with xs:all content model. Since XML
Schema places severe restrictions on xs:all, the use of @XmlType(propOrder={}) is therefore not recommended. So, the following
example shows the mapping of a Java class to xs:all, but
the corresponding .NET code generated by svcutil is omitted.