325N/A/*
325N/A * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
325N/A *
325N/A * This code is free software; you can redistribute it and/or modify it
325N/A * under the terms of the GNU General Public License version 2 only, as
325N/A * published by the Free Software Foundation. Oracle designates this
325N/A * particular file as subject to the "Classpath" exception as provided
325N/A * by Oracle in the LICENSE file that accompanied this code.
325N/A *
325N/A * This code is distributed in the hope that it will be useful, but WITHOUT
325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
325N/A * version 2 for more details (a copy is included in the LICENSE file that
325N/A * accompanied this code).
325N/A *
325N/A * You should have received a copy of the GNU General Public License version
325N/A * 2 along with this work; if not, write to the Free Software Foundation,
325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
325N/A *
325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
325N/A * or visit www.oracle.com if you need additional information or have any
325N/A * questions.
325N/A */
325N/A
325N/Apackage com.sun.xml.internal.bind.annotation;
325N/A
325N/Aimport java.lang.annotation.Retention;
325N/Aimport java.lang.annotation.Target;
325N/A
325N/Aimport javax.xml.bind.annotation.XmlAttribute;
325N/Aimport javax.xml.bind.annotation.XmlElement;
325N/Aimport javax.xml.bind.annotation.XmlElementRef;
325N/Aimport javax.xml.bind.annotation.XmlValue;
325N/A
325N/Aimport static java.lang.annotation.ElementType.FIELD;
325N/Aimport static java.lang.annotation.ElementType.METHOD;
325N/Aimport static java.lang.annotation.RetentionPolicy.RUNTIME;
325N/A
325N/A/**
325N/A * Designates a boolean field/property as a flag to indicate
325N/A * whether another property is present or not.
325N/A *
325N/A * <p>
325N/A * Sometimes you'd want to map a Java primitive type to an
325N/A * optional element/attribute. Doing this makes it impossible
325N/A * to represent the absence of the property, thus you always
325N/A * end up producing the value when you marshal to XML.
325N/A *
325N/A * For example,
325N/A * <pre>
325N/A * {@link XmlElement}
325N/A * class Foo {
325N/A * {@link XmlElement}
325N/A * int x;
325N/A * }
325N/A *
325N/A * marshaller.marshal(new Foo());
325N/A * </pre>
325N/A * and you get:
325N/A * <pre><xmp>
325N/A * <foo><x>0</x></foo>
325N/A * </xmp></pre>
325N/A *
325N/A * <p>
325N/A * By creating a side boolean field/property that has this annotation,
325N/A * you can indicate the absence of the property by setting this boolean
325N/A * to false.
325N/A * <pre>
325N/A * {@link XmlElement}
325N/A * class Foo {
325N/A * {@link XmlElement}
325N/A * int x;
325N/A * {@link XmlIsSet}("x")
325N/A * boolean xIsPresent;
325N/A * }
325N/A *
325N/A * Foo f = new Foo();
325N/A * f.x = 5;
325N/A * f.xIsPresent = false;
325N/A *
325N/A * marshaller.marshal(f);
325N/A *
325N/A * <xmp>
325N/A * <foo/>
325N/A * </xmp>
325N/A *
325N/A * f.xIsPresent = true;
325N/A * <xmp>
325N/A * <foo><x>5</x></foo>
325N/A * </xmp>
325N/A * </pre>
325N/A *
325N/A * <p>
325N/A * A property/field annotated with {@link XmlIsSet} itself will not show up in XML.
325N/A * It is an error to use this annotation on the same property/field
325N/A * as {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue}, or {@link XmlElementRef},
325N/A * ...<b>TBD</b>.
325N/A *
325N/A * @deprecated
325N/A * this hasn't been implemented in the RI, and this hasn't been speced yet.
325N/A * I believe Joe asked for this feature. I'd like to drop this.
325N/A *
325N/A * @author Kohsuke Kawaguchi
325N/A */
325N/A@Retention(RUNTIME)
325N/A@Target({FIELD,METHOD})
325N/Apublic @interface XmlIsSet {
325N/A /**
325N/A * Specifies the name of the property to attach to.
325N/A */
325N/A String value();
325N/A}