Thu, 31 Aug 2017 15:18:52 +0800
merge
1 /*
2 * Copyright (c) 1997, 2011, 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 */
26 package com.sun.xml.internal.bind.annotation;
28 import java.lang.annotation.Retention;
29 import java.lang.annotation.Target;
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;
36 import static java.lang.annotation.ElementType.FIELD;
37 import static java.lang.annotation.ElementType.METHOD;
38 import static java.lang.annotation.RetentionPolicy.RUNTIME;
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 }