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}