1 /*
   2  * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.xml.internal.bind.annotation;
  27 
  28 import java.lang.annotation.Retention;
  29 import java.lang.annotation.Target;
  30 
  31 import javax.xml.bind.annotation.XmlAttribute;
  32 import javax.xml.bind.annotation.XmlElement;
  33 import javax.xml.bind.annotation.XmlElementRef;
  34 import javax.xml.bind.annotation.XmlValue;
  35 
  36 import static java.lang.annotation.ElementType.FIELD;
  37 import static java.lang.annotation.ElementType.METHOD;
  38 import static java.lang.annotation.RetentionPolicy.RUNTIME;
  39 
  40 /**
  41  * Designates a boolean field/property as a flag to indicate
  42  * whether another property is present or not.
  43  *
  44  * <p>
  45  * Sometimes you'd want to map a Java primitive type to an
  46  * optional element/attribute. Doing this makes it impossible
  47  * to represent the absence of the property, thus you always
  48  * end up producing the value when you marshal to XML.
  49  *
  50  * For example,
  51  * <pre>
  52  * {@link XmlElement}
  53  * class Foo {
  54  *      {@link XmlElement}
  55  *      int x;
  56  * }
  57  *
  58  * marshaller.marshal(new Foo());
  59  * </pre>
  60  * and you get:
  61  * <pre><xmp>
  62  * <foo><x>0</x></foo>
  63  * </xmp></pre>
  64  *
  65  * <p>
  66  * By creating a side boolean field/property that has this annotation,
  67  * you can indicate the absence of the property by setting this boolean
  68  * to false.
  69  * <pre>
  70  * {@link XmlElement}
  71  * class Foo {
  72  *      {@link XmlElement}
  73  *      int x;
  74  *      {@link XmlIsSet}("x")
  75  *      boolean xIsPresent;
  76  * }
  77  *
  78  * Foo f = new Foo();
  79  * f.x = 5;
  80  * f.xIsPresent = false;
  81  *
  82  * marshaller.marshal(f);
  83  *
  84  * <xmp>
  85  * <foo/>
  86  * </xmp>
  87  *
  88  * f.xIsPresent = true;
  89  * <xmp>
  90  * <foo><x>5</x></foo>
  91  * </xmp>
  92  * </pre>
  93  *
  94  * <p>
  95  * A property/field annotated with {@link XmlIsSet} itself will not show up in XML.
  96  * It is an error to use this annotation on the same property/field
  97  * as {@link XmlElement}, {@link XmlAttribute}, {@link XmlValue}, or {@link XmlElementRef},
  98  * ...<b>TBD</b>.
  99  *
 100  * @deprecated
 101  *      this hasn't been implemented in the RI, and this hasn't been speced yet.
 102  *      I believe Joe asked for this feature. I'd like to drop this.
 103  *
 104  * @author Kohsuke Kawaguchi
 105  */
 106 @Retention(RUNTIME)
 107 @Target({FIELD,METHOD})
 108 public @interface XmlIsSet {
 109     /**
 110      * Specifies the name of the property to attach to.
 111      */
 112     String value();
 113 }