001/*
002 * Copyright (c) 2004-2010, Kohsuke Kawaguchi
003 * All rights reserved.
004 *
005 * Redistribution and use in source and binary forms, with or without modification, are permitted provided
006 * that the following conditions are met:
007 *
008 *     * Redistributions of source code must retain the above copyright notice, this list of
009 *       conditions and the following disclaimer.
010 *     * Redistributions in binary form must reproduce the above copyright notice, this list of
011 *       conditions and the following disclaimer in the documentation and/or other materials
012 *       provided with the distribution.
013 *
014 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
015 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
016 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
017 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
018 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
019 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
020 * IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
021 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
022 */
023
024package org.kohsuke.stapler.export;
025
026import java.lang.annotation.Retention;
027import java.lang.annotation.RetentionPolicy;
028import java.lang.annotation.Documented;
029import java.lang.annotation.Target;
030import static java.lang.annotation.ElementType.FIELD;
031import static java.lang.annotation.ElementType.METHOD;
032
033/**
034 * Mark the field or the getter method whose value gets exposed
035 * to the remote API.
036 *
037 * @author Kohsuke Kawaguchi
038 * @see ExportedBean
039 */
040@Retention(RetentionPolicy.RUNTIME)
041@Documented
042@Target({FIELD, METHOD})
043public @interface Exported {
044    /**
045     * Controls how visible this property is.
046     *
047     * <p>
048     * If the value is 1, the property will be
049     * visible only when the current model object is exposed as the
050     * top-level object.
051     * <p>
052     * If the value is 2, in addition to above, the property will still
053     * be visible if the current model object is exposed as the 2nd-level
054     * object.
055     * <p>
056     * And the rest goes in the same way. If the value is N, the object
057     * is exposed as the Nth level object.
058     *
059     * <p>
060     * The default value of this property is determined by
061     * {@link ExportedBean#defaultVisibility()}.
062     *
063     * <p>
064     * So bigger the number, more important the property is.
065     */
066    int visibility() default 0;
067
068    /**
069     * Name of the exposed property.
070     * <p>
071     * This token is used as the XML element name or the JSON property name.
072     * The default is to use the Java property name.
073     */
074    String name() default "";
075
076    /**
077     * Visibility adjustment for traversing this property.
078     *
079     * <p>
080     * If true, visiting this property won't increase the depth count,
081     * so the referenced object is exported as if it were a part of this
082     * object.
083     *
084     * <p>
085     * This flag can be used to selectively expand the subtree to be
086     * returned to the client.
087     */
088    boolean inline() default false;
089
090    /**
091     * Include an object referenced by this property as if all its properties
092     * are merged into properties of the current object.
093     *
094     * <p>
095     * Any duplicate properties from the referenced object will be masked.
096     */
097    boolean merge() default false;
098
099    /**
100     * If the value is null, don't even write the property.
101     *
102     * By default, the property will be produced with null value, such as this:
103     * <pre>
104     * {
105     *     foo: null,
106     *     bar: "abc"
107     * }
108     * </pre>
109     *
110     * With this switch enabled on the 'foo' field, the above will become this:
111     * <pre>
112     * {
113     *     bar: "abc"
114     * }
115     * </pre>
116     */
117    boolean skipNull() default false;
118
119    /**
120     * If a string value "key/value" is given, produce a map in more verbose following form:
121     * "[{key:KEY1, value:VALUE1}, {key:KEY2, value:VALUE2}, ...]
122     * (whereas normally it produces more compact {KEY1:VALUE1, KEY2:VALUE2, ...}
123     *
124     * <p>
125     * So for example, if you say "name/value", you might see something like
126     * "[{name:"kohsuke", value:"abc"], ...}
127     *
128     * <p>
129     * The verbose form is useful/necessary when you use complex data structure as a key,
130     * or if the string representation of the key can contain letters that are unsafe in some flavours
131     * (such as XML, which prohibits a number of characters to be used as tag names.)
132     *
133     */
134    String verboseMap() default "";
135}