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>// &lt;ul&gt;&lt;li&gt;1&lt;li&gt;2&lt;li&gt;3&lt;/ul&gt;</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>//    &lt;table&gt; </jc>
095 *    <jc>//       &lt;tr&gt;&lt;th&gt;firstName&lt;/th&gt;&lt;th&gt;lastName&lt;/th&gt;&lt;/tr&gt; </jc>
096 *    <jc>//       &lt;tr&gt;&lt;td&gt;Bob&lt;/td&gt;&lt;td&gt;Costas&lt;/td&gt;&lt;/tr&gt; </jc>
097 *    <jc>//       &lt;tr&gt;&lt;td&gt;Billy&lt;/td&gt;&lt;td&gt;TheKid&lt;/td&gt;&lt;/tr&gt; </jc>
098 *    <jc>//       &lt;tr&gt;&lt;td&gt;Barney&lt;/td&gt;&lt;td&gt;Miller&lt;/td&gt;&lt;/tr&gt; </jc>
099 *    <jc>//    &lt;/table&gt; </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>//    &lt;table&gt; </jc>
109 *    <jc>//       &lt;tr&gt;&lt;th&gt;key&lt;/th&gt;&lt;th&gt;value&lt;/th&gt;&lt;/tr&gt; </jc>
110 *    <jc>//       &lt;tr&gt;&lt;td&gt;foo&lt;/td&gt;&lt;td&gt;bar&lt;/td&gt;&lt;/tr&gt; </jc>
111 *    <jc>//       &lt;tr&gt;&lt;td&gt;baz&lt;/td&gt;&lt;td&gt;123&lt;/td&gt;&lt;/tr&gt; </jc>
112 *    <jc>//    &lt;/table&gt; </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>//   &lt;table&gt; </jc>
119 *    <jc>//      &lt;tr&gt;&lt;th&gt;key&lt;/th&gt;&lt;th&gt;value&lt;/th&gt;&lt;/tr&gt; </jc>
120 *    <jc>//      &lt;tr&gt;&lt;td&gt;foo&lt;/td&gt;&lt;td&gt;bar&lt;/td&gt;&lt;/tr&gt; </jc>
121 *    <jc>//      &lt;tr&gt;&lt;td&gt;baz&lt;/td&gt;&lt;td&gt;123&lt;/td&gt;&lt;/tr&gt; </jc>
122 *    <jc>//      &lt;tr&gt;&lt;td&gt;someNumbers&lt;/td&gt;&lt;td&gt;&lt;ul&gt;&lt;li&gt;1&lt;li&gt;2&lt;li&gt;3&lt;/ul&gt;&lt;/td&gt;&lt;/tr&gt; </jc>
123 *    <jc>//      &lt;tr&gt;&lt;td&gt;someSubMap&lt;/td&gt;&lt;td&gt; </jc>
124 *    <jc>//         &lt;table&gt; </jc>
125 *    <jc>//            &lt;tr&gt;&lt;th&gt;key&lt;/th&gt;&lt;th&gt;value&lt;/th&gt;&lt;/tr&gt; </jc>
126 *    <jc>//            &lt;tr&gt;&lt;td&gt;a&lt;/td&gt;&lt;td&gt;b&lt;/td&gt;&lt;/tr&gt; </jc>
127 *    <jc>//         &lt;/table&gt; </jc>
128 *    <jc>//      &lt;/td&gt;&lt;/tr&gt; </jc>
129 *    <jc>//   &lt;/table&gt; </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:&emsp;</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:&emsp;</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:&emsp;</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:&emsp;</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:&emsp;</i>  Anchor text source.
516       *
517       * <p>
518       * When creating anchor tags (e.g. <code><xt>&lt;a</xt> <xa>href</xa>=<xs>'...'</xs>
519       * <xt>&gt;</xt>text<xt>&lt;/a&gt;</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: &lt;a href='http://www.apache.org?foo=bar#myAnchor'&gt;http://www.apache.org?foo=bar#myAnchor&lt;/a&gt;</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: &lt;a href='http://www.apache.org?foo=bar#myAnchor'&gt;f1&lt;/a&gt;</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: &lt;a href='http://www.apache.org?foo=bar#myAnchor'&gt;http://www.apache.org?foo=bar&lt;/a&gt;</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: &lt;a href='http://www.apache.org/foo/bar?baz=qux#myAnchor'&gt;bar&lt;/a&gt;</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: &lt;a href='http://www.apache.org/foo/bar?baz=qux#myAnchor'&gt;myAnchor&lt;/a&gt;</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: &lt;a href&#61;'/myContext/myServlet/bar/baz'&gt;myServlet/bar/baz&lt;/a&gt;</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: &lt;a href&#61;'/myContext/myServlet/bar/baz'&gt;bar/baz&lt;/a&gt;</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: &lt;a href&#61;'/myContext/myServlet/foo/bar/baz'&gt;bar/baz&lt;/a&gt;</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:&emsp;</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>&lt;a</xt> <xa>href</xa>=<xs>'...'</xs>
855    *    <xt>&gt;</xt>text<xt>&lt;/a&gt;</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}