ohair@286: /* ohair@286: * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. ohair@286: * ohair@286: * This code is free software; you can redistribute it and/or modify it ohair@286: * under the terms of the GNU General Public License version 2 only, as ohair@286: * published by the Free Software Foundation. Oracle designates this ohair@286: * particular file as subject to the "Classpath" exception as provided ohair@286: * by Oracle in the LICENSE file that accompanied this code. ohair@286: * ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License ohair@286: * version 2 for more details (a copy is included in the LICENSE file that ohair@286: * accompanied this code). ohair@286: * ohair@286: * You should have received a copy of the GNU General Public License version ohair@286: * 2 along with this work; if not, write to the Free Software Foundation, ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. ohair@286: * ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@286: * or visit www.oracle.com if you need additional information or have any ohair@286: * questions. ohair@286: */ ohair@286: ohair@286: package javax.xml.bind.annotation; ohair@286: ohair@286: import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter; ohair@286: import java.lang.annotation.Retention; ohair@286: import java.lang.annotation.Target; ohair@286: ohair@286: import static java.lang.annotation.ElementType.*; ohair@286: import static java.lang.annotation.ElementType.PARAMETER; ohair@286: import static java.lang.annotation.RetentionPolicy.*; ohair@286: ohair@286: /** ohair@286: * Maps a JavaBean property to a XML element derived from property name. ohair@286: * ohair@286: *
Usage
ohair@286: *ohair@286: * @XmlElement annotation can be used with the following program ohair@286: * elements: ohair@286: *
ohair@286: * ohair@286: *
ohair@286: * A JavaBean property, when annotated with @XmlElement annotation ohair@286: * is mapped to a local element in the XML Schema complex type to ohair@286: * which the containing class is mapped. ohair@286: * ohair@286: *
ohair@286: * Example 1: Map a public non static non final field to local ohair@286: * element ohair@286: *
ohair@286: * //Example: Code fragment ohair@286: * public class USPrice { ohair@286: * @XmlElement(name="itemprice") ohair@286: * public java.math.BigDecimal price; ohair@286: * } ohair@286: * ohair@286: * <!-- Example: Local XML Schema element --> ohair@286: * <xs:complexType name="USPrice"/> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="itemprice" type="xs:decimal" minOccurs="0"/> ohair@286: * </sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: *
ohair@286: * ohair@286: * Example 2: Map a field to a nillable element. ohair@286: *
ohair@286: * ohair@286: * //Example: Code fragment ohair@286: * public class USPrice { ohair@286: * @XmlElement(nillable=true) ohair@286: * public java.math.BigDecimal price; ohair@286: * } ohair@286: * ohair@286: * <!-- Example: Local XML Schema element --> ohair@286: * <xs:complexType name="USPrice"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="0"/> ohair@286: * </sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: *
ohair@286: * Example 3: Map a field to a nillable, required element. ohair@286: *
ohair@286: * ohair@286: * //Example: Code fragment ohair@286: * public class USPrice { ohair@286: * @XmlElement(nillable=true, required=true) ohair@286: * public java.math.BigDecimal price; ohair@286: * } ohair@286: * ohair@286: * <!-- Example: Local XML Schema element --> ohair@286: * <xs:complexType name="USPrice"> ohair@286: * <xs:sequence> ohair@286: * <xs:element name="price" type="xs:decimal" nillable="true" minOccurs="1"/> ohair@286: * </sequence> ohair@286: * </xs:complexType> ohair@286: *ohair@286: *
ohair@286: * ohair@286: *
Example 4: Map a JavaBean property to an XML element ohair@286: * with anonymous type.
ohair@286: *ohair@286: * See Example 6 in @{@link XmlType}. ohair@286: * ohair@286: *
ohair@286: * @author Sekhar Vajjhala, Sun Microsystems, Inc. ohair@286: * @since JAXB2.0 ohair@286: */ ohair@286: ohair@286: @Retention(RUNTIME) @Target({FIELD, METHOD, PARAMETER}) ohair@286: public @interface XmlElement { ohair@286: /** ohair@286: * Name of the XML Schema element. ohair@286: *
If the value is "##default", then element name is derived from the ohair@286: * JavaBean property name. ohair@286: */ ohair@286: String name() default "##default"; ohair@286: ohair@286: /** ohair@286: * Customize the element declaration to be nillable. ohair@286: *
If nillable() is true, then the JavaBean property is ohair@286: * mapped to a XML Schema nillable element declaration. ohair@286: */ ohair@286: boolean nillable() default false; ohair@286: ohair@286: /** ohair@286: * Customize the element declaration to be required. ohair@286: *
If required() is true, then Javabean property is mapped to ohair@286: * an XML schema element declaration with minOccurs="1". ohair@286: * maxOccurs is "1" for a single valued property and "unbounded" ohair@286: * for a multivalued property. ohair@286: *
If required() is false, then the Javabean property is mapped ohair@286: * to XML Schema element declaration with minOccurs="0". ohair@286: * maxOccurs is "1" for a single valued property and "unbounded" ohair@286: * for a multivalued property. ohair@286: */ ohair@286: ohair@286: boolean required() default false; ohair@286: ohair@286: /** ohair@286: * XML target namespace of the XML Schema element. ohair@286: *
ohair@286: * If the value is "##default", then the namespace is determined ohair@286: * as follows: ohair@286: *
ohair@286: * The
'\u0000'value specified as a default of this annotation element ohair@286: * is used as a poor-man's substitute for null to allow implementations ohair@286: * to recognize the 'no default value' state. ohair@286: */ ohair@286: String defaultValue() default "\u0000"; ohair@286: ohair@286: /** ohair@286: * The Java class being referenced. ohair@286: */ ohair@286: Class type() default DEFAULT.class; ohair@286: ohair@286: /** ohair@286: * Used in {@link XmlElement#type()} to ohair@286: * signal that the type be inferred from the signature ohair@286: * of the property. ohair@286: */ ohair@286: static final class DEFAULT {} ohair@286: }