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.html; 018 019import static org.apache.juneau.commons.utils.Shorts.*; 020import static org.apache.juneau.commons.utils.SystemUtils.*; 021 022import java.util.*; 023import java.util.concurrent.*; 024import java.util.concurrent.atomic.*; 025 026import org.apache.juneau.commons.bean.*; 027import org.apache.juneau.commons.collections.*; 028import org.apache.juneau.marshall.*; 029import org.apache.juneau.marshall.serializer.*; 030import org.apache.juneau.marshall.xml.*; 031 032/** 033 * Serializes POJO models to HTML. 034 * 035 * <h2 class='topic'>Media types</h2> 036 * <p> 037 * Handles <c>Accept</c> types: <bc>text/html</bc> 038 * <p> 039 * Produces <c>Content-Type</c> types: <bc>text/html</bc> 040 * 041 * <h2 class='topic'>Description</h2> 042 * <p> 043 * The conversion is as follows... 044 * <ul class='spaced-list'> 045 * <li> 046 * {@link Map Maps} (e.g. {@link HashMap}, {@link TreeMap}) and beans are converted to HTML tables with 047 * 'key' and 'value' columns. 048 * <li> 049 * {@link Collection Collections} (e.g. {@link HashSet}, {@link LinkedList}) and Java arrays are converted 050 * to HTML ordered lists. 051 * <li> 052 * {@code Collections} of {@code Maps} and beans are converted to HTML tables with keys as headers. 053 * <li> 054 * Everything else is converted to text. 055 * </ul> 056 * 057 * <p> 058 * This serializer provides several serialization options. Typically, one of the predefined <jsf>DEFAULT</jsf> 059 * serializers will be sufficient. 060 * However, custom serializers can be constructed to fine-tune behavior. 061 * 062 * <p> 063 * The {@link HtmlLink} annotation can be used on beans to add hyperlinks to the output. 064 * 065 * <h2 class='topic'>Behavior-specific subclasses</h2> 066 * <p> 067 * The following direct subclasses are provided for convenience: 068 * <ul class='spaced-list'> 069 * <li> 070 * {@link Sq} - Default serializer, single quotes. 071 * <li> 072 * {@link SqReadable} - Default serializer, single quotes, whitespace added. 073 * </ul> 074 * 075 * <h2 class='section'>Example:</h2> 076 * <p class='bjava'> 077 * <jc>// Use one of the default serializers to serialize a POJO</jc> 078 * String <jv>html</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>.write(<jv>someObject</jv>); 079 * 080 * <jc>// Create a custom serializer that doesn't use whitespace and newlines</jc> 081 * HtmlSerializer <jv>serializer</jv> = HtmlSerializer.<jsm>create</jsm>().ws().build(); 082 * 083 * <jc>// Same as above, except uses cloning</jc> 084 * HtmlSerializer <jv>serializer</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>.copy().ws().build(); 085 * 086 * <jc>// Serialize POJOs to HTML</jc> 087 * 088 * <jc>// Produces: </jc> 089 * <jc>// <ul><li>1<li>2<li>3</ul></jc> 090 * List <jv>list</jv> = JsonList.<jsm>of</jsm>(1, 2, 3); 091 * String <jv>html</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>.write(<jv>list</jv>); 092 * 093 * <jc>// Produces: </jc> 094 * <jc>// <table> </jc> 095 * <jc>// <tr><th>firstName</th><th>lastName</th></tr> </jc> 096 * <jc>// <tr><td>Bob</td><td>Costas</td></tr> </jc> 097 * <jc>// <tr><td>Billy</td><td>TheKid</td></tr> </jc> 098 * <jc>// <tr><td>Barney</td><td>Miller</td></tr> </jc> 099 * <jc>// </table> </jc> 100 * <jv>html</jv> = JsonList.<jsm>of</jsm>( 101 * JsonMap.<jsm>ofText</jsm>(<js>"{firstName:'Bob',lastName:'Costas'}"</js>), 102 * JsonMap.<jsm>ofText</jsm>(<js>"{firstName:'Billy',lastName:'TheKid'}"</js>), 103 * JsonMap.<jsm>ofText</jsm>(<js>"{firstName:'Barney',lastName:'Miller'}"</js>) 104 * ); 105 * String <jv>html</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>.write(<jv>list</jv>); 106 * 107 * <jc>// Produces: </jc> 108 * <jc>// <table> </jc> 109 * <jc>// <tr><th>key</th><th>value</th></tr> </jc> 110 * <jc>// <tr><td>foo</td><td>bar</td></tr> </jc> 111 * <jc>// <tr><td>baz</td><td>123</td></tr> </jc> 112 * <jc>// </table> </jc> 113 * Map <jv>map</jv> = JsonMap.<jsm>ofText</jsm>(<js>"{foo:'bar',baz:123}"</js>); 114 * String <jv>html</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>.write(<jv>map</jv>); 115 * 116 * <jc>// HTML elements can be nested arbitrarily deep</jc> 117 * <jc>// Produces: </jc> 118 * <jc>// <table> </jc> 119 * <jc>// <tr><th>key</th><th>value</th></tr> </jc> 120 * <jc>// <tr><td>foo</td><td>bar</td></tr> </jc> 121 * <jc>// <tr><td>baz</td><td>123</td></tr> </jc> 122 * <jc>// <tr><td>someNumbers</td><td><ul><li>1<li>2<li>3</ul></td></tr> </jc> 123 * <jc>// <tr><td>someSubMap</td><td> </jc> 124 * <jc>// <table> </jc> 125 * <jc>// <tr><th>key</th><th>value</th></tr> </jc> 126 * <jc>// <tr><td>a</td><td>b</td></tr> </jc> 127 * <jc>// </table> </jc> 128 * <jc>// </td></tr> </jc> 129 * <jc>// </table> </jc> 130 * Map <jv>map</jv> = JsonMap.<jsm>ofText</jsm>(<js>"{foo:'bar',baz:123}"</js>); 131 * <jv>map</jv>.put(<js>"someNumbers"</js>, JsonList.<jsm>of</jsm>(1, 2, 3)); 132 * <jv>map</jv>.put(<js>"someSubMap"</js>, JsonMap.<jsm>ofText</jsm>(<js>"{a:'b'}"</js>)); 133 * String <jv>html</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>.write(<jv>map</jv>); 134 * </p> 135 * 136 * <h2 class='section'>Notes:</h2><ul> 137 * <li class='note'>This class is thread safe and reusable. 138 * </ul> 139 * 140 * <h2 class='section'>See Also:</h2><ul> 141 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlSupport">HTML</a> 142 143 * </ul> 144 */ 145@SuppressWarnings({ 146 "java:S110", // Inheritance depth acceptable for this class hierarchy 147 "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants 148 "java:S9149" // Per-format static factories intentionally shadow the parent's. 149}) 150public class HtmlSerializer extends XmlSerializer implements HtmlMetaProvider { 151 152 /** 153 * Builder class. 154 */ 155 @SuppressWarnings({ 156 "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name. 157 }) 158 public abstract static class Builder<SELF extends Builder<SELF>> extends XmlSerializer.Builder<SELF> { 159 160 private static final Set<String> DEFAULT_URI_SCHEMES = Set.of("http", "https", "mailto", "tel"); 161 162 private static final Cache<HashKey,HtmlSerializer> CACHE = Cache.of(HashKey.class, HtmlSerializer.class).build(); 163 164 private boolean addBeanTypesHtml; 165 private boolean addKeyValueTableHeaders; 166 private boolean disableDetectLabelParameters; 167 private boolean disableDetectLinksInStrings; 168 private String labelParameter; 169 private AnchorText uriAnchorText; 170 private Set<String> uriSchemes; 171 172 /** 173 * Constructor, default settings. 174 */ 175 protected Builder() { 176 produces("text/html"); 177 addBeanTypesHtml = env("HtmlSerializer.addBeanTypesHtml", false); 178 addKeyValueTableHeaders = env("HtmlSerializer.addKeyValueTableHeaders", false); 179 disableDetectLabelParameters = env("HtmlSerializer.disableDetectLabelParameters", false); 180 disableDetectLinksInStrings = env("HtmlSerializer.disableDetectLinksInStrings", false); 181 uriAnchorText = env("HtmlSerializer.uriAnchorText", AnchorText.TO_STRING); 182 labelParameter = env("HtmlSerializer.labelParameter", "label"); 183 uriSchemes = DEFAULT_URI_SCHEMES; 184 } 185 186 /** 187 * Copy constructor. 188 * 189 * @param copyFrom The builder to copy from. 190 * <br>Cannot be <jk>null</jk>. 191 */ 192 protected Builder(Builder<?> copyFrom) { 193 super(reqnn("copyFrom", copyFrom)); 194 addBeanTypesHtml = copyFrom.addBeanTypesHtml; 195 addKeyValueTableHeaders = copyFrom.addKeyValueTableHeaders; 196 disableDetectLabelParameters = copyFrom.disableDetectLabelParameters; 197 disableDetectLinksInStrings = copyFrom.disableDetectLinksInStrings; 198 labelParameter = copyFrom.labelParameter; 199 uriAnchorText = copyFrom.uriAnchorText; 200 uriSchemes = copyFrom.uriSchemes; 201 } 202 203 /** 204 * Copy constructor. 205 * 206 * @param copyFrom The bean to copy from. 207 * <br>Cannot be <jk>null</jk>. 208 */ 209 protected Builder(HtmlSerializer copyFrom) { 210 super(reqnn("copyFrom", copyFrom)); 211 addBeanTypesHtml = copyFrom.addBeanTypesHtml; 212 addKeyValueTableHeaders = copyFrom.addKeyValueTableHeaders; 213 disableDetectLabelParameters = ! copyFrom.detectLabelParameters; 214 disableDetectLinksInStrings = ! copyFrom.detectLinksInStrings; 215 labelParameter = copyFrom.labelParameter; 216 uriAnchorText = copyFrom.uriAnchorText; 217 uriSchemes = copyFrom.uriSchemes; 218 } 219 220 /** 221 * Add <js>"_type"</js> properties when needed. 222 * 223 * <p> 224 * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred 225 * through reflection. 226 * 227 * <p> 228 * When present, this value overrides the {@link org.apache.juneau.marshall.serializer.Serializer.Builder#addBeanTypes() Serializer.Builder#addBeanTypes()} setting and is 229 * provided to customize the behavior of specific serializers in a {@link SerializerSet}. 230 * 231 * @return This object. 232 */ 233 public SELF addBeanTypesHtml() { 234 return addBeanTypesHtml(true); 235 } 236 237 /** 238 * Same as {@link #addBeanTypesHtml()} but allows you to explicitly specify the value. 239 * 240 * @param value The value for this setting. 241 * @return This object. 242 */ 243 public SELF addBeanTypesHtml(boolean value) { 244 addBeanTypesHtml = value; 245 return self(); 246 } 247 248 /** 249 * <i><l>HtmlSerializer</l> configuration property: </i> Add key/value headers on bean/map tables. 250 * 251 * <p> 252 * When enabled, <bc>key</bc> and <bc>value</bc> column headers are added to tables. 253 * 254 * <h4 class='section'>Example:</h4> 255 * <p class='bjson'> 256 * <jc>// Our bean class.</jc> 257 * <jk>public class</jk> MyBean { 258 * <jk>public</jk> String <jf>f1</jf> = <js>"foo"</js>; 259 * <jk>public</jk> String <jf>f2</jf> = <js>"bar"</js>; 260 * } 261 * 262 * <jc>// Serializer without headers.</jc> 263 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer.<jsf>DEFAULT</jsf>; 264 * 265 * <jc>// Serializer with headers.</jc> 266 * WriterSerializer <jv>serializer2</jv> = HtmlSerializer 267 * .<jsm>create</jsm>() 268 * .addKeyValueTableHeaders() 269 * .build(); 270 * 271 * String <jv>withoutHeaders</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 272 * String <jv>withHeaders</jv> = <jv>serializer2</jv>.write(<jk>new</jk> MyBean()); 273 * </p> 274 * 275 * <p> 276 * The following shows the difference between the two generated outputs: 277 * 278 * <table class='styled'> 279 * <caption>Serialized output without headers</caption> 280 * <tr> 281 * <th><c>withoutHeaders</c></th> 282 * <th><c>withHeaders</c></th> 283 * </tr> 284 * <tr> 285 * <td> 286 * <table class='unstyled'> 287 * <caption>Nested table without headers (1)</caption> 288 * <tr><td>f1</td><td>foo</td></tr> 289 * <tr><td>f2</td><td>bar</td></tr> 290 * </table> 291 * </td> 292 * <td> 293 * <table class='unstyled'> 294 * <caption>Nested table without headers (2)</caption> 295 * <tr><th>key</th><th>value</th></tr> 296 * <tr><td>f1</td><td>foo</td></tr> 297 * <tr><td>f2</td><td>bar</td></tr> 298 * </table> 299 * </td> 300 * </tr> 301 * </table> 302 * 303 * @return This object. 304 */ 305 public SELF addKeyValueTableHeaders() { 306 return addKeyValueTableHeaders(true); 307 } 308 309 /** 310 * Same as {@link #addKeyValueTableHeaders()} but allows you to explicitly specify the value. 311 * 312 * @param value The value for this setting. 313 * @return This object. 314 */ 315 public SELF addKeyValueTableHeaders(boolean value) { 316 addKeyValueTableHeaders = value; 317 return self(); 318 } 319 320 @Override /* Overridden from Context.Builder<?> */ 321 public HtmlSerializer build() { 322 return cache(CACHE).build(HtmlSerializer.class); 323 } 324 325 @Override /* Overridden from Context.Builder<?> */ 326 public abstract SELF copy(); 327 328 /** 329 * <i><l>HtmlSerializer</l> configuration property: </i> Dont look for link labels in URIs. 330 * 331 * <p> 332 * Disables the feature where if the URL has a label parameter (e.g. <js>"?label=foobar"</js>), then use that as the anchor text of the link. 333 * 334 * <p> 335 * The parameter name can be changed via the {@link #labelParameter(String)} property. 336 * 337 * <h4 class='section'>Example:</h4> 338 * <p class='bjson'> 339 * <jc>// Our bean class with a property containing what looks like a URL.</jc> 340 * <jk>public class</jk> MyBean { 341 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org?label=Apache%20Foundation"</js>); 342 * } 343 * 344 * <jc>// Serializer with label detection.</jc> 345 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer 346 * .<jsm>create</jsm>() 347 * .addKeyValueTableHeaders() 348 * .build(); 349 * 350 * <jc>// Serializer without label detection.</jc> 351 * WriterSerializer <jv>serializer2</jv> = HtmlSerializer 352 * .<jsm>create</jsm>() 353 * .addKeyValueTableHeaders() 354 * .disableDetectLabelParameters() 355 * .build(); 356 * 357 * String <jv>withLabels</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 358 * String <jv>withoutLabels</jv> = <jv>serializer2</jv>.write(<jk>new</jk> MyBean()); 359 * </p> 360 * 361 * <p> 362 * The following shows the difference between the two generated outputs. 363 * <br>Note that they're both hyperlinks, but the anchor text differs: 364 * 365 * <table class='styled'> 366 * <caption>Serialized output with labels</caption> 367 * <tr> 368 * <th><c>withLabels</c></th> 369 * <th><c>withoutLabels</c></th> 370 * </tr> 371 * <tr> 372 * <td> 373 * <table class='unstyled'> 374 * <caption>Nested table with labels (1)</caption> 375 * <tr><th>key</th><th>value</th></tr> 376 * <tr><td>f1</td><td><a href='http://www.apache.org?label=Apache%20Foundation'>Apache Foundation</a></td></tr> 377 * </table> 378 * </td> 379 * <td> 380 * <table class='unstyled'> 381 * <caption>Nested table with labels (2)</caption> 382 * <tr><th>key</th><th>value</th></tr> 383 * <tr><td>f1</td><td><a href='http://www.apache.org?label=Apache%20Foundation'>http://www.apache.org?label=Apache%20Foundation</a></td></tr> 384 * </table> 385 * </td> 386 * </tr> 387 * </table> 388 * 389 * @return This object. 390 */ 391 public SELF disableDetectLabelParameters() { 392 return disableDetectLabelParameters(true); 393 } 394 395 /** 396 * Same as {@link #disableDetectLabelParameters()} but allows you to explicitly specify the value. 397 * 398 * @param value The value for this setting. 399 * @return This object. 400 */ 401 public SELF disableDetectLabelParameters(boolean value) { 402 disableDetectLabelParameters = value; 403 return self(); 404 } 405 406 /** 407 * <i><l>HtmlSerializer</l> configuration property: </i> Don't look for URLs in {@link String Strings}. 408 * 409 * <p> 410 * Disables the feature where if a string looks like a URL (i.e. starts with <js>"http://"</js> or <js>"https://"</js>, then treat it like a URL 411 * and make it into a hyperlink based on the rules specified by {@link Builder#uriAnchorText(AnchorText)}. 412 * 413 * <h4 class='section'>Example:</h4> 414 * <p class='bjson'> 415 * <jc>// Our bean class with a property containing what looks like a URL.</jc> 416 * <jk>public class</jk> MyBean { 417 * <jk>public</jk> String <jf>f1</jf> = <js>"http://www.apache.org"</js>; 418 * } 419 * 420 * <jc>// Serializer with link detection.</jc> 421 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer 422 * .<jsm>create</jsm>() 423 * .addKeyValueTableHeaders() 424 * .build(); 425 * 426 * <jc>// Serializer without link detection.</jc> 427 * WriterSerializer <jv>serializer2</jv> = HtmlSerializer 428 * .<jsm>create</jsm>() 429 * .addKeyValueTableHeaders() 430 * .disableDetectLinksInStrings() 431 * .build(); 432 * 433 * String <jv>withLinks</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 434 * String <jv>withoutLinks</jv> = <jv>serializer2</jv>.write(<jk>new</jk> MyBean()); 435 * </p> 436 * 437 * <p> 438 * The following shows the difference between the two generated outputs: 439 * 440 * <table class='styled'> 441 * <caption>Serialized output with links</caption> 442 * <tr> 443 * <th><c>withLinks</c></th> 444 * <th><c>withoutLinks</c></th> 445 * </tr> 446 * <tr> 447 * <td> 448 * <table class='unstyled'> 449 * <caption>Nested table with links (1)</caption> 450 * <tr><th>key</th><th>value</th></tr> 451 * <tr><td>f1</td><td><a href='http://www.apache.org'>http://www.apache.org</a></td></tr> 452 * </table> 453 * </td> 454 * <td> 455 * <table class='unstyled'> 456 * <caption>Nested table with links (2)</caption> 457 * <tr><th>key</th><th>value</th></tr> 458 * <tr><td>f1</td><td>http://www.apache.org</td></tr> 459 * </table> 460 * </td> 461 * </tr> 462 * </table> 463 * 464 * @return This object. 465 */ 466 public SELF disableDetectLinksInStrings() { 467 return disableDetectLinksInStrings(true); 468 } 469 470 /** 471 * Same as {@link #disableDetectLinksInStrings()} but allows you to explicitly specify the value. 472 * 473 * @param value The value for this setting. 474 * @return This object. 475 */ 476 public SELF disableDetectLinksInStrings(boolean value) { 477 disableDetectLinksInStrings = value; 478 return self(); 479 } 480 481 @Override /* Overridden from Context.Builder<?> */ 482 public HashKey hashKey() { 483 // @formatter:off 484 return HashKey.of( 485 super.hashKey(), 486 addBeanTypesHtml, 487 addKeyValueTableHeaders, 488 disableDetectLabelParameters, 489 disableDetectLinksInStrings, 490 labelParameter, 491 uriAnchorText, 492 uriSchemes 493 ); 494 // @formatter:on 495 } 496 497 /** 498 * <i><l>HtmlSerializer</l> configuration property: </i> Link label parameter name. 499 * 500 * <p> 501 * The parameter name to look for when resolving link labels}. 502 * 503 * @param value 504 * The new value for this property. 505 * <br>Cannot be <jk>null</jk>. 506 * <br>The default is <js>"label"</js>. 507 * @return This object. 508 */ 509 public SELF labelParameter(String value) { 510 labelParameter = reqnn("value", value); 511 return self(); 512 } 513 514 /** 515 * <i><l>HtmlSerializer</l> configuration property: </i> Anchor text source. 516 * 517 * <p> 518 * When creating anchor tags (e.g. <code><xt><a</xt> <xa>href</xa>=<xs>'...'</xs> 519 * <xt>></xt>text<xt></a></xt></code>) in HTML, this setting defines what to set the inner text to. 520 * 521 * <p> 522 * The possible values are: 523 * <ul> 524 * <li class='jc'>{@link AnchorText} 525 * <ul> 526 * <li class='jf'>{@link AnchorText#TO_STRING TO_STRING} (default) - Set to whatever is returned by {@link #toString()} on the object. 527 * <br> 528 * <h4 class='section'>Example:</h4> 529 * <p class='bjson'> 530 * <jc>// Our bean class with a URI property.</jc> 531 * <jk>public class</jk> MyBean { 532 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org?foo=bar#myAnchor"</js>); 533 * } 534 * 535 * <jc>// Serializer with TO_STRING anchor text.</jc> 536 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer.<jsm>create</jsm>().anchorText(<jsf>TO_STRING</jsf>).build(); 537 * 538 * <jc>// Produces: <a href='http://www.apache.org?foo=bar#myAnchor'>http://www.apache.org?foo=bar#myAnchor</a></jc> 539 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 540 * </p> 541 * <li class='jf'>{@link AnchorText#PROPERTY_NAME PROPERTY_NAME} - Set to the bean property name. 542 * <br> 543 * <h4 class='section'>Example:</h4> 544 * <p class='bjson'> 545 * <jc>// Our bean class with a URI property.</jc> 546 * <jk>public class</jk> MyBean { 547 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org?foo=bar#myAnchor"</js>); 548 * } 549 * 550 * <jc>// Serializer with PROPERTY_NAME anchor text.</jc> 551 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer.<jsm>create</jsm>().anchorText(<jsf>PROPERTY_NAME</jsf>).build(); 552 * 553 * <jc>// Produces: <a href='http://www.apache.org?foo=bar#myAnchor'>f1</a></jc> 554 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 555 * </p> 556 * <li class='jf'>{@link AnchorText#URI URI} - Set to the URI value. 557 * <br> 558 * <h4 class='section'>Example:</h4> 559 * <p class='bjson'> 560 * <jc>// Our bean class with a URI property.</jc> 561 * <jk>public class</jk> MyBean { 562 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org?foo=bar#myAnchor"</js>); 563 * } 564 * 565 * <jc>// Serializer with URI anchor text.</jc> 566 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer.<jsm>create</jsm>().anchorText(<jsf>URI</jsf>).build(); 567 * 568 * <jc>// Produces: <a href='http://www.apache.org?foo=bar#myAnchor'>http://www.apache.org?foo=bar</a></jc> 569 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 570 * </p> 571 * <li class='jf'>{@link AnchorText#LAST_TOKEN LAST_TOKEN} - Set to the last token of the URI value. 572 * <br> 573 * <h4 class='section'>Example:</h4> 574 * <p class='bjson'> 575 * <jc>// Our bean class with a URI property.</jc> 576 * <jk>public class</jk> MyBean { 577 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org/foo/bar?baz=qux#myAnchor"</js>); 578 * } 579 * 580 * <jc>// Serializer with LAST_TOKEN anchor text.</jc> 581 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer.<jsm>create</jsm>().anchorText(<jsf>LAST_TOKEN</jsf>).build(); 582 * 583 * <jc>// Produces: <a href='http://www.apache.org/foo/bar?baz=qux#myAnchor'>bar</a></jc> 584 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 585 * </p> 586 * <li class='jf'>{@link AnchorText#URI_ANCHOR URI_ANCHOR} - Set to the anchor of the URL. 587 * <br> 588 * <h4 class='section'>Example:</h4> 589 * <p class='bjson'> 590 * <jc>// Our bean class with a URI property.</jc> 591 * <jk>public class</jk> MyBean { 592 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org/foo/bar?baz=qux#myAnchor"</js>); 593 * } 594 * 595 * <jc>// Serializer with URI_ANCHOR anchor text.</jc> 596 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer.<jsm>create</jsm>().anchorText(<jsf>URI_ANCHOR</jsf>).build(); 597 * 598 * <jc>// Produces: <a href='http://www.apache.org/foo/bar?baz=qux#myAnchor'>myAnchor</a></jc> 599 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 600 * </p> 601 * <li class='jf'>{@link AnchorText#CONTEXT_RELATIVE CONTEXT_RELATIVE} - Same as {@link AnchorText#TO_STRING TO_STRING} but assumes it's a context-relative path. 602 * <br> 603 * <h4 class='section'>Example:</h4> 604 * <p class='bjson'> 605 * <jc>// Our bean class with a URI property.</jc> 606 * <jk>public class</jk> MyBean { 607 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"bar/baz"</js>); 608 * } 609 * 610 * <jc>// Serializer with CONTEXT_RELATIVE anchor text.</jc> 611 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer 612 * .<jsm>create</jsm>() 613 * .anchorText(<jsf>CONTEXT_RELATIVE</jsf>) 614 * .uriResolution(<jsf>ROOT_RELATIVE</jsf>) 615 * .uriRelativity(<jsf>RESOURCE</jsf>) 616 * .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>) 617 * .build(); 618 * 619 * <jc>// Produces: <a href='/myContext/myServlet/bar/baz'>myServlet/bar/baz</a></jc> 620 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 621 * </p> 622 * <li class='jf'>{@link AnchorText#SERVLET_RELATIVE SERVLET_RELATIVE} - Same as {@link AnchorText#TO_STRING TO_STRING} but assumes it's a servlet-relative path. 623 * <br> 624 * <h4 class='section'>Example:</h4> 625 * <p class='bjson'> 626 * <jc>// Our bean class with a URI property.</jc> 627 * <jk>public class</jk> MyBean { 628 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"bar/baz"</js>); 629 * } 630 * 631 * <jc>// Serializer with SERVLET_RELATIVE anchor text.</jc> 632 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer 633 * .<jsm>create</jsm>() 634 * .anchorText(<jsf>SERVLET_RELATIVE</jsf>) 635 * .uriResolution(<jsf>ROOT_RELATIVE</jsf>) 636 * .uriRelativity(<jsf>RESOURCE</jsf>) 637 * .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>) 638 * .build(); 639 * 640 * <jc>// Produces: <a href='/myContext/myServlet/bar/baz'>bar/baz</a></jc> 641 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 642 * </p> 643 * <li class='jf'>{@link AnchorText#PATH_RELATIVE PATH_RELATIVE} - Same as {@link AnchorText#TO_STRING TO_STRING} but assumes it's a path-relative path. 644 * <br> 645 * <h4 class='section'>Example:</h4> 646 * <p class='bjson'> 647 * <jc>// Our bean class with a URI property.</jc> 648 * <jk>public class</jk> MyBean { 649 * <jk>public</jk> URI <jf>f1</jf> = URI.<jsm>create</jsm>(<js>"bar/baz"</js>); 650 * } 651 * 652 * <jc>// Serializer with PATH_RELATIVE anchor text.</jc> 653 * WriterSerializer <jv>serializer1</jv> = HtmlSerializer 654 * .<jsm>create</jsm>() 655 * .anchorText(<jsf>PATH_RELATIVE</jsf>) 656 * .uriResolution(<jsf>ROOT_RELATIVE</jsf>) 657 * .uriRelativity(<jsf>PATH_INFO</jsf>) 658 * .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>) 659 * .build(); 660 * 661 * <jc>// Produces: <a href='/myContext/myServlet/foo/bar/baz'>bar/baz</a></jc> 662 * String <jv>html</jv> = <jv>serializer1</jv>.write(<jk>new</jk> MyBean()); 663 * </p> 664 * </ul> 665 * </ul> 666 * 667 * @param value 668 * The new value for this property. 669 * <br>Cannot be <jk>null</jk>. 670 * <br>The default is {@link AnchorText#TO_STRING}. 671 * @return This object. 672 */ 673 public SELF uriAnchorText(AnchorText value) { 674 uriAnchorText = reqnn("value", value); 675 return self(); 676 } 677 678 /** 679 * <i><l>HtmlSerializer</l> configuration property: </i> Allowed URI schemes for links. 680 * 681 * <p> 682 * Link targets (<c>href</c> attributes) whose scheme is not in this list are rendered as plain text instead of as a link. 683 * The check is applied after the URI has been resolved. 684 * Relative URIs, fragments (<js>"#foo"</js>) and query strings (<js>"?foo"</js>) are always allowed. 685 * 686 * @param value 687 * The allowed schemes, compared case-insensitively and without the trailing colon. 688 * <br>Cannot be <jk>null</jk>. 689 * <br>The default is <js>"http"</js>, <js>"https"</js>, <js>"mailto"</js> and <js>"tel"</js>. 690 * @return This object. 691 */ 692 public SELF uriSchemes(String...value) { 693 uriSchemes = Set.copyOf(Arrays.stream(reqnn("value", value)).map(x -> x.toLowerCase(Locale.ROOT)).toList()); 694 return self(); 695 } 696 697 698 } 699 700 /** 701 * Concrete default builder leaf for the non-subclassed {@link HtmlSerializer#create()} / {@link HtmlSerializer#copy()} path. 702 */ 703 public static final class DefaultBuilder extends Builder<DefaultBuilder> { 704 705 DefaultBuilder() {} 706 707 DefaultBuilder(HtmlSerializer copyFrom) { 708 super(copyFrom); 709 } 710 711 DefaultBuilder(Builder<?> copyFrom) { 712 super(copyFrom); 713 } 714 715 @Override /* Overridden from Context.Builder<?> */ 716 public DefaultBuilder copy() { 717 return new DefaultBuilder(this); 718 } 719 } 720 721 /** Default serializer, single quotes. */ 722 public static class Sq extends HtmlSerializer { 723 724 /** 725 * Constructor. 726 * 727 * @param builder The builder for this object. 728 */ 729 public Sq(Builder<?> builder) { 730 super(builder.quoteChar('\'')); 731 } 732 } 733 734 /** Default serializer, single quotes, whitespace added. */ 735 public static class SqReadable extends HtmlSerializer { 736 737 /** 738 * Constructor. 739 * 740 * @param builder The builder for this object. 741 */ 742 public SqReadable(Builder<?> builder) { 743 super(builder.quoteChar('\'').useWhitespace()); 744 } 745 } 746 747 /** Default serializer, all default settings. */ 748 public static final HtmlSerializer DEFAULT = new HtmlSerializer(create()); 749 750 /** Default serializer, single quotes. */ 751 public static final HtmlSerializer DEFAULT_SQ = new HtmlSerializer.Sq(create()); 752 /** Default serializer, single quotes, whitespace added. */ 753 public static final HtmlSerializer DEFAULT_SQ_READABLE = new HtmlSerializer.SqReadable(create()); 754 755 /** Default serializer, single quotes, simplified (no JSON type tags on strings). */ 756 public static final HtmlSerializer DEFAULT_SIMPLE_SQ = new HtmlSerializer(create().sq().disableJsonTags()); 757 758 /** 759 * Creates a new builder for this object. 760 * 761 * @return A new builder. 762 */ 763 @SuppressWarnings({ 764 "java:S1452" // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type 765 }) 766 public static Builder<?> create() { 767 return new DefaultBuilder(); 768 } 769 770 protected final boolean addBeanTypesHtml; 771 protected final boolean addKeyValueTableHeaders; 772 protected final boolean detectLabelParameters; 773 protected final boolean detectLinksInStrings; 774 protected final AnchorText uriAnchorText; 775 protected final String labelParameter; 776 protected final Set<String> uriSchemes; 777 778 private final Map<ClassMeta<?>,HtmlClassMeta> htmlClassMetas = new ConcurrentHashMap<>(); 779 private final Map<BeanPropertyMeta,HtmlBeanPropertyMeta> htmlBeanPropertyMetas = new ConcurrentHashMap<>(); 780 781 private final AtomicReference<HtmlSchemaSerializer> schemaSerializer = new AtomicReference<>(); 782 783 /** 784 * Constructor. 785 * 786 * @param builder The builder for this object. 787 */ 788 public HtmlSerializer(Builder<?> builder) { 789 super(builder); 790 addBeanTypesHtml = builder.addBeanTypesHtml; 791 addKeyValueTableHeaders = builder.addKeyValueTableHeaders; 792 detectLabelParameters = ! builder.disableDetectLabelParameters; 793 detectLinksInStrings = ! builder.disableDetectLinksInStrings; 794 labelParameter = builder.labelParameter; 795 uriAnchorText = builder.uriAnchorText; 796 uriSchemes = builder.uriSchemes; 797 } 798 799 @Override /* Overridden from Context */ 800 public Builder<?> copy() { 801 return new DefaultBuilder(this); 802 } 803 804 @Override /* Overridden from Context */ 805 public HtmlSerializerSession.Builder<?> createSession() { 806 return HtmlSerializerSession.create(this); 807 } 808 809 @Override /* Overridden from HtmlMetaProvider */ 810 public HtmlBeanPropertyMeta getHtmlBeanPropertyMeta(BeanPropertyMeta bpm) { 811 if (bpm == null) 812 return HtmlBeanPropertyMeta.DEFAULT; 813 return htmlBeanPropertyMetas.computeIfAbsent(bpm, k -> new HtmlBeanPropertyMeta(k.getDelegateFor(), this.getAnnotationProvider(), this)); 814 } 815 816 @Override /* Overridden from HtmlMetaProvider */ 817 public HtmlClassMeta getHtmlClassMeta(ClassMeta<?> cm) { 818 return htmlClassMetas.computeIfAbsent(cm, k -> new HtmlClassMeta(k, this)); 819 } 820 821 /** 822 * Returns the schema serializer. 823 * 824 * @return The schema serializer. 825 */ 826 public HtmlSerializer getSchemaSerializer() { 827 HtmlSchemaSerializer result = schemaSerializer.get(); 828 if (result == null) { 829 result = HtmlSchemaSerializer.create().marshallingContext(getMarshallingContext()).build(); 830 if (! schemaSerializer.compareAndSet(null, result)) { 831 result = schemaSerializer.get(); 832 } 833 } 834 return result; 835 } 836 837 @Override /* Overridden from Context */ 838 public HtmlSerializerSession getSession() { return createSession().build(); } 839 840 /** 841 * Link label parameter name. 842 * 843 * @see Builder#labelParameter(String) 844 * @return 845 * The parameter name to look for when resolving link labels. 846 */ 847 protected final String getLabelParameter() { return labelParameter; } 848 849 /** 850 * Anchor text source. 851 * 852 * @see Builder#uriAnchorText(AnchorText) 853 * @return 854 * When creating anchor tags (e.g. <code><xt><a</xt> <xa>href</xa>=<xs>'...'</xs> 855 * <xt>></xt>text<xt></a></xt></code>) in HTML, this setting defines what to set the inner text to. 856 */ 857 protected final AnchorText getUriAnchorText() { return uriAnchorText; } 858 859 /** 860 * Add <js>"_type"</js> properties when needed. 861 * 862 * @see Builder#addBeanTypesHtml() 863 * @return 864 * <jk>true</jk> if <js>"_type"</js> properties will be added to beans if their type cannot be inferred 865 * through reflection. 866 */ 867 @Override 868 protected final boolean isAddBeanTypes() { return addBeanTypesHtml || super.isAddBeanTypes(); } 869 870 /** 871 * Add key/value headers on bean/map tables. 872 * 873 * @see Builder#addKeyValueTableHeaders() 874 * @return 875 * <jk>true</jk> if <bc>key</bc> and <bc>value</bc> column headers are added to tables. 876 */ 877 protected final boolean isAddKeyValueTableHeaders() { return addKeyValueTableHeaders; } 878 879 /** 880 * Look for link labels in URIs. 881 * 882 * @see Builder#disableDetectLabelParameters() 883 * @return 884 * <jk>true</jk> if we should look for URL label parameters (e.g. <js>"?label=foobar"</js>). 885 */ 886 protected final boolean isDetectLabelParameters() { return detectLabelParameters; } 887 888 /** 889 * Look for URLs in {@link String Strings}. 890 * 891 * @see Builder#disableDetectLinksInStrings() 892 * @return 893 * <jk>true</jk> if we should automatically convert strings to URLs if they look like a URL. 894 */ 895 protected final boolean isDetectLinksInStrings() { return detectLinksInStrings; } 896 897 @Override /* Overridden from XmlSerializer */ 898 protected FluentMap<String,Object> properties() { 899 return super.properties() 900 .a("addBeanTypesHtml", addBeanTypesHtml) 901 .a("addKeyValueTableHeaders", addKeyValueTableHeaders) 902 .a("detectLabelParameters", detectLabelParameters) 903 .a("detectLinksInStrings", detectLinksInStrings) 904 .a("labelParameter", labelParameter) 905 .a("uriAnchorText", uriAnchorText) 906 .a("uriSchemes", uriSchemes); 907 } 908}