001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.json;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * Annotation for specifying various JSON options for the JSON serializers and parsers.
026 *
027 * <p>
028 * Can be used in the following locations:
029 * <ul>
030 *    <li>Marshalled classes/methods/fields.
031 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link JsonApply @JsonApply}.
032 * </ul>
033 *
034 * <p>
035 * Can be used for the following:
036 * <ul class='spaced-list'>
037 *    <li>
038 *       Wrap bean instances inside wrapper object (e.g. <c>{'wrapperAttr':bean}</c>).
039 * </ul>
040 *
041 * <h5 class='section'>See Also:</h5><ul>
042 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JsonSupport">JSON</a>
043
044 * </ul>
045 */
046@Documented
047@Target({ TYPE, METHOD, FIELD })
048@Retention(RUNTIME)
049@Inherited
050public @interface Json {
051
052   /**
053    * Optional description for the exposed API.
054    *
055    * @return The annotation value.
056    * @since 9.2.0
057    */
058   String[] description() default {};
059
060   /**
061    * Wraps beans in a JSON object with the specified attribute name.
062    *
063    * <p>
064    * Applies only to {@link ElementType#TYPE}.
065    *
066    * <p>
067    * This annotation can be applied to beans as well as other objects serialized to other types (e.g. strings).
068    *
069    * <h5 class='figure'>Example:</h5>
070    * <p class='bjava'>
071    *    <ja>@Json</ja>(wrapperAttr=<js>"myWrapper"</js>)
072    *    <jk>public class</jk> MyBean {
073    *       <jk>public int</jk> <jf>f1</jf> = 123;
074    *    }
075    * </p>
076    *
077    * <p>
078    * Without the <ja>@Json</ja> annotations, serializing this bean as JSON would have produced the following...
079    * <p class='bjson'>
080    *    {
081    *       f1: 123
082    *    }
083    * </p>
084    *
085    * <p>
086    * With the annotations, serializing this bean as JSON produces the following...
087    * <p class='bjson'>
088    *    {
089    *       myWrapper: {
090    *          f1: 123
091    *       }
092    *    }
093    * </p>
094    *
095    * @return The annotation value.
096    */
097   String wrapperAttr() default "";
098}