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.plaintext.annotation;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.annotation.*;
025import org.apache.juneau.plaintext.*;
026
027/**
028 * Annotation that can be applied to classes, fields, and methods to tweak how they are handled by {@link PlainTextSerializer} and {@link PlainTextParser}.
029 *
030 * <p>
031 * Can be used in the following locations:
032 * <ul>
033 *    <li>Marshalled classes/methods/fields.
034 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when an {@link #on()} value is specified.
035 * </ul>
036 *
037 */
038@Documented
039@Target({ TYPE, FIELD, METHOD })
040@Retention(RUNTIME)
041@Inherited
042@Repeatable(PlainTextAnnotation.Array.class)
043@ContextApply(PlainTextAnnotation.Apply.class)
044public @interface PlainText {
045
046   /**
047    * Optional description for the exposed API.
048    *
049    * @return The annotation value.
050    * @since 9.2.0
051    */
052   String[] description() default {};
053
054   /**
055    * Dynamically apply this annotation to the specified classes/methods/fields.
056    *
057    * <p>
058    * Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing class/method/field.
059    * It is ignored when the annotation is applied directly to classes/methods/fields.
060    *
061    * <h5 class='section'>Valid patterns:</h5>
062    * <ul class='spaced-list'>
063    *  <li>Classes:
064    *       <ul>
065    *          <li>Fully qualified:
066    *             <ul>
067    *                <li><js>"com.foo.MyClass"</js>
068    *             </ul>
069    *          <li>Fully qualified inner class:
070    *             <ul>
071    *                <li><js>"com.foo.MyClass$Inner1$Inner2"</js>
072    *             </ul>
073    *          <li>Simple:
074    *             <ul>
075    *                <li><js>"MyClass"</js>
076    *             </ul>
077    *          <li>Simple inner:
078    *             <ul>
079    *                <li><js>"MyClass$Inner1$Inner2"</js>
080    *                <li><js>"Inner1$Inner2"</js>
081    *                <li><js>"Inner2"</js>
082    *             </ul>
083    *       </ul>
084    *    <li>Methods:
085    *       <ul>
086    *          <li>Fully qualified with args:
087    *             <ul>
088    *                <li><js>"com.foo.MyClass.myMethod(String,int)"</js>
089    *                <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js>
090    *                <li><js>"com.foo.MyClass.myMethod()"</js>
091    *             </ul>
092    *          <li>Fully qualified:
093    *             <ul>
094    *                <li><js>"com.foo.MyClass.myMethod"</js>
095    *             </ul>
096    *          <li>Simple with args:
097    *             <ul>
098    *                <li><js>"MyClass.myMethod(String,int)"</js>
099    *                <li><js>"MyClass.myMethod(java.lang.String,int)"</js>
100    *                <li><js>"MyClass.myMethod()"</js>
101    *             </ul>
102    *          <li>Simple:
103    *             <ul>
104    *                <li><js>"MyClass.myMethod"</js>
105    *             </ul>
106    *          <li>Simple inner class:
107    *             <ul>
108    *                <li><js>"MyClass$Inner1$Inner2.myMethod"</js>
109    *                <li><js>"Inner1$Inner2.myMethod"</js>
110    *                <li><js>"Inner2.myMethod"</js>
111    *             </ul>
112    *       </ul>
113    *    <li>Fields:
114    *       <ul>
115    *          <li>Fully qualified:
116    *             <ul>
117    *                <li><js>"com.foo.MyClass.myField"</js>
118    *             </ul>
119    *          <li>Simple:
120    *             <ul>
121    *                <li><js>"MyClass.myField"</js>
122    *             </ul>
123    *          <li>Simple inner class:
124    *             <ul>
125    *                <li><js>"MyClass$Inner1$Inner2.myField"</js>
126    *                <li><js>"Inner1$Inner2.myField"</js>
127    *                <li><js>"Inner2.myField"</js>
128    *             </ul>
129    *       </ul>
130    *    <li>A comma-delimited list of anything on this list.
131    * </ul>
132    *
133    * <h5 class='section'>See Also:</h5><ul>
134    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
135    * </ul>
136    *
137    * @return The annotation value.
138    */
139   String[] on() default {};
140
141   /**
142    * Dynamically apply this annotation to the specified classes.
143    *
144    * <p>
145    * Identical to {@link #on()} except allows you to specify class objects instead of a strings.
146    *
147    * <h5 class='section'>See Also:</h5><ul>
148    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
149    * </ul>
150    *
151    * @return The annotation value.
152    */
153   Class<?>[] onClass() default {};
154}