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