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.uon;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020import static org.apache.juneau.commons.utils.SystemUtils.*;
021
022import java.io.*;
023import java.util.*;
024import java.util.concurrent.*;
025
026import org.apache.juneau.commons.bean.*;
027import org.apache.juneau.commons.collections.*;
028import org.apache.juneau.commons.httppart.*;
029import org.apache.juneau.marshall.*;
030import org.apache.juneau.marshall.httppart.*;
031import org.apache.juneau.marshall.serializer.*;
032import org.apache.juneau.marshall.stream.*;
033
034/**
035 * Serializes POJO models to UON (a notation for URL-encoded query parameter values).
036 *
037 * <h2 class='topic'>Media types</h2>
038 * <p>
039 * Handles <c>Accept</c> types:  <bc>text/uon</bc>
040 * <p>
041 * Produces <c>Content-Type</c> types:  <bc>text/uon</bc>
042 *
043 * <h2 class='topic'>Description</h2>
044 * <p>
045 * This serializer provides several serialization options.
046 * Typically, one of the predefined DEFAULT serializers will be sufficient.
047 * However, custom serializers can be constructed to fine-tune behavior.
048 *
049 * <p>
050 * The following shows a sample object defined in Javascript:
051 * <p class='bjson'>
052 *    {
053 *       id: 1,
054 *       name: <js>'John Smith'</js>,
055 *       uri: <js>'http://sample/addressBook/person/1'</js>,
056 *       addressBookUri: <js>'http://sample/addressBook'</js>,
057 *       birthDate: <js>'1946-08-12T00:00:00Z'</js>,
058 *       otherIds: <jk>null</jk>,
059 *       addresses: [
060 *          {
061 *             uri: <js>'http://sample/addressBook/address/1'</js>,
062 *             personUri: <js>'http://sample/addressBook/person/1'</js>,
063 *             id: 1,
064 *             street: <js>'100 Main Street'</js>,
065 *             city: <js>'Anywhereville'</js>,
066 *             state: <js>'NY'</js>,
067 *             zip: 12345,
068 *             isCurrent: <jk>true</jk>,
069 *          }
070 *       ]
071 *    }
072 * </p>
073 *
074 * <p>
075 * Using the "strict" syntax defined in this document, the equivalent UON notation would be as follows:
076 * <p class='buon'>
077 *    (
078 *       <ua>id</ua>=<un>1</un>,
079 *       <ua>name</ua>=<us>'John+Smith'</us>,
080 *       <ua>uri</ua>=<us>http://sample/addressBook/person/1</us>,
081 *       <ua>addressBookUri</ua>=<us>http://sample/addressBook</us>,
082 *       <ua>birthDate</ua>=<us>1946-08-12T00:00:00Z</us>,
083 *       <ua>otherIds</ua>=<uk>null</uk>,
084 *       <ua>addresses</ua>=@(
085 *          (
086 *             <ua>uri</ua>=<us>http://sample/addressBook/address/1</us>,
087 *             <ua>personUri</ua>=<us>http://sample/addressBook/person/1</us>,
088 *             <ua>id</ua>=<un>1</un>,
089 *             <ua>street</ua>=<us>'100+Main+Street'</us>,
090 *             <ua>city</ua>=<us>Anywhereville</us>,
091 *             <ua>state</ua>=<us>NY</us>,
092 *             <ua>zip</ua>=<un>12345</un>,
093 *             <ua>isCurrent</ua>=<uk>true</uk>
094 *          )
095 *       )
096 *    )
097 * </p>
098 *
099 * <h2 class='figure'>Example output (Map of name/age):</h2>
100 * <p class='bcode'>
101 *    (name=Alice,age=30)
102 * </p>
103 *
104 * <h2 class='figure'>Complex (nested object + array):</h2>
105 * <p class='bcode'>
106 *    (name=Alice,age=30,address=(street=123+Main+St,city=Boston,state=MA),tags=@(a,b,c))
107 * </p>
108 *
109 * <h2 class='section'>Example:</h2>
110 * <p class='bjava'>
111 *    <jc>// Serialize a Map</jc>
112 *    Map <jv>map</jv> = JsonMap.<jsm>ofText</jsm>(<js>"{a:'b',c:1,d:false,e:['f',1,false],g:{h:'i'}}"</js>);
113 *
114 *    <jc>// Serialize to value equivalent to JSON.</jc>
115 *    <jc>// Produces "(a=b,c=1,d=false,e=@(f,1,false),g=(h=i))"</jc>
116 *    String <jv>uon</jv> = UonSerializer.<jsf>DEFAULT</jsf>.write(<jv>map</jv>);
117 *
118 *    <jc>// Serialize a bean</jc>
119 *    <jk>public class</jk> Person {
120 *       <jk>public</jk> Person(String <jv>name</jv>);
121 *       <jk>public</jk> String getName();
122 *       <jk>public int</jk> getAge();
123 *       <jk>public</jk> Address getAddress();
124 *       <jk>public boolean</jk> deceased;
125 *    }
126 *
127 *    <jk>public class</jk> Address {
128 *       <jk>public</jk> String getStreet();
129 *       <jk>public</jk> String getCity();
130 *       <jk>public</jk> String getState();
131 *       <jk>public int</jk> getZip();
132 *    }
133 *
134 *    Person <jv>person</jv> = <jk>new</jk> Person(<js>"John Doe"</js>, 23, <js>"123 Main St"</js>, <js>"Anywhere"</js>,
135 *       <js>"NY"</js>, 12345, <jk>false</jk>);
136 *
137 *    <jc>// Produces "(name='John Doe',age=23,address=(street='123 Main St',city=Anywhere,state=NY,zip=12345),deceased=false)"</jc>
138 *    String <jv>uon</jv> = UonSerializer.<jsf>DEFAULT</jsf>.write(<jv>person</jv>);
139 * </p>
140 *
141 * <h2 class='section'>Notes:</h2><ul>
142 *    <li class='note'>This class is thread safe and reusable.
143 * </ul>
144 *
145 * <h2 class='section'>See Also:</h2><ul>
146 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/UonSupport">UON</a>
147
148 * </ul>
149 */
150@SuppressWarnings({
151   "java:S110", // Inheritance depth acceptable for this class hierarchy
152   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
153   "java:S9149", // Per-format static factories intentionally shadow the parent's.
154   "resource" // Closeable resources are owned by the caller's serializer session; Eclipse JDT @Owning warning is by design.
155})
156public class UonSerializer extends WriterSerializer implements HttpPartSerializer, UonMetaProvider, RecordWritable {
157
158   /**
159    * Builder class.
160    */
161   @SuppressWarnings({
162      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
163   })
164   public abstract static class Builder<SELF extends Builder<SELF>> extends WriterSerializer.Builder<SELF> {
165
166      private static final Cache<HashKey,UonSerializer> CACHE = Cache.of(HashKey.class, UonSerializer.class).build();
167
168      private boolean addBeanTypesUon;
169      private boolean encoding;
170      private ParamFormat paramFormat;
171      private Character quoteCharUon;
172
173      /**
174       * Constructor, default settings.
175       */
176      protected Builder() {
177         produces("text/uon");
178         addBeanTypesUon = env("UonSerializer.addBeanTypesUon", false);
179         encoding = env("UonSerializer.encoding", false);
180         paramFormat = env("UonSerializer.paramFormat", ParamFormat.UON);
181         quoteCharUon = null;
182      }
183
184      /**
185       * Copy constructor.
186       *
187       * @param copyFrom The builder to copy from.
188       *    <br>Cannot be <jk>null</jk>.
189       */
190      protected Builder(Builder<?> copyFrom) {
191         super(reqnn("copyFrom", copyFrom));
192         addBeanTypesUon = copyFrom.addBeanTypesUon;
193         encoding = copyFrom.encoding;
194         paramFormat = copyFrom.paramFormat;
195         quoteCharUon = copyFrom.quoteCharUon;
196      }
197
198      /**
199       * Copy constructor.
200       *
201       * @param copyFrom The bean to copy from.
202       *    <br>Cannot be <jk>null</jk>.
203       */
204      protected Builder(UonSerializer copyFrom) {
205         super(reqnn("copyFrom", copyFrom));
206         addBeanTypesUon = copyFrom.addBeanTypesUon;
207         encoding = copyFrom.encoding;
208         paramFormat = copyFrom.paramFormat;
209         quoteCharUon = copyFrom.quoteCharUon;
210      }
211
212      /**
213       * Add <js>"_type"</js> properties when needed.
214       *
215       * <p>
216       * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
217       * through reflection.
218       *
219       * <p>
220       * When present, this value overrides the {@link org.apache.juneau.marshall.serializer.Serializer.Builder#addBeanTypes() Serializer.Builder#addBeanTypes()} setting and is
221       * provided to customize the behavior of specific serializers in a {@link SerializerSet}.
222       *
223       * @return This object.
224       */
225      public SELF addBeanTypesUon() {
226         return addBeanTypesUon(true);
227      }
228
229      /**
230       * Same as {@link #addBeanTypesUon()} but allows you to explicitly specify the value.
231       *
232       * @param value The value for this setting.
233       * @return This object.
234       */
235      public SELF addBeanTypesUon(boolean value) {
236         addBeanTypesUon = value;
237         return self();
238      }
239
240      @Override /* Overridden from Context.Builder<?> */
241      public UonSerializer build() {
242         return cache(CACHE).build(UonSerializer.class);
243      }
244
245      @Override /* Overridden from Context.Builder<?> */
246      public abstract SELF copy();
247
248      /**
249       * Encode non-valid URI characters.
250       *
251       * <p>
252       * Encode non-valid URI characters with <js>"%xx"</js> constructs.
253       *
254       * <p>
255       * If <jk>true</jk>, non-valid URI characters will be converted to <js>"%xx"</js> sequences.
256       * <br>Set to <jk>false</jk> if parameter value is being passed to some other code that will already perform
257       * URL-encoding of non-valid URI characters.
258       *
259       * <h4 class='section'>Example:</h4>
260       * <p class='bjava'>
261       *    <jc>// Create a non-encoding UON serializer.</jc>
262       *    UonSerializer <jv>serializer1</jv> = UonSerializer.
263       *       .<jsm>create</jsm>()
264       *       .build();
265       *
266       *    <jc>// Create an encoding UON serializer.</jc>
267       *    UonSerializer <jv>serializer2</jv> = UonSerializer.
268       *       .<jsm>create</jsm>()
269       *       .encoding()
270       *       .build();
271       *
272       *    JsonMap <jv>map</jv> = JsonMap.<jsm>of</jsm>(<js>"foo"</js>, <js>"foo bar"</js>);
273       *
274       *    <jc>// Produces: "(foo=foo bar)"</jc>
275       *    String <jv>uon1</jv> = <jv>serializer1</jv>.write(<jv>map</jv>)
276       *
277       *    <jc>// Produces: "(foo=foo%20bar)"</jc>
278       *    String <jv>uon2</jv> = <jv>serializer2</jv>.write(<jv>map</jv>)
279       * </p>
280       *
281       * @return This object.
282       */
283      public SELF encoding() {
284         return encoding(true);
285      }
286
287      /**
288       * Same as {@link #encoding()} but allows you to disable the previous setting.
289       *
290       * @param value The new value for this setting.
291       * @return This object.
292       */
293      public SELF encoding(boolean value) {
294         encoding = value;
295         return self();
296      }
297
298      @Override /* Overridden from Context.Builder<?> */
299      public HashKey hashKey() {
300         // @formatter:off
301         return HashKey.of(
302            super.hashKey(),
303            addBeanTypesUon,
304            encoding,
305            paramFormat,
306            quoteCharUon
307         );
308         // @formatter:on
309      }
310
311      /**
312       * Format to use for query/form-data/header values.
313       *
314       * <p>
315       * Specifies the format to use for URL GET parameter keys and values.
316       *
317       * <h4 class='section'>Example:</h4>
318       * <p class='bjava'>
319       *    <jc>// Create a normal UON serializer.</jc>
320       *    UonSerializer <jv>serializer1</jv> = UonSerializer
321       *       .<jsm>create</jsm>()
322       *       .build();
323       *
324       *    <jc>// Create a plain-text UON serializer.</jc>
325       *    UonSerializer <jv>serializer2</jv> = UonSerializer
326       *       .<jsm>create</jsm>()
327       *       .paramFormat(<jsf>PLAIN_TEXT</jsf>)
328       *       .build();
329       *
330       *    JsonMap <jv>map</jv> = JsonMap.<jsm>of</jsm>(
331       *       <js>"foo"</js>, <js>"bar"</js>,
332       *       <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
333       *    );
334       *
335       *    <jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc>
336       *    String <jv>uon1</jv> = <jv>serializer1</jv>.write(<jv>map</jv>)
337       *
338       *    <jc>// Produces: "foo=bar,baz=qux,true,123"</jc>
339       *    String <jv>uon2</jv> = <jv>serializer2</jv>.write(<jv>map</jv>)
340       * </p>
341       *
342       * <ul class='values javatree'>
343       *    <li class='jf'>{@link ParamFormat#UON} (default) - Use UON notation for parameters.
344       *    <li class='jf'>{@link ParamFormat#PLAINTEXT} - Use plain text for parameters.
345       * </ul>
346       *
347       * @param value
348       *    The new value for this property.
349       *    <br>The default value is {@link ParamFormat#UON}.
350       *    <br>Cannot be <jk>null</jk>.
351       * @return This object.
352       */
353      public SELF paramFormat(ParamFormat value) {
354         paramFormat = reqnn("value", value);
355         return self();
356      }
357
358      /**
359       * Format to use for query/form-data/header values.
360       *
361       * <p>
362       * Specifies plain-text for the format to use for URL GET parameter keys and values.
363       *
364       * <h4 class='section'>Example:</h4>
365       * <p class='bjava'>
366       *    <jc>// Create a plain-text UON serializer.</jc>
367       *    UonSerializer <jv>serializer</jv> = UonSerializer
368       *       .<jsm>create</jsm>()
369       *       .paramFormatPlain()
370       *       .build();
371       *
372       *    JsonMap <jv>map</jv> = JsonMap.<jsm>of</jsm>(
373       *       <js>"foo"</js>, <js>"bar"</js>,
374       *       <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
375       *    );
376       *
377       *    <jc>// Produces: "foo=bar,baz=qux,true,123"</jc>
378       *    String <jv>uon</jv> = <jv>serializer</jv>.write(<jv>map</jv>)
379       * </p>
380       *
381       * @return This object.
382       */
383      public SELF paramFormatPlain() {
384         return paramFormat(ParamFormat.PLAINTEXT);
385      }
386
387      /**
388       * Specifies the quote character.
389       *
390       * @param value The value for this setting.
391       * @return This object.
392       */
393      public SELF quoteCharUon(char value) {
394         quoteCharUon = value;
395         return self();
396      }
397
398
399   }
400
401   /**
402    * Concrete default builder leaf for the non-subclassed {@link UonSerializer#create()} / {@link UonSerializer#copy()} path.
403    */
404   public static final class DefaultBuilder extends Builder<DefaultBuilder> {
405
406      DefaultBuilder() {}
407
408      DefaultBuilder(UonSerializer copyFrom) {
409         super(copyFrom);
410      }
411
412      DefaultBuilder(Builder<?> copyFrom) {
413         super(copyFrom);
414      }
415
416      @Override /* Overridden from Context.Builder<?> */
417      public DefaultBuilder copy() {
418         return new DefaultBuilder(this);
419      }
420   }
421
422   /**
423    * Equivalent to <code>UonSerializer.<jsm>create</jsm>().encoding().build();</code>.
424    */
425   public static class Encoding extends UonSerializer {
426
427      /**
428       * Constructor.
429       *
430       * @param builder The builder for this object.
431       */
432      public Encoding(Builder<?> builder) {
433         super(builder.encoding());
434      }
435   }
436
437   /**
438    * Equivalent to <code>UonSerializer.<jsm>create</jsm>().ws().build();</code>.
439    */
440   public static class Readable extends UonSerializer {
441
442      /**
443       * Constructor.
444       *
445       * @param builder The builder for this object.
446       */
447      public Readable(Builder<?> builder) {
448         super(builder.useWhitespace());
449      }
450   }
451
452   /** Reusable instance of {@link UonSerializer}, all default settings. */
453   public static final UonSerializer DEFAULT = new UonSerializer(create());
454   /** Reusable instance of {@link UonSerializer.Readable}. */
455   public static final UonSerializer DEFAULT_READABLE = new Readable(create());
456
457   /** Reusable instance of {@link UonSerializer.Encoding}. */
458   public static final UonSerializer DEFAULT_ENCODING = new Encoding(create());
459
460   /**
461    * Creates a new builder for this object.
462    *
463    * @return A new builder.
464    */
465   @SuppressWarnings({
466      "java:S1452" // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type
467   })
468   public static Builder<?> create() {
469      return new DefaultBuilder();
470   }
471
472   protected final boolean addBeanTypesUon;
473   protected final boolean encoding;
474   protected final Character quoteCharUon;
475   protected final ParamFormat paramFormat;
476   private final boolean addBeanTypes2;
477
478   private final char quoteChar2;
479   private final Map<BeanPropertyMeta,UonBeanPropertyMeta> uonBeanPropertyMetas = new ConcurrentHashMap<>();
480   private final Map<ClassMeta<?>,UonClassMeta> uonClassMetas = new ConcurrentHashMap<>();
481
482   /**
483    * Constructor.
484    *
485    * @param builder
486    *    The builder for this object.
487    */
488   public UonSerializer(Builder<?> builder) {
489      super(builder);
490
491      addBeanTypesUon = builder.addBeanTypesUon;
492      encoding = builder.encoding;
493      paramFormat = builder.paramFormat;
494      quoteCharUon = builder.quoteCharUon;
495
496      addBeanTypes2 = addBeanTypesUon || super.isAddBeanTypes();
497      if (nn(quoteCharUon)) {
498         quoteChar2 = quoteCharUon;
499      } else if (nn(super.quoteChar())) {
500         quoteChar2 = super.quoteChar();
501      } else {
502         quoteChar2 = '\'';
503      }
504   }
505
506   @Override /* Overridden from Context */
507   public Builder<?> copy() {
508      return new DefaultBuilder(this);
509   }
510
511   @Override /* Overridden from Context */
512   public UonSerializerSession.Builder<?> createSession() {
513      return UonSerializerSession.create(this);
514   }
515
516   @Override /* Overridden from HttpPartSerializer */
517   public UonSerializerSession getPartSession() { return UonSerializerSession.create(this).build(); }
518
519   @Override /* Overridden from Context */
520   public UonSerializerSession getSession() { return createSession().build(); }
521
522   /**
523    * Convenience delegator that opens a whole-value {@link RecordWriter} over the output using
524    * <b>default session arguments</b> (mirrors {@link #write(Object)}).
525    *
526    * <p>
527    * The real implementation lives on {@link UonSerializerSession#writeRecords(Object)}.
528    * Callers that need request-derived configuration should call {@link #createSession()} and
529    * invoke {@link UonSerializerSession#writeRecords(Object)} on the built session instead.
530    *
531    * @param output The output.
532    * @return A new {@link RecordWriter}.
533    * @throws IOException If a problem occurred opening the underlying output.
534    */
535   @Override /* RecordWritable */
536   public RecordWriter writeRecords(Object output) throws IOException {
537      return getSession().writeRecords(output);
538   }
539
540   @Override /* RecordWritable */
541   public boolean isRecordStreaming() {
542      return false;
543   }
544
545   @Override /* Overridden from UonMetaProvider */
546   public UonBeanPropertyMeta getUonBeanPropertyMeta(BeanPropertyMeta bpm) {
547      if (bpm == null)
548         return UonBeanPropertyMeta.DEFAULT;
549      return uonBeanPropertyMetas.computeIfAbsent(bpm, k -> new UonBeanPropertyMeta(k.getDelegateFor(), this));
550   }
551
552   @Override /* Overridden from UonMetaProvider */
553   public UonClassMeta getUonClassMeta(ClassMeta<?> cm) {
554      return uonClassMetas.computeIfAbsent(cm, k -> new UonClassMeta(k, this));
555   }
556
557   /**
558    * Converts the specified value to a string that can be used as an HTTP header value, query parameter value,
559    * form-data parameter, or URI path variable.
560    *
561    * <p>
562    * Returned values should NOT be URL-encoded.
563    *
564    * @param partType The category of value being serialized.
565    * @param schema
566    *    Schema information about the part.
567    *    <br>May be <jk>null</jk>.
568    *    <br>Not all part serializers use the schema information.
569    * @param value The value being serialized.
570    * @return The serialized value.
571    * @throws SerializeException If a problem occurred while trying to parse the input.
572    * @throws SchemaValidationException If the output fails schema validation.
573    */
574   public String write(HttpPartType partType, HttpPartSchema schema, Object value) throws SchemaValidationException, SerializeException {
575      return getPartSession().write(partType, schema, value);
576   }
577
578   /**
579    * Format to use for query/form-data/header values.
580    *
581    * @see Builder#paramFormat(ParamFormat)
582    * @return
583    *    Specifies the format to use for URL GET parameter keys and values.
584    */
585   protected final ParamFormat getParamFormat() { return paramFormat; }
586
587   /**
588    * Quote character.
589    *
590    * @see Builder#quoteCharUon(char)
591    * @return
592    *    The character used for quoting attributes and values.
593    */
594   @Override
595   protected final char getQuoteChar() { return quoteChar2; }
596
597   /**
598    * Add <js>"_type"</js> properties when needed.
599    *
600    * @see Builder#addBeanTypesUon()
601    * @return
602    *    <jk>true</jk> if <js>"_type"</js> properties will be added to beans if their type cannot be inferred
603    *    through reflection.
604    */
605   @Override
606   protected final boolean isAddBeanTypes() { return addBeanTypes2; }
607
608   /**
609    * Encode non-valid URI characters.
610    *
611    * @see Builder#encoding()
612    * @return
613    *    <jk>true</jk> if non-valid URI characters should be encoded with <js>"%xx"</js> constructs.
614    */
615   protected final boolean isEncoding() { return encoding; }
616
617   @Override /* Overridden from WriterSerializer */
618   protected FluentMap<String,Object> properties() {
619      return super.properties()
620         .a("addBeanTypes", addBeanTypes2)
621         .a("encoding", encoding)
622         .a("paramFormat", paramFormat);
623   }
624}