001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036:
037: package com.sun.xml.bind.annotation;
038:
039: import java.lang.annotation.Retention;
040: import java.lang.annotation.Target;
041:
042: import javax.xml.bind.annotation.XmlAttribute;
043: import javax.xml.bind.annotation.XmlElement;
044: import javax.xml.bind.annotation.XmlElementRef;
045: import javax.xml.bind.annotation.XmlValue;
046:
047: import static java.lang.annotation.ElementType.FIELD;
048: import static java.lang.annotation.ElementType.METHOD;
049: import static java.lang.annotation.RetentionPolicy.RUNTIME;
050:
051: /**
052: * Designates a boolean field/property as a flag to indicate
053: * whether another property is present or not.
054: *
055: * <p>
056: * Sometimes you'd want to map a Java primitive type to an
057: * optional element/attribute. Doing this makes it impossible
058: * to represent the absence of the property, thus you always
059: * end up producing the value when you marshal to XML.
060: *
061: * For example,
062: * <pre>
063: * {@link XmlElement}
064: * class Foo {
065: * {@link XmlElement}
066: * int x;
067: * }
068: *
069: * marshaller.marshal(new Foo());
070: * </pre>
071: * and you get:
072: * <pre><xmp>
073: * <foo><x>0</x></foo>
074: * </xmp></pre>
075: *
076: * <p>
077: * By creating a side boolean field/property that has this annotation,
078: * you can indicate the absence of the property by setting this boolean
079: * to false.
080: * <pre>
081: * {@link XmlElement}
082: * class Foo {
083: * {@link XmlElement}
084: * int x;
085: * {@link XmlIsSet}("x")
086: * boolean xIsPresent;
087: * }
088: *
089: * Foo f = new Foo();
090: * f.x = 5;
091: * f.xIsPresent = false;
092: *
093: * marshaller.marshal(f);
094: *
095: * <xmp>
096: * <foo/>
097: * </xmp>
098: *
099: * f.xIsPresent = true;
100: * <xmp>
101: * <foo><x>5</x></foo>
102: * </xmp>
103: * </pre>
104: *
105: * <p>
106: * A property/field annotated with {@link XmlIsSet} itself will not show up in XML.
107: * It is an error to use this annotation on the same property/field
108: * as {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue}, or {@link XmlElementRef},
109: * ...<b>TBD</b>.
110: *
111: * @deprecated
112: * this hasn't been implemented in the RI, and this hasn't been speced yet.
113: * I believe Joe asked for this feature. I'd like to drop this.
114: *
115: * @author Kohsuke Kawaguchi
116: */
117: @Retention(RUNTIME)
118: @Target({FIELD,METHOD})
119: public @interface XmlIsSet {
120: /**
121: * Specifies the name of the property to attach to.
122: */
123: String value();
124: }
|