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 <a href='...'>drive</a> 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}