jdk8-mips64-public/jaxws: src/share/jaxws_classes/com/sun/xml/internal/bind/annotation/XmlIsSet.java@e530533619ec

     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 }

Mercurial > jdk8-mips64-public > jaxws / file revision