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.html.annotation;
014
015import static java.lang.annotation.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019
020import org.apache.juneau.annotation.*;
021import org.apache.juneau.html.*;
022
023/**
024 * Annotation that can be applied to classes, fields, and methods to tweak how they are handled by {@link HtmlSerializer}.
025 *
026 * <p>
027 * Can be used in the following locations:
028 * <ul>
029 *    <li>Marshalled classes/methods/fields.
030 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when an {@link #on()} value is specified.
031 * </ul>
032 *
033 * <h5 class='section'>See Also:</h5><ul>
034 *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.HtmlAnnotation">@Html Annotation</a>
035 *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.HtmlDetails">HTML Details</a>
036 * </ul>
037 */
038@Documented
039@Target({TYPE,FIELD,METHOD})
040@Retention(RUNTIME)
041@Inherited
042@Repeatable(HtmlAnnotation.Array.class)
043@ContextApply(HtmlAnnotation.Apply.class)
044public @interface Html {
045
046   /**
047    * Use the specified anchor text when serializing a URI.
048    *
049    * <p>
050    * The text can contain any bean property values resolved through variables of the form <js>"{property-name}"</js>.
051    *
052    * <h5 class='figure'>Example:</h5>
053    * <p class='bjava'>
054    *    <jc>// Produces &lt;a href&#61;'...'&gt;drive&lt;/a&gt; when serialized to HTML.</jc>
055    *    <ja>@Html</ja>(anchorText=<js>"drive"</js>)
056    *    <ja>@URI</ja> <jc>// Treat property as a URL</jc>
057    *    <jk>public</jk> String getDrive() {...}
058    * </p>
059    *
060    * <p>
061    * This overrides the behavior specified by {@link org.apache.juneau.html.HtmlSerializer.Builder#uriAnchorText(AnchorText)}.
062    *
063    * @return The annotation value.
064    */
065   String anchorText() default "";
066
067   /**
068    * Specifies what format to use for the HTML element.
069    *
070    * @return The annotation value.
071    */
072   HtmlFormat format() default HtmlFormat.HTML;
073
074   /**
075    * Adds a hyperlink to a bean property when rendered as HTML.
076    *
077    * <p>
078    * The text can contain any bean property values resolved through variables of the form <js>"{property-name}"</js>.
079    *
080    * <p>
081    * The URLs can be any of the following forms:
082    * <ul>
083    *    <li>Absolute - e.g. <js>"http://host:123/myContext/myServlet/myPath"</js>
084    *    <li>Context-root-relative - e.g. <js>"/myContext/myServlet/myPath"</js>
085    *    <li>Context-relative - e.g. <js>"context:/myServlet/myPath"</js>
086    *    <li>Servlet-relative - e.g. <js>"servlet:/myPath"</js>
087    *    <li>Path-info-relative - e.g. <js>"myPath"</js>
088    * </ul>
089    *
090    * <h5 class='figure'>Example:</h5>
091    * <p class='bjava'>
092    *    <jk>public class</jk> FileSpace {
093    *
094    *       <ja>@Html</ja>(link=<js>"servlet:/drive/{drive}"</js>)
095    *       <jk>public</jk> String getDrive() {
096    *          ...;
097    *       }
098    *    }
099    * </p>
100    *
101    * @return The annotation value.
102    */
103   String link() default "";
104
105   /**
106    * When <jk>true</jk>, don't add headers to tables.
107    *
108    * <h5 class='section'>See Also:</h5><ul>
109    *    <li class='jm'>{@link org.apache.juneau.html.HtmlSerializer.Builder#addKeyValueTableHeaders()}
110    * </ul>
111    *
112    * @return The annotation value.
113    */
114   boolean noTableHeaders() default false;
115
116   /**
117    * When <jk>true</jk>, collections of beans should be rendered as trees instead of tables.
118    *
119    * <p>
120    * Default is <jk>false</jk>.
121    *
122    * @return The annotation value.
123    */
124   boolean noTables() default false;
125
126   /**
127    * Dynamically apply this annotation to the specified classes/methods/fields.
128    *
129    * <p>
130    * Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing class/method/field.
131    * It is ignored when the annotation is applied directly to classes/methods/fields.
132    *
133    * <h5 class='section'>Valid patterns:</h5>
134    * <ul class='spaced-list'>
135    *  <li>Classes:
136    *       <ul>
137    *          <li>Fully qualified:
138    *             <ul>
139    *                <li><js>"com.foo.MyClass"</js>
140    *             </ul>
141    *          <li>Fully qualified inner class:
142    *             <ul>
143    *                <li><js>"com.foo.MyClass$Inner1$Inner2"</js>
144    *             </ul>
145    *          <li>Simple:
146    *             <ul>
147    *                <li><js>"MyClass"</js>
148    *             </ul>
149    *          <li>Simple inner:
150    *             <ul>
151    *                <li><js>"MyClass$Inner1$Inner2"</js>
152    *                <li><js>"Inner1$Inner2"</js>
153    *                <li><js>"Inner2"</js>
154    *             </ul>
155    *       </ul>
156    *    <li>Methods:
157    *       <ul>
158    *          <li>Fully qualified with args:
159    *             <ul>
160    *                <li><js>"com.foo.MyClass.myMethod(String,int)"</js>
161    *                <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js>
162    *                <li><js>"com.foo.MyClass.myMethod()"</js>
163    *             </ul>
164    *          <li>Fully qualified:
165    *             <ul>
166    *                <li><js>"com.foo.MyClass.myMethod"</js>
167    *             </ul>
168    *          <li>Simple with args:
169    *             <ul>
170    *                <li><js>"MyClass.myMethod(String,int)"</js>
171    *                <li><js>"MyClass.myMethod(java.lang.String,int)"</js>
172    *                <li><js>"MyClass.myMethod()"</js>
173    *             </ul>
174    *          <li>Simple:
175    *             <ul>
176    *                <li><js>"MyClass.myMethod"</js>
177    *             </ul>
178    *          <li>Simple inner class:
179    *             <ul>
180    *                <li><js>"MyClass$Inner1$Inner2.myMethod"</js>
181    *                <li><js>"Inner1$Inner2.myMethod"</js>
182    *                <li><js>"Inner2.myMethod"</js>
183    *             </ul>
184    *       </ul>
185    *    <li>Fields:
186    *       <ul>
187    *          <li>Fully qualified:
188    *             <ul>
189    *                <li><js>"com.foo.MyClass.myField"</js>
190    *             </ul>
191    *          <li>Simple:
192    *             <ul>
193    *                <li><js>"MyClass.myField"</js>
194    *             </ul>
195    *          <li>Simple inner class:
196    *             <ul>
197    *                <li><js>"MyClass$Inner1$Inner2.myField"</js>
198    *                <li><js>"Inner1$Inner2.myField"</js>
199    *                <li><js>"Inner2.myField"</js>
200    *             </ul>
201    *       </ul>
202    *    <li>A comma-delimited list of anything on this list.
203    * </ul>
204    *
205    * <h5 class='section'>See Also:</h5><ul>
206    *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
207    * </ul>
208    *
209    * @return The annotation value.
210    */
211   String[] on() default {};
212
213   /**
214    * Dynamically apply this annotation to the specified classes.
215    *
216    * <p>
217    * Identical to {@link #on()} except allows you to specify class objects instead of a strings.
218    *
219    * <h5 class='section'>See Also:</h5><ul>
220    *    <li class='link'><a class="doclink" href="../../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
221    * </ul>
222    *
223    * @return The annotation value.
224    */
225   Class<?>[] onClass() default {};
226
227   /**
228    * Associates an {@link HtmlRender} with a bean property for custom HTML rendering of the property.
229    *
230    * <p>
231    * This annotation applies to bean properties and classes.
232    *
233    * @return The annotation value.
234    */
235   @SuppressWarnings("rawtypes")
236   Class<? extends HtmlRender> render() default HtmlRender.class;
237}