Skip to content

GitLab

Commit 256dd782 authored by Lukas Jungmann's avatar Lukas Jungmann
Browse files

Update javadoc for JDK 14 

Signed-off-by: default avatarLukas Jungmann <lukas.jungmann@oracle.com>
parent c6992313
Hide whitespace changes
Inline Side-by-side
Showing with 94 additions and 89 deletions
jaxb-api/src/main/java/jakarta/xml/bind/JAXBContext.java
View file @ 256dd782
......@@ -65,7 +65,7 @@ import java.util.Properties;
* configure the datatype converter that will be used during these operations.</i>
*
* <a id="Unmarshalling"></a>
* <h3>Unmarshalling</h3>
* <h2>Unmarshalling</h2>
* <p>
* The {@link Unmarshaller} class provides the client application the ability
* to convert XML data into a tree of Java content objects.
......
jaxb-api/src/main/java/jakarta/xml/bind/annotation/XmlAccessorOrder.java
View file @ 256dd782
......@@ -21,12 +21,12 @@ import static java.lang.annotation.RetentionPolicy.*;
/**
* <p> Controls the ordering of fields and properties in a class. </p>
*
* <h3>Usage </h3>
* <h2>Usage </h2>
*
* <p> {@code @XmlAccessorOrder} annotation can be used with the following
* program elements:</p>
*
* <ul>
* program elements:</p>
*
* <ul>
* <li> package</li>
* <li> a top level class </li>
* </ul>
......@@ -49,8 +49,8 @@ import static java.lang.annotation.RetentionPolicy.*;
* </ul>
*
* <p>This annotation can be used with the following annotations:
* {@link XmlType}, {@link XmlRootElement}, {@link XmlAccessorType},
* {@link XmlSchema}, {@link XmlSchemaType}, {@link XmlSchemaTypes},
* {@link XmlType}, {@link XmlRootElement}, {@link XmlAccessorType},
* {@link XmlSchema}, {@link XmlSchemaType}, {@link XmlSchemaTypes},
* , {@link XmlJavaTypeAdapter}. It can also be used with the
* following annotations at the package level: {@link XmlJavaTypeAdapter}.
*
......
jaxb-api/src/main/java/jakarta/xml/bind/annotation/XmlAnyElement.java
View file @ 256dd782
......@@ -27,19 +27,19 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* Maps a JavaBean property to XML infoset representation and/or JAXB element.
*
* <p>
* This annotation serves as a "catch-all" property while unmarshalling
* This annotation serves as a "catch-all" property while unmarshalling
* xml content into a instance of a JAXB annotated class. It typically
* annotates a multi-valued JavaBean property, but it can occur on
* single value JavaBean property. During unmarshalling, each xml element
* that does not match a static &#64;XmlElement or &#64;XmlElementRef
* annotation for the other JavaBean properties on the class, is added to this
* single value JavaBean property. During unmarshalling, each xml element
* that does not match a static &#64;XmlElement or &#64;XmlElementRef
* annotation for the other JavaBean properties on the class, is added to this
* "catch-all" property.
*
* <h2>Usages:</h2>
* <pre>
* &#64;XmlAnyElement
* public {@link Element}[] others;
*
*
* // Collection of {@link Element} or JAXB elements.
* &#64;XmlAnyElement(lax="true")
* public {@link Object}[] others;
......@@ -64,7 +64,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
* <h2>Relationship to other annotations</h2>
* <p>
* This annotation can be used with {@link XmlJavaTypeAdapter}, so that users
* can map their own data structure to DOM, which in turn can be composed
* can map their own data structure to DOM, which in turn can be composed
* into XML.
*
* <p>
......@@ -237,13 +237,15 @@ public @interface XmlAnyElement {
* Controls the unmarshaller behavior when it sees elements
* known to the current {@link JAXBContext}.
*
* <h3>When false</h3>
* <p>
* <dl>
* <dt>When false</dt>
* <dd>
* If false, all the elements that match the property will be unmarshalled
* to DOM, and the property will only contain DOM elements.
* </dd>
*
* <h3>When true</h3>
* <p>
* <dt>When true</dt>
* <dd>
* If true, when an element matches a property marked with {@link XmlAnyElement}
* is known to {@link JAXBContext} (for example, there's a class with
* {@link XmlRootElement} that has the same tag name, or there's
......@@ -252,8 +254,10 @@ public @interface XmlAnyElement {
* instead of unmarshalling it to DOM. Additionally, if the element is
* unknown but it has a known xsi:type, the unmarshaller eagerly unmarshals
* the element to a {@link JAXBElement}, with the unknown element name and
* the JAXBElement value is set to an instance of the JAXB mapping of the
* the JAXBElement value is set to an instance of the JAXB mapping of the
* known xsi:type.
* </dd>
* </dl>
*
* <p>
* As a result, after the unmarshalling, the property can become heterogeneous;
......
jaxb-api/src/main/java/jakarta/xml/bind/annotation/XmlElementRef.java
View file @ 256dd782
......@@ -18,7 +18,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
/**
/**
* <p>
* Maps a JavaBean property to a XML element derived from property's type.
* <p>
......@@ -34,10 +34,10 @@ import static java.lang.annotation.ElementType.METHOD;
* XML element name is derived from the instance of the type of the
* JavaBean property at runtime.
*
* <h3> XML Schema substitution group support </h3>
* <h2> XML Schema substitution group support </h2>
* XML Schema allows a XML document author to use XML element names
* that were not statically specified in the content model of a
* schema using substitution groups. Schema derived code provides
* schema using substitution groups. Schema derived code provides
* support for substitution groups using an <i>element property</i>,
* (section 5.5.5, "Element Property" of JAXB 2.0 specification). An
* element property method signature is of the form:
......@@ -52,7 +52,7 @@ import static java.lang.annotation.ElementType.METHOD;
* element property indicates that the element name from {@code JAXBElement}
* instance be used instead of deriving an XML element name from the
* JavaBean property name.
*
*
* <p>
* The usage is subject to the following constraints:
* <ul>
......@@ -88,8 +88,8 @@ import static java.lang.annotation.ElementType.METHOD;
* &#64;XmlRootElement(name="target")
* class Target {
* // The presence of &#64;XmlElementRef indicates that the XML
* // element name will be derived from the &#64;XmlRootElement
* // annotation on the type (for e.g. "jar" for JarTask).
* // element name will be derived from the &#64;XmlRootElement
* // annotation on the type (for e.g. "jar" for JarTask).
* &#64;XmlElementRef
* List&lt;Task&gt; tasks;
* }
......@@ -107,7 +107,7 @@ import static java.lang.annotation.ElementType.METHOD;
* ...
* }
* {@code
*
*
* <!-- XML Schema fragment -->
* <xs:element name="target" type="Target">
* <xs:complexType name="Target">
......@@ -148,15 +148,15 @@ import static java.lang.annotation.ElementType.METHOD;
* <p> The following example shows the annotations for XML Schema
* substitution groups. The annotations and the ObjectFactory are
* derived from the schema.
*
*
* <pre>
* &#64;XmlElement
* class Math {
* // The value of {@link #type()}is
* // The value of {@link #type()}is
* // JAXBElement.class , which indicates the XML
* // element name ObjectFactory - in general a class marked
* // with &#64;XmlRegistry. (See ObjectFactory below)
* //
* //
* // The {@link #name()} is "operator", a pointer to a
* // factory method annotated with a
* // {@link XmlElementDecl} with the name "operator". Since
......@@ -166,7 +166,7 @@ import static java.lang.annotation.ElementType.METHOD;
* // elements "add" or "sub". At runtime, JAXBElement
* // instance contains the element name that has been
* // substituted in the XML document.
* //
* //
* &#64;XmlElementRef(type=JAXBElement.class,name="operator")
* JAXBElement&lt;? extends Operator&gt; term;
* }
......@@ -199,7 +199,7 @@ import static java.lang.annotation.ElementType.METHOD;
* </math>
* }</pre>
*
*
*
* @author <ul><li>Kohsuke Kawaguchi, Sun Microsystems,Inc. </li><li>Sekhar Vajjhala, Sun Microsystems, Inc.</li></ul>
* @see XmlElementRefs
* @since 1.6, JAXB 2.0
......@@ -235,7 +235,7 @@ public @interface XmlElementRef {
* an {@link XmlElementDecl}, then it is an error.
*
* <p> If {@code type()} is not {@code JAXBElement.class}, then
* this value must be "".
* this value must be "".
*
*/
String namespace() default "";
......
jaxb-api/src/main/java/jakarta/xml/bind/annotation/XmlSchema.java
View file @ 256dd782
......@@ -19,11 +19,11 @@ import static java.lang.annotation.RetentionPolicy.*;
/**
* <p> Maps a package name to a XML namespace. </p>
*
* <h3>Usage</h3>
* <h2>Usage</h2>
* <p>
* The XmlSchema annotation can be used with the following program
* elements:
* <ul>
* <ul>
* <li>package</li>
* </ul>
*
......@@ -41,15 +41,15 @@ import static java.lang.annotation.RetentionPolicy.*;
* package-info.java.
* </ul>
*
* <p><b>Example 1:</b> Customize name of XML namespace to which
* <p><b>Example 1:</b> Customize name of XML namespace to which
* package is mapped.</p>
*
* <pre>
* &#64;jakarta.xml.bind.annotation.XmlSchema (
* namespace = "http://www.example.com/MYPO1"
* )
* {@code
*
* {@code
*
* <!-- XML Schema fragment -->
* <schema
* xmlns=...
......@@ -66,7 +66,7 @@ import static java.lang.annotation.RetentionPolicy.*;
* <pre>
* // Package level annotation
* &#64;jakarta.xml.bind.annotation.XmlSchema (
* xmlns = {
* xmlns = {
* &#64;jakarta.xml.bind.annotation.XmlNs(prefix = "po",
* namespaceURI="http://www.example.com/myPO1"),
*
......@@ -75,13 +75,13 @@ import static java.lang.annotation.RetentionPolicy.*;
* }
* )
* {@code
*
*
* <!-- XML Schema fragment -->
* <schema
* xmlns:xs="http://www.w3.org/2001/XMLSchema"
* xmlns:po="http://www.example.com/PO1"
* targetNamespace="http://www.example.com/PO1">
*
*
* }</pre>
*
* <p><b>Example 3:</b> Customize elementFormDefault</p>
......@@ -91,13 +91,13 @@ import static java.lang.annotation.RetentionPolicy.*;
* ...
* )
* {@code
*
*
* <!-- XML Schema fragment -->
* <schema
* xmlns="http://www.w3.org/2001/XMLSchema"
* xmlns:po="http://www.example.com/PO1"
* elementFormDefault="unqualified">
*
*
* }</pre>
* @author Sekhar Vajjhala, Sun Microsystems, Inc.
......@@ -120,7 +120,7 @@ public @interface XmlSchema {
String namespace() default "";
/**
* Namespace qualification for elements. By default, element
* Namespace qualification for elements. By default, element
* default attribute will be absent from the XML Schema fragment.
*/
XmlNsForm elementFormDefault() default XmlNsForm.UNSET;
......@@ -162,7 +162,8 @@ public @interface XmlSchema {
* must have the same {@link #location()} values.
*
*
* <h3>Note to implementor</h3>
* <p>
* <strong>Note to implementor</strong>
* <p>
* More precisely, the value must be either {@code ""}, {@code "##generate"}, or
* <a href="http://www.w3.org/TR/xmlschema-2/#anyURI">
......
jaxb-api/src/main/java/jakarta/xml/bind/annotation/XmlType.java
View file @ 256dd782
......@@ -30,7 +30,7 @@ import java.lang.annotation.Target;
* <p>See "Package Specification" in jakarta.xml.bind.package javadoc for
* additional common information.</p>
*
* <h3> Mapping a Class </h3>
* <h2> Mapping a Class </h2>
* <p>
* A class maps to a XML Schema type. A class is a data container for
* values represented by properties and fields. A schema type is a
......@@ -45,7 +45,7 @@ import java.lang.annotation.Target;
* factory method overrides the no-arg constructor.
* <p>
* A class maps to either a XML Schema complex type or a XML Schema simple
* type. The XML Schema type is derived based on the
* type. The XML Schema type is derived based on the
* mapping of JavaBean properties and fields contained within the
* class. The schema type to which the class is mapped can either be
* named or anonymous. A class can be mapped to an anonymous schema
......@@ -56,12 +56,12 @@ import java.lang.annotation.Target;
* <ul>
* <li><b>global element: </b> A global element of an anonymous
* type can be derived by annotating the class with @{@link
* XmlRootElement}. See Example 3 below. </li>
* XmlRootElement}. See Example 3 below. </li>
*
* <li><b>local element: </b> A JavaBean property that references
* a class annotated with @XmlType(name="") and is mapped to the
* element associated with the anonymous type. See Example 4
* below.</li>
* below.</li>
*
* <li><b>attribute: </b> A JavaBean property that references
* a class annotated with @XmlType(name="") and is mapped to the
......@@ -72,7 +72,7 @@ import java.lang.annotation.Target;
* <li>If class is annotated with {@code @XmlType(name="") }, it
* is mapped to an anonymous type otherwise, the class name maps
* to a complex type name. The {@code XmlName()} annotation element
* can be used to customize the name.</li>
* can be used to customize the name.</li>
*
* <li> Properties and fields that are mapped to elements are mapped to a
* content model within a complex type. The annotation element
......@@ -115,7 +115,7 @@ import java.lang.annotation.Target;
* <th scope="col">SimpleType</th>
* </tr>
* </thead>
*
*
* <tbody>
* <tr>
* <td>Class</td>
......@@ -124,7 +124,7 @@ import java.lang.annotation.Target;
* <td>complexcontent<br>xs:all</td>
* <td> </td>
* </tr>
*
*
* <tr>
* <td>Class</td>
* <td>non empty</td>
......@@ -132,7 +132,7 @@ import java.lang.annotation.Target;
* <td>complexcontent<br>xs:sequence</td>
* <td> </td>
* </tr>
*
*
* <tr>
* <td>Class</td>
* <td>X</td>
......@@ -140,7 +140,7 @@ import java.lang.annotation.Target;
* <td>complexcontent<br>empty sequence</td>
* <td> </td>
* </tr>
*
*
* <tr>
* <td>Class</td>
* <td>X</td>
......@@ -148,7 +148,7 @@ import java.lang.annotation.Target;
* <td>simplecontent</td>
* <td> </td>
* </tr>
*
*
* <tr>
* <td>Class</td>
* <td>X</td>
......@@ -159,23 +159,23 @@ import java.lang.annotation.Target;
* </tbody>
* </table>
* </blockquote>
*
*
* <h3> Mapping an enum type </h3>
*
*
* An enum type maps to a XML schema simple type with enumeration
* facets. The following annotation elements are ignored since they
* are not meaningful: {@code propOrder()} , {@code factoryMethod()} ,
* {@code factoryClass()} .
*
* <h3> Usage with other annotations </h3>
* <p> This annotation can be used with the following annotations:
* <p> This annotation can be used with the following annotations:
* {@link XmlRootElement}, {@link XmlAccessorOrder}, {@link XmlAccessorType},
* {@link XmlEnum}. However, {@link
* XmlAccessorOrder} and {@link XmlAccessorType} are ignored when this
* annotation is used on an enum type.
*
*
* <p> <b> Example 1: </b> Map a class to a complex type with
* xs:sequence with a customized ordering of JavaBean properties.
* xs:sequence with a customized ordering of JavaBean properties.
* </p>
*
* <pre>
......@@ -183,13 +183,13 @@ import java.lang.annotation.Target;
* public class USAddress {
* String getName() {..};
* void setName(String) {..};
*
*
* String getStreet() {..};
* void setStreet(String) {..};
*
* String getCity() {..};
* String getCity() {..};
* void setCity(String) {..};
*
*
* String getState() {..};
* void setState(String) {..};
*
......@@ -197,7 +197,7 @@ import java.lang.annotation.Target;
* void setZip(java.math.BigDecimal) {..};
* }
* {@code
*
*
* <!-- XML Schema mapping for USAddress -->
* <xs:complexType name="USAddress">
* <xs:sequence>
......@@ -215,7 +215,7 @@ import java.lang.annotation.Target;
* &#64;XmlType(propOrder={})
* public class USAddress { ...}
* {@code
*
*
* <!-- XML Schema mapping for USAddress -->
* <xs:complexType name="USAddress">
* <xs:all>
......@@ -228,14 +228,14 @@ import java.lang.annotation.Target;
* </xs:complexType>
*}</pre>
* <p> <b> Example 3: </b> Map a class to a global element with an
* anonymous type.
* anonymous type.
* </p>
* <pre>
* &#64;XmlRootElement
* &#64;XmlType(name="")
* public class USAddress { ...}
* {@code
*
*
* <!-- XML Schema mapping for USAddress -->
* <xs:element name="USAddress">
* <xs:complexType>
......@@ -261,9 +261,9 @@ import java.lang.annotation.Target;
*
* &#64;XmlType(name="")
* public class USAddress { ... }
* }
* }
* {@code
*
*
* <!-- XML Schema mapping for USAddress -->
* <xs:complexType name="Invoice">
* <xs:sequence>
......@@ -282,24 +282,24 @@ import java.lang.annotation.Target;
*
* <p> <b> Example 5: </b> Map a property to an attribute with
* anonymous type.
*
*
* <pre>
*
* //Example: Code fragment
* public class Item {
* public String name;
* &#64;XmlAttribute
* &#64;XmlAttribute
* public USPrice price;
* }
*
* // map class to anonymous simple type.
*
* // map class to anonymous simple type.
* &#64;XmlType(name="")
* public class USPrice {
* public class USPrice {
* &#64;XmlValue
* public java.math.BigDecimal price;
* }
* {@code
*
*
* <!-- Example: XML Schema fragment -->
* <xs:complexType name="Item">
* <xs:sequence>
......@@ -315,7 +315,7 @@ import java.lang.annotation.Target;
*
* <p> <b> Example 6: </b> Define a factoryClass and factoryMethod
*
* <pre>
* <pre>
* &#64;XmlType(name="USAddressType", factoryClass=USAddressFactory.class,
* factoryMethod="getUSAddress")
* public class USAddress {
......@@ -326,7 +326,7 @@ import java.lang.annotation.Target;
* private String street;
* private int zip;
*
* public USAddress(String name, String street, String city,
* public USAddress(String name, String street, String city,
* String state, int zip) {
* this.name = name;
* this.street = street;
......@@ -338,14 +338,14 @@ import java.lang.annotation.Target;
*
* public class USAddressFactory {
* public static USAddress getUSAddress(){
* return new USAddress("Mark Baker", "23 Elm St",
* return new USAddress("Mark Baker", "23 Elm St",
* "Dayton", "OH", 90952);
* }
*
* </pre>
*
* <p> <b> Example 7: </b> Define factoryMethod and use the default factoryClass
*
*
* <pre>
* &#64;XmlType(name="USAddressType", factoryMethod="getNewInstance")
* public class USAddress {
......@@ -378,25 +378,25 @@ 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.
*
*
* <p> Refer to the table for how the propOrder affects the
* mapping of class </p>
*
*
* <p> 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. </p>
* <p> All of the JavaBean properties being mapped to XML Schema elements
* must be listed.
* must be listed.
* <p> A JavaBean property or field listed in propOrder must not
* be transient or annotated with {@code @XmlTransient}.
* <p> The default ordering of JavaBean properties is determined
* by @{@link XmlAccessorOrder}.
* by @{@link XmlAccessorOrder}.
*/
String[] propOrder() default {""};
......@@ -406,19 +406,19 @@ public @interface XmlType {
* containing the class is mapped.
*/
String namespace() default "##default" ;
/**
* Class containing a no-arg factory method for creating an
* instance of this class. The default is this class.
*
*
* <p>If {@code factoryClass} is DEFAULT.class and
* {@code factoryMethod} is "", then there is no static factory
* method.
*
*
* <p>If {@code factoryClass} is DEFAULT.class and
* {@code factoryMethod} is not "", then
* {@code factoryMethod} is not "", then
* {@code factoryMethod} is the name of a static factory method
* in this class.
* in this class.
*
* <p>If {@code factoryClass} is not DEFAULT.class, then
* {@code factoryMethod} must not be "" and must be the name of
......@@ -429,14 +429,14 @@ public @interface XmlType {
/**
* Used in {@link XmlType#factoryClass()} to
* signal that either factory mehod is not used or
* that it's in the class with this {@link XmlType} itself.
* that it's in the class with this {@link XmlType} itself.
*/
static final class DEFAULT {}
/**
* Name of a no-arg factory method in the class specified in
* {@code factoryClass} factoryClass().
*
*
*/
String factoryMethod() default "";
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Powered by Integricloud