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;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * Identifies examples for POJOs.
026 *
027 * <p>
028 * Can be used in the following locations:
029 * <ul>
030 *    <li>Static method that returns an example of the POJO.
031 *    <li>Static field that contains an example of the POJO.
032 *    <li>On a class.
033 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link ExampleApply @ExampleApply}.
034 * </ul>
035 *
036 * <h5 class='figure'>Examples:</h5>
037 * <p class='bjava'>
038 *    <jc>// On a static method.</jc>
039 *    <jk>public class</jk> A {
040 *
041 *       <ja>@Example</ja>
042 *       <jk>public static</jk> A example() {
043 *          <jk>return new</jk> A().foo(<js>"bar"</js>).baz(123);
044 *       }
045 *
046 *       ...
047 *    }
048 *
049 *    <jc>// On a static field.</jc>
050 *    <jk>public class</jk> B {
051 *
052 *       <ja>@Example</ja>
053 *       <jk>public static</jk> B EXAMPLE = <jk>new</jk> B().foo(<js>"bar"</js>).baz(123);
054 *
055 *       ...
056 *    }
057 *
058 *    <jc>// On a class.</jc>
059 *    <ja>@Example</ja>(<js>"{foo:'bar',baz:123}"</js>)
060 *    <jk>public class</jk> C {...}
061 * </p>
062 *
063 */
064@Documented
065@Target({ FIELD, METHOD, TYPE })
066@Retention(RUNTIME)
067@Inherited
068public @interface Example {
069
070   /**
071    * Optional description for the exposed API.
072    *
073    * @return The annotation value.
074    * @since 9.2.0
075    */
076   String[] description() default {};
077
078   /**
079    * An example of a POJO class.
080    *
081    * <p>
082    * Format is Lax-JSON.
083    *
084    * <p>
085    * This value is only used when the annotation is used on a type.
086    *
087    * @return The annotation value.
088    */
089   String value() default "";
090}