You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2020/05/15 00:08:31 UTC
[juneau] branch master updated: Javadocs
This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new 539a79f Javadocs
539a79f is described below
commit 539a79f7cc222d112194e4af37199a90642d73c0
Author: JamesBognar <ja...@salesforce.com>
AuthorDate: Thu May 14 20:08:07 2020 -0400
Javadocs
---
.../apache/juneau/jena/RdfSerializerBuilder.java | 18 -
.../org/apache/juneau/BeanTraverseBuilder.java | 63 +-
.../org/apache/juneau/BeanTraverseContext.java | 32 +-
.../apache/juneau/csv/CsvSerializerBuilder.java | 18 -
.../juneau/html/HtmlDocSerializerBuilder.java | 18 -
.../juneau/html/HtmlSchemaSerializerBuilder.java | 18 -
.../apache/juneau/html/HtmlSerializerBuilder.java | 18 -
.../html/HtmlStrippedDocSerializerBuilder.java | 18 -
.../apache/juneau/jso/JsoSerializerBuilder.java | 18 -
.../juneau/json/JsonSchemaSerializerBuilder.java | 18 -
.../apache/juneau/json/JsonSerializerBuilder.java | 18 -
.../juneau/json/SimpleJsonSerializerBuilder.java | 18 -
.../juneau/msgpack/MsgPackSerializerBuilder.java | 18 -
.../java/org/apache/juneau/oapi/OpenApiCommon.java | 34 +-
.../apache/juneau/oapi/OpenApiParserBuilder.java | 43 +
.../juneau/oapi/OpenApiSerializerBuilder.java | 76 +-
.../apache/juneau/parser/InputStreamParser.java | 6 +-
.../juneau/parser/InputStreamParserBuilder.java | 30 +-
.../main/java/org/apache/juneau/parser/Parser.java | 58 +-
.../org/apache/juneau/parser/ParserBuilder.java | 302 +++-
.../org/apache/juneau/parser/ReaderParser.java | 10 +-
.../apache/juneau/parser/ReaderParserBuilder.java | 33 +
.../plaintext/PlainTextSerializerBuilder.java | 18 -
.../juneau/serializer/OutputStreamSerializer.java | 1 +
.../serializer/OutputStreamSerializerBuilder.java | 36 +-
.../org/apache/juneau/serializer/Serializer.java | 132 +-
.../juneau/serializer/SerializerBuilder.java | 566 +++++-
.../apache/juneau/serializer/WriterSerializer.java | 47 +-
.../juneau/serializer/WriterSerializerBuilder.java | 166 +-
.../juneau/soap/SoapXmlSerializerBuilder.java | 18 -
.../java/org/apache/juneau/uon/UonSerializer.java | 7 +-
.../apache/juneau/uon/UonSerializerBuilder.java | 83 +-
.../urlencoding/UrlEncodingSerializerBuilder.java | 24 -
.../apache/juneau/xml/XmlSerializerBuilder.java | 18 -
juneau-doc/src/main/javadoc/overview.html | 30 +
.../apache/juneau/rest/client2/RestClientTest.java | 162 --
.../org/apache/juneau/rest/client2/RestClient.java | 4 +-
.../juneau/rest/client2/RestClientBuilder.java | 1854 ++++++++++++++++----
.../apache/juneau/rest/mock2/MockRestClient.java | 66 -
39 files changed, 2924 insertions(+), 1193 deletions(-)
diff --git a/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializerBuilder.java b/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializerBuilder.java
index 8e6fb61..c87200d 100644
--- a/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializerBuilder.java
+++ b/juneau-core/juneau-marshall-rdf/src/main/java/org/apache/juneau/jena/RdfSerializerBuilder.java
@@ -1763,36 +1763,18 @@ public class RdfSerializerBuilder extends WriterSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public RdfSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public RdfSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public RdfSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public RdfSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public RdfSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public RdfSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseBuilder.java
index ad496ea..d2ba77f 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseBuilder.java
@@ -52,7 +52,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* Configuration property: Automatically detect POJO recursions.
*
* <p>
- * Specifies that recursions should be checked for during traversal.
+ * When enabled, specifies that recursions should be checked for during traversal.
*
* <p>
* Recursions can occur when traversing models that aren't true trees but rather contain loops.
@@ -66,7 +66,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * <jc>// Create a serializer that automatically checks for recursions.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .detectRecursions(<jk>true</jk>)
@@ -79,7 +79,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* A a = <jk>new</jk> A();
* a.<jf>f</jf> = a;
*
- * <jc>// Throws a SerializeException</jc>
+ * <jc>// Throws a SerializeException and not a StackOverflowError</jc>
* String json = s.serialize(a);
* </p>
*
@@ -101,7 +101,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* Configuration property: Automatically detect POJO recursions.
*
* <p>
- * Specifies that recursions should be checked for during traversal.
+ * When enabled, specifies that recursions should be checked for during traversal.
*
* <p>
* Recursions can occur when traversing models that aren't true trees but rather contain loops.
@@ -115,7 +115,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * <jc>// Create a serializer that automatically checks for recursions.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .detectRecursions()
@@ -128,7 +128,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* A a = <jk>new</jk> A();
* a.<jf>f</jf> = a;
*
- * <jc>// Throws a SerializeException</jc>
+ * <jc>// Throws a SerializeException and not a StackOverflowError</jc>
* String json = s.serialize(a);
* </p>
*
@@ -147,7 +147,7 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* Configuration property: Ignore recursion errors.
*
* <p>
- * If <jk>true</jk>, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
+ * When enabled, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
*
* <p>
* For example, if a model contains the links A->B->C->A, then the JSON generated will look like
@@ -157,9 +157,14 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* {A:{B:{C:<jk>null</jk>}}}
* </p>
*
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * <jc>// Create a serializer that ignores recursions.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .ignoreRecursions(<jk>true</jk>)
@@ -204,9 +209,14 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* {A:{B:{C:<jk>null</jk>}}}
* </p>
*
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * <jc>// Create a serializer ignores recursions.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .ignoreRecursions()
@@ -240,6 +250,22 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* <p>
* The initial indentation level at the root.
*
+ * <p>
+ * Useful when constructing document fragments that need to be indented at a certain level when whitespace is enabled.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer with whitespace enabled and an initial depth of 2.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .ws()
+ * .initialDepth(2)
+ * .build();
+ *
+ * <jc>// Produces "\t\t{\n\t\t\t'foo':'bar'\n\t\t}\n"</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_initialDepth}
* </ul>
@@ -258,9 +284,22 @@ public class BeanTraverseBuilder extends BeanContextBuilder {
* Configuration property: Max traversal depth.
*
* <p>
- * Abort traversal if specified depth is reached in the POJO tree.
- * <br>If this depth is exceeded, an exception is thrown.
- * <br>This prevents stack overflows from occurring when trying to traverse models with recursive references.
+ * When enabled, abort traversal if specified depth is reached in the POJO tree.
+ *
+ * <p>
+ * If this depth is exceeded, an exception is thrown.
+ *
+ * <p>
+ * This prevents stack overflows from occurring when trying to traverse models with recursive references.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that throws an exception if the depth reaches greater than 20.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .maxDepth(20)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_maxDepth}
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseContext.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseContext.java
index dcad339..a35af8a 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseContext.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanTraverseContext.java
@@ -56,8 +56,9 @@ public abstract class BeanTraverseContext extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * Specifies that recursions should be checked for during traversal.
+ * When enabled, specifies that recursions should be checked for during traversal.
*
* <p>
* Recursions can occur when traversing models that aren't true trees but rather contain loops.
@@ -71,7 +72,7 @@ public abstract class BeanTraverseContext extends BeanContext {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * <jc>// Create a serializer that automatically checks for recursions.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .set(<jsf>BEANTRAVERSE_detectRecursions</jsf>, <jk>true</jk>)
@@ -114,20 +115,26 @@ public abstract class BeanTraverseContext extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
+ * When enabled, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
*
* <p>
* For example, if a model contains the links A->B->C->A, then the JSON generated will look like
* the following when <jsf>BEANTRAVERSE_ignoreRecursions</jsf> is <jk>true</jk>...
*
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
* <p class='bcode w800'>
* {A:{B:{C:<jk>null</jk>}}}
* </p>
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * <jc>// Create a serializer ignores recursions.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .set(<jsf>BEANTRAVERSE_ignoreRecursions</jsf>, <jk>true</jk>)
@@ -169,9 +176,12 @@ public abstract class BeanTraverseContext extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* The initial indentation level at the root.
- * <br>Useful when constructing document fragments that need to be indented at a certain level.
+ *
+ * <p>
+ * Useful when constructing document fragments that need to be indented at a certain level when whitespace is enabled.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
@@ -218,13 +228,19 @@ public abstract class BeanTraverseContext extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
+ * <p>
+ * When enabled, abort traversal if specified depth is reached in the POJO tree.
+ *
+ * <p>
+ * If this depth is exceeded, an exception is thrown.
+ *
* <p>
- * Abort traversal if specified depth is reached in the POJO tree.
- * <br>If this depth is exceeded, an exception is thrown.
+ * This prevents stack overflows from occurring when trying to traverse models with recursive references.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a serializer that throws an exception if the depth is greater than 20.</jc>
+ * <jc>// Create a serializer that throws an exception if the depth reaches greater than 20.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .maxDepth(20)
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/csv/CsvSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/csv/CsvSerializerBuilder.java
index 75092c1..545562b 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/csv/CsvSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/csv/CsvSerializerBuilder.java
@@ -884,36 +884,18 @@ public class CsvSerializerBuilder extends WriterSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public CsvSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public CsvSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public CsvSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public CsvSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public CsvSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public CsvSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerBuilder.java
index 2fa6fe8..d5a41a2 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerBuilder.java
@@ -1410,36 +1410,18 @@ public class HtmlDocSerializerBuilder extends HtmlStrippedDocSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlDocSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlDocSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlDocSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlDocSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlDocSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlDocSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSchemaSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSchemaSerializerBuilder.java
index 222cef4..a908532 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSchemaSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSchemaSerializerBuilder.java
@@ -1125,36 +1125,18 @@ public class HtmlSchemaSerializerBuilder extends HtmlSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlSchemaSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlSchemaSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlSchemaSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlSchemaSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlSchemaSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlSchemaSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java
index 45b32d3..11b85e2 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java
@@ -1058,36 +1058,18 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializerBuilder.java
index ec4bc5c..be26355 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializerBuilder.java
@@ -884,36 +884,18 @@ public class HtmlStrippedDocSerializerBuilder extends HtmlSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlStrippedDocSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlStrippedDocSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlStrippedDocSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlStrippedDocSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public HtmlStrippedDocSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public HtmlStrippedDocSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jso/JsoSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jso/JsoSerializerBuilder.java
index 629df6e..ab3a13a 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jso/JsoSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jso/JsoSerializerBuilder.java
@@ -883,36 +883,18 @@ public class JsoSerializerBuilder extends OutputStreamSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public JsoSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsoSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public JsoSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsoSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public JsoSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsoSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSchemaSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSchemaSerializerBuilder.java
index d71db9b..5ecf545 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSchemaSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSchemaSerializerBuilder.java
@@ -1112,36 +1112,18 @@ public class JsonSchemaSerializerBuilder extends JsonSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public JsonSchemaSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsonSchemaSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public JsonSchemaSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsonSchemaSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public JsonSchemaSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsonSchemaSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializerBuilder.java
index 453da59..fa3c282 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializerBuilder.java
@@ -980,36 +980,18 @@ public class JsonSerializerBuilder extends WriterSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public JsonSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsonSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public JsonSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsonSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public JsonSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public JsonSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/SimpleJsonSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/SimpleJsonSerializerBuilder.java
index e411cb4..46911cc 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/SimpleJsonSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/SimpleJsonSerializerBuilder.java
@@ -883,36 +883,18 @@ public class SimpleJsonSerializerBuilder extends JsonSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public SimpleJsonSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public SimpleJsonSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public SimpleJsonSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public SimpleJsonSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public SimpleJsonSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public SimpleJsonSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java
index 8cb3551..a9e5cff 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java
@@ -883,36 +883,18 @@ public class MsgPackSerializerBuilder extends OutputStreamSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public MsgPackSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public MsgPackSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public MsgPackSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public MsgPackSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public MsgPackSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public MsgPackSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiCommon.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiCommon.java
index 87a646c..7b382c7 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiCommon.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiCommon.java
@@ -46,6 +46,7 @@ public interface OpenApiCommon {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Specifies the format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#format()}.
*
@@ -72,26 +73,23 @@ public interface OpenApiCommon {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a plain-text serializer.</jc>
- * OpenApiSerializer s1 = OpenApiSerializer.
+ * OpenApiSerializer s1 = OpenApiSerializer
* .<jsm>create</jsm>()
* .build();
*
* <jc>// Create a UON serializer.</jc>
- * OpenApiSerializer s2 = OpenApiSerializer.
+ * OpenApiSerializer s2 = OpenApiSerializer
* .<jsm>create</jsm>()
* .format(<jsf>UON</jsf>)
* .build();
*
- * OMap m = OMap.<jsm>of</jsm>(
- * <js>"foo"</js>, <js>"bar"</js>,
- * <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
- * );
+ * String string = <js>"foo bar"</js>;
*
- * <jc>// Produces: "foo=bar,baz=qux\,true\,123"</jc>
- * String v1 = s1.serialize(m);
+ * <jc>// Produces: "foo bar"</jc>
+ * String v1 = s.serialize(string);
*
- * <jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc>
- * String v2 = s2.serialize(m);
+ * <jc>// Produces: "'foo bar'"</jc>
+ * String v2 = s2.serialize(string);
* </p>
*/
public static final String OAPI_format = PREFIX + ".format.s";
@@ -120,6 +118,7 @@ public interface OpenApiCommon {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Specifies the collection format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#collectionFormat()}.
*
@@ -140,20 +139,27 @@ public interface OpenApiCommon {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a serializer using CSV for collections.</jc>
- * OpenApiSerializer s2 = OpenApiSerializer.
+ * OpenApiSerializer s1 = OpenApiSerializer
* .<jsm>create</jsm>()
* .collectionFormat(<jsf>CSV</jsf>)
* .build();
*
* <jc>// Create a serializer using UON for collections.</jc>
- * OpenApiSerializer s2 = OpenApiSerializer.
+ * OpenApiSerializer s2 = OpenApiSerializer
* .<jsm>create</jsm>()
* .collectionFormat(<jsf>UON</jsf>)
* .build();
*
- * OList l = OList.<jsm>of</jsm>(<js>"foo"</js>, <js>"bar"</js>);
+ * <jc>// An arbitrary data structure.</jc>
+ * OList l = OList.<jsm>of</jsm>(
+ * <js>"foo"</js>,
+ * <js>"bar"</js>,
+ * OMap.<jsm>of</jsm>(
+ * <js>"baz"</js>, OList.<jsm>of</jsm>(<js>"qux"</js>,<js>"true"</js>,<js>"123"</js>)
+ * )
+ * );
*
- * <jc>// Produces: "foo=bar,baz=qux,true,123"</jc>
+ * <jc>// Produces: "foo=bar,baz=qux\,true\,123"</jc>
* String v1 = s1.serialize(l)
*
* <jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc>
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiParserBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiParserBuilder.java
index 4f82fae..b9a0dc1 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiParserBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiParserBuilder.java
@@ -83,6 +83,28 @@ public class OpenApiParserBuilder extends UonParserBuilder {
* </ul>
* </ul>
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a plain-text parser.</jc>
+ * OpenApiParser p1 = OpenApiParser
+ * .<jsm>create</jsm>()
+ * .build();
+ *
+ * <jc>// Create a UON parser.</jc>
+ * OpenApiParser p2 = OpenApiParser
+ * .<jsm>create</jsm>()
+ * .format(<jsf>UON</jsf>)
+ * .build();
+ *
+ * String string = <js>"foo bar"</js>;
+ *
+ * <jc>// Parse a plain-text string.</jc>
+ * String v1 = s.serialize(<js>"foo bar"</js>);
+ *
+ * <jc>// Parse a UON string.</jc>
+ * String v2 = s2.serialize(<js>"'foo bar'"</js>);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link OpenApiCommon#OAPI_format}
* </ul>
@@ -115,6 +137,27 @@ public class OpenApiParserBuilder extends UonParserBuilder {
* </ul>
* </ul>
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using CSV for collections.</jc>
+ * OpenApiParser p1 = OpenApiParser
+ * .<jsm>create</jsm>()
+ * .collectionFormat(<jsf>CSV</jsf>)
+ * .build();
+ *
+ * <jc>// Create a serializer using UON for collections.</jc>
+ * OpenApiParser p2 = OpenApiParser
+ * .<jsm>create</jsm>()
+ * .collectionFormat(<jsf>UON</jsf>)
+ * .build();
+ *
+ * <jc>// Parse CSV.</jc>
+ * OList l1 = p1.parse(<js>"foo=bar,baz=qux\,true\,123"</js>, OList.<jk>class</jk>)
+ *
+ * <jc>// Parse UON.</jc>
+ * OList l2 = p2.parse(<js>"(foo=bar,baz=@(qux,true,123))"</js>, OList.<jk>class</jk>)
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link OpenApiCommon#OAPI_collectionFormat}
* </ul>
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiSerializerBuilder.java
index 1d9a568..47a64cb 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/oapi/OpenApiSerializerBuilder.java
@@ -83,6 +83,28 @@ public class OpenApiSerializerBuilder extends UonSerializerBuilder {
* </ul>
* </ul>
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a plain-text serializer.</jc>
+ * OpenApiSerializer s1 = OpenApiSerializer
+ * .<jsm>create</jsm>()
+ * .build();
+ *
+ * <jc>// Create a UON serializer.</jc>
+ * OpenApiSerializer s2 = OpenApiSerializer
+ * .<jsm>create</jsm>()
+ * .format(<jsf>UON</jsf>)
+ * .build();
+ *
+ * String string = <js>"foo bar"</js>;
+ *
+ * <jc>// Produces: "foo bar"</jc>
+ * String v1 = s.serialize(string);
+ *
+ * <jc>// Produces: "'foo bar'"</jc>
+ * String v2 = s2.serialize(string);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link OpenApiCommon#OAPI_format}
* </ul>
@@ -115,6 +137,36 @@ public class OpenApiSerializerBuilder extends UonSerializerBuilder {
* </ul>
* </ul>
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer using CSV for collections.</jc>
+ * OpenApiSerializer s1 = OpenApiSerializer
+ * .<jsm>create</jsm>()
+ * .collectionFormat(<jsf>CSV</jsf>)
+ * .build();
+ *
+ * <jc>// Create a serializer using UON for collections.</jc>
+ * OpenApiSerializer s2 = OpenApiSerializer
+ * .<jsm>create</jsm>()
+ * .collectionFormat(<jsf>UON</jsf>)
+ * .build();
+ *
+ * <jc>// An arbitrary data structure.</jc>
+ * OList l = OList.<jsm>of</jsm>(
+ * <js>"foo"</js>,
+ * <js>"bar"</js>,
+ * OMap.<jsm>of</jsm>(
+ * <js>"baz"</js>, OList.<jsm>of</jsm>(<js>"qux"</js>,<js>"true"</js>,<js>"123"</js>)
+ * )
+ * );
+ *
+ * <jc>// Produces: "foo=bar,baz=qux\,true\,123"</jc>
+ * String v1 = s1.serialize(l)
+ *
+ * <jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc>
+ * String v2 = s2.serialize(l)
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link OpenApiCommon#OAPI_collectionFormat}
* </ul>
@@ -958,36 +1010,18 @@ public class OpenApiSerializerBuilder extends UonSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public OpenApiSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public OpenApiSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public OpenApiSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public OpenApiSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public OpenApiSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public OpenApiSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
@@ -1054,12 +1088,6 @@ public class OpenApiSerializerBuilder extends UonSerializerBuilder {
}
@Override /* GENERATED - UonSerializerBuilder */
- public OpenApiSerializerBuilder paramFormat(String value) {
- super.paramFormat(value);
- return this;
- }
-
- @Override /* GENERATED - UonSerializerBuilder */
public OpenApiSerializerBuilder paramFormat(ParamFormat value) {
super.paramFormat(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParser.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParser.java
index cd857a2..72f4e0a 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParser.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParser.java
@@ -59,11 +59,11 @@ public abstract class InputStreamParser extends Parser {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* When using the {@link #parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
* when converting the string into a byte array.
*
- *
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser that parses from BASE64.</jc>
@@ -77,6 +77,10 @@ public abstract class InputStreamParser extends Parser {
* .<jsm>create</jsm>()
* .set(<jsf>ISPARSER_binaryFormat</jsf>, <js>"BASE64"</js>)
* .build();
+ *
+ * String input = <js>"base64-encoded-string"</js>;
+ *
+ * MyBean myBean = p.parse(input, MyBean.<jk>class</jk>);
* </p>
*/
public static final String ISPARSER_binaryFormat = PREFIX + ".binaryFormat.s";
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParserBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParserBuilder.java
index f371c73..921d3fd 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParserBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/InputStreamParserBuilder.java
@@ -53,9 +53,22 @@ public class InputStreamParserBuilder extends ParserBuilder {
* Configuration property: Binary input format.
*
* <p>
- * When using the {@link Parser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
+ * When using the {@link InputStreamParser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
* when converting the string into a byte array.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser that parses from BASE64.</jc>
+ * InputStreamParser p = MsgPackParser
+ * .<jsm>create</jsm>()
+ * .binaryFormat(<jsf>BASE64</jsf>)
+ * .build();
+ *
+ * String input = <js>"base64-encoded-string"</js>;
+ *
+ * MyBean myBean = p.parse(input, MyBean.<jk>class</jk>);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link InputStreamParser#ISPARSER_binaryFormat}
* </ul>
@@ -74,9 +87,22 @@ public class InputStreamParserBuilder extends ParserBuilder {
* Configuration property: Binary input format.
*
* <p>
- * When using the {@link Parser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
+ * When using the {@link InputStreamParser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
* when converting the string into a byte array.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser that parses from BASE64.</jc>
+ * InputStreamParser p = MsgPackParser
+ * .<jsm>create</jsm>()
+ * .binaryFormat(<js>"BASE64"</js>)
+ * .build();
+ *
+ * String input = <js>"base64-encoded-string"</js>;
+ *
+ * MyBean myBean = p.parse(input, MyBean.<jk>class</jk>);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link InputStreamParser#ISPARSER_binaryFormat}
* </ul>
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/Parser.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/Parser.java
index 7d3127a..f4d88cf 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/Parser.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/Parser.java
@@ -150,20 +150,21 @@ public abstract class Parser extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
+ * When enabled, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
* after parsing is complete.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser using strict mode.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .autoCloseStreams()
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>PARSER_autoCloseStreams</jsf>, <jk>true</jk>)
* .build();
@@ -199,6 +200,7 @@ public abstract class Parser extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* When parse errors occur, this specifies the number of lines of input before and after the
* error location to be printed as part of the exception message.
@@ -206,14 +208,14 @@ public abstract class Parser extends BeanContext {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser whose exceptions print out 100 lines before and after the parse error location.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .debug() <jc>// Enable debug mode to capture Reader contents as strings.</jc>
* .debugOuputLines(100)
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>BEAN_debug</jsf>, <jk>true</jk>)
* .set(<jsf>PARSER_debugOutputLines</jsf>, 100)
@@ -250,6 +252,7 @@ public abstract class Parser extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Class used to listen for errors and warnings that occur during parsing.
*
@@ -269,13 +272,13 @@ public abstract class Parser extends BeanContext {
* }
*
* <jc>// Create a parser using our listener.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .listener(MyParserListener.<jk>class</jk>)
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>PARSER_listener</jsf>, MyParserListener.<jk>class</jk>)
* .build();
@@ -321,8 +324,9 @@ public abstract class Parser extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, strict mode for the parser is enabled.
+ * When enabled, strict mode for the parser is enabled.
*
* <p>
* Strict mode can mean different things for different parsers.
@@ -355,24 +359,24 @@ public abstract class Parser extends BeanContext {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser using strict mode.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .strict()
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>PARSER_strict</jsf>, <jk>true</jk>)
* .build();
*
* <jc>// Use it.</jc>
- * <jk>try</jk> {
- * String json = <js>"{unquotedAttr:'value'}"</js>;
+ * <jk>try</jk> {
+ * String json = <js>"{unquotedAttr:'value'}"</js>;
* MyBean myBean = p.parse(json, MyBean.<jk>class</jk>);
- * } <jk>catch</jk> (ParseException e) {
- * <jsm>assertTrue</jsm>(e.getMessage().contains(<js>"Unquoted attribute detected."</js>);
- * }
+ * } <jk>catch</jk> (ParseException e) {
+ * <jsm>assertTrue</jsm>(e.getMessage().contains(<js>"Unquoted attribute detected."</js>);
+ * }
* </p>
*/
public static final String PARSER_strict = PREFIX + ".strict.b";
@@ -401,28 +405,31 @@ public abstract class Parser extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser with trim-strings enabled.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .trimStrings()
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>PARSER_trimStrings</jsf>, <jk>true</jk>)
* .build();
*
* <jc>// Use it.</jc>
- * String json = <js>"{foo:' bar '}"</js>;
- * Map<String,String> m = p.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
- * <jsm>assertEquals</jsm>(<js>"bar"</js>, m.get(<js>"foo"</js>));
+ * String json = <js>"{' foo ':' bar '}"</js>;
+ * Map<String,String> map = p.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
+ *
+ * <jc>// Make sure strings are parsed.</jc>
+ * <jsm>assertEquals</jsm>(<js>"bar"</js>, map.get(<js>"foo"</js>));
* </p>
*/
public static final String PARSER_trimStrings = PREFIX + ".trimStrings.b";
@@ -451,8 +458,9 @@ public abstract class Parser extends BeanContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, don't use internal buffering during parsing.
+ * When enabled, don't use internal buffering during parsing.
*
* <p>
* This is useful in cases when you want to parse the same input stream or reader multiple times
@@ -462,13 +470,13 @@ public abstract class Parser extends BeanContext {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser using strict mode.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .unbuffered()
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>PARSER_unbuffered</jsf>, <jk>true</jk>)
* .build();
@@ -497,8 +505,6 @@ public abstract class Parser extends BeanContext {
* <li>RDF parsers - These read everything into an internal model before any parsing begins.
* </ul>
* </ul>
- *
- * If <jk>true</jk>, don't use internal buffering during parsing.
*/
public static final String PARSER_unbuffered = PREFIX + ".unbuffered.b";
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserBuilder.java
index bee1039..c95ec97 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserBuilder.java
@@ -19,10 +19,15 @@ import java.lang.reflect.*;
import java.util.*;
import org.apache.juneau.*;
+import org.apache.juneau.html.*;
import org.apache.juneau.http.*;
import org.apache.juneau.internal.*;
+import org.apache.juneau.json.*;
+import org.apache.juneau.msgpack.*;
import org.apache.juneau.reflect.*;
import org.apache.juneau.svl.*;
+import org.apache.juneau.uon.*;
+import org.apache.juneau.xml.*;
/**
* Builder class for building instances of parsers.
@@ -53,9 +58,23 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Auto-close streams.
*
* <p>
- * If <jk>true</jk>, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
+ * When enabled, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
* after parsing is complete.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .autoCloseStreams(<jk>true</jk>)
+ * .build();
+ *
+ * Reader r = <jk>new</jk> FileReader(<js>"/tmp/myfile.json"</js>);
+ * MyBean myBean = p.parse(r, MyBean.<jk>class</jk>);
+ *
+ * <jsm>assertTrue</jsm>(r.isClosed());
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_autoCloseStreams}
* </ul>
@@ -74,7 +93,22 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Auto-close streams.
*
* <p>
- * Shortcut for calling <code>autoCloseStreams(<jk>true</jk>)</code>.
+ * When enabled, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
+ * after parsing is complete.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .autoCloseStreams()
+ * .build();
+ *
+ * Reader r = <jk>new</jk> FileReader(<js>"/tmp/myfile.json"</js>);
+ * MyBean myBean = p.parse(r, MyBean.<jk>class</jk>);
+ *
+ * <jsm>assertTrue</jsm>(r.isClosed());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_autoCloseStreams}
@@ -94,6 +128,23 @@ public class ParserBuilder extends BeanContextBuilder {
* When parse errors occur, this specifies the number of lines of input before and after the
* error location to be printed as part of the exception message.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser whose exceptions print out 100 lines before and after the parse error location.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .debug() <jc>// Enable debug mode to capture Reader contents as strings.</jc>
+ * .debugOuputLines(100)
+ * .build();
+ *
+ * Reader r = <jk>new</jk> FileReader(<js>"/tmp/mybadfile.json"</js>);
+ * <jk>try</jk> {
+ * p.parse(r, Object.<jk>class</jk>);
+ * } <jk>catch</jk> (ParseException e) {
+ * System.<jsf>err</jsf>.println(e.getMessage()); <jc>// Will display 200 lines of the output.</jc>
+ * }
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_debugOutputLines}
* </ul>
@@ -114,6 +165,42 @@ public class ParserBuilder extends BeanContextBuilder {
* <p>
* Class used to listen for errors and warnings that occur during parsing.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Define our parser listener.</jc>
+ * <jc>// Simply captures all unknown bean property events.</jc>
+ * <jk>public class</jk> MyParserListener <jk>extends</jk> ParserListener {
+ *
+ * <jc>// A simple property to store our events.</jc>
+ * <jk>public</jk> List<String> <jf>events</jf> = <jk>new</jk> LinkedList<>();
+ *
+ * <ja>@Override</ja>
+ * <jk>public</jk> <T> <jk>void</jk> onUnknownBeanProperty(ParserSession session, ParserPipe pipe, String propertyName, Class<T> beanClass, T bean, <jk>int</jk> line, <jk>int</jk> col) {
+ * <jf>events</jf>.add(propertyName + <js>","</js> + line + <js>","</js> + col);
+ * }
+ * }
+ *
+ * <jc>// Create a parser using our listener.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .listener(MyParserListener.<jk>class</jk>)
+ * .build();
+ *
+ * <jc>// Create a session object.</jc>
+ * <jc>// Needed because listeners are created per-session.</jc>
+ * <jk>try</jk> (ReaderParserSession s = p.createSession()) {
+ *
+ * <jc>// Parse some JSON object.</jc>
+ * MyBean myBean = s.parse(<js>"{...}"</js>, MyBean.<jk>class</jk>);
+ *
+ * <jc>// Get the listener.</jc>
+ * MyParserListener l = s.getListener(MyParserListener.<jk>class</jk>);
+ *
+ * <jc>// Dump the results to the console.</jc>
+ * SimpleJsonSerializer.<jsf>DEFAULT</jsf>.println(l.<jf>events</jf>);
+ * }
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_listener}
* </ul>
@@ -130,7 +217,52 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Strict mode.
*
* <p>
- * If <jk>true</jk>, strict mode for the parser is enabled.
+ * When enabled, strict mode for the parser is enabled.
+ *
+ * <p>
+ * Strict mode can mean different things for different parsers.
+ *
+ * <table class='styled'>
+ * <tr><th>Parser class</th><th>Strict behavior</th></tr>
+ * <tr>
+ * <td>All reader-based parsers</td>
+ * <td>
+ * When enabled, throws {@link ParseException ParseExceptions} on malformed charset input.
+ * Otherwise, malformed input is ignored.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link JsonParser}</td>
+ * <td>
+ * When enabled, throws exceptions on the following invalid JSON syntax:
+ * <ul>
+ * <li>Unquoted attributes.
+ * <li>Missing attribute values.
+ * <li>Concatenated strings.
+ * <li>Javascript comments.
+ * <li>Numbers and booleans when Strings are expected.
+ * <li>Numbers valid in Java but not JSON (e.g. octal notation, etc...)
+ * </ul>
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .strict(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Use it.</jc>
+ * <jk>try</jk> {
+ * String json = <js>"{unquotedAttr:'value'}"</js>;
+ * MyBean myBean = p.parse(json, MyBean.<jk>class</jk>);
+ * } <jk>catch</jk> (ParseException e) {
+ * <jsm>assertTrue</jsm>(e.getMessage().contains(<js>"Unquoted attribute detected."</js>);
+ * }
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_strict}
@@ -150,7 +282,52 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Strict mode.
*
* <p>
- * Shortcut for calling <code>strict(<jk>true</jk>)</code>.
+ * When enabled, strict mode for the parser is enabled.
+ *
+ * <p>
+ * Strict mode can mean different things for different parsers.
+ *
+ * <table class='styled'>
+ * <tr><th>Parser class</th><th>Strict behavior</th></tr>
+ * <tr>
+ * <td>All reader-based parsers</td>
+ * <td>
+ * When enabled, throws {@link ParseException ParseExceptions} on malformed charset input.
+ * Otherwise, malformed input is ignored.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link JsonParser}</td>
+ * <td>
+ * When enabled, throws exceptions on the following invalid JSON syntax:
+ * <ul>
+ * <li>Unquoted attributes.
+ * <li>Missing attribute values.
+ * <li>Concatenated strings.
+ * <li>Javascript comments.
+ * <li>Numbers and booleans when Strings are expected.
+ * <li>Numbers valid in Java but not JSON (e.g. octal notation, etc...)
+ * </ul>
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .strict()
+ * .build();
+ *
+ * <jc>// Use it.</jc>
+ * <jk>try</jk> {
+ * String json = <js>"{unquotedAttr:'value'}"</js>;
+ * MyBean myBean = p.parse(json, MyBean.<jk>class</jk>);
+ * } <jk>catch</jk> (ParseException e) {
+ * <jsm>assertTrue</jsm>(e.getMessage().contains(<js>"Unquoted attribute detected."</js>);
+ * }
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_strict}
@@ -167,9 +344,25 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Trim parsed strings.
*
* <p>
- * If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser with trim-strings enabled.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .trimStrings(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Use it.</jc>
+ * String json = <js>"{' foo ':' bar '}"</js>;
+ * Map<String,String> map = p.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
+ *
+ * <jc>// Make sure strings are parsed.</jc>
+ * <jsm>assertEquals</jsm>(<js>"bar"</js>, map.get(<js>"foo"</js>));
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_trimStrings}
* </ul>
@@ -188,7 +381,24 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Trim parsed strings.
*
* <p>
- * Shortcut for calling <code>trimStrings(<jk>true</jk>)</code>.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being added to
+ * the POJO.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser with trim-strings enabled.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .trimStrings()
+ * .build();
+ *
+ * <jc>// Use it.</jc>
+ * String json = <js>"{' foo ':' bar '}"</js>;
+ * Map<String,String> map = p.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
+ *
+ * <jc>// Make sure strings are parsed.</jc>
+ * <jsm>assertEquals</jsm>(<js>"bar"</js>, map.get(<js>"foo"</js>));
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_trimStrings}
@@ -205,7 +415,45 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Unbuffered.
*
* <p>
- * If <jk>true</jk>, don't use internal buffering during parsing.
+ * When enabled, don't use internal buffering during parsing.
+ *
+ * <p>
+ * This is useful in cases when you want to parse the same input stream or reader multiple times
+ * because it may contain multiple independent POJOs to parse.
+ * <br>Buffering would cause the parser to read past the current POJO in the stream.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .unbuffered(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// If you're calling parse on the same input multiple times, use a session instead of the parser directly.</jc>
+ * <jc>// It's more efficient because we don't need to recalc the session settings again. </jc>
+ * ReaderParserSession s = p.createSession();
+ *
+ * <jc>// Read input with multiple POJOs</jc>
+ * Reader json = <jk>new</jk> StringReader(<js>"{foo:'bar'}{foo:'baz'}"</js>);
+ * MyBean myBean1 = s.parse(json, MyBean.<jk>class</jk>);
+ * MyBean myBean2 = s.parse(json, MyBean.<jk>class</jk>);
+ * </p>
+ *
+ * <ul class='notes'>
+ * <li>
+ * This only allows for multi-input streams for the following parsers:
+ * <ul>
+ * <li class='jc'>{@link JsonParser}
+ * <li class='jc'>{@link UonParser}
+ * </ul>
+ * It has no effect on the following parsers:
+ * <ul>
+ * <li class='jc'>{@link MsgPackParser} - It already doesn't use buffering.
+ * <li class='jc'>{@link XmlParser}, {@link HtmlParser} - These use StAX which doesn't allow for more than one root element anyway.
+ * <li>RDF parsers - These read everything into an internal model before any parsing begins.
+ * </ul>
+ * </ul>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_unbuffered}
@@ -225,7 +473,45 @@ public class ParserBuilder extends BeanContextBuilder {
* Configuration property: Unbuffered.
*
* <p>
- * Shortcut for calling <code>unbuffered(<jk>true</jk>)</code>.
+ * When enabled, don't use internal buffering during parsing.
+ *
+ * <p>
+ * This is useful in cases when you want to parse the same input stream or reader multiple times
+ * because it may contain multiple independent POJOs to parse.
+ * <br>Buffering would cause the parser to read past the current POJO in the stream.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .unbuffered(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// If you're calling parse on the same input multiple times, use a session instead of the parser directly.</jc>
+ * <jc>// It's more efficient because we don't need to recalc the session settings again. </jc>
+ * ReaderParserSession s = p.createSession();
+ *
+ * <jc>// Read input with multiple POJOs</jc>
+ * Reader json = <jk>new</jk> StringReader(<js>"{foo:'bar'}{foo:'baz'}"</js>);
+ * MyBean myBean1 = s.parse(json, MyBean.<jk>class</jk>);
+ * MyBean myBean2 = s.parse(json, MyBean.<jk>class</jk>);
+ * </p>
+ *
+ * <ul class='notes'>
+ * <li>
+ * This only allows for multi-input streams for the following parsers:
+ * <ul>
+ * <li class='jc'>{@link JsonParser}
+ * <li class='jc'>{@link UonParser}
+ * </ul>
+ * It has no effect on the following parsers:
+ * <ul>
+ * <li class='jc'>{@link MsgPackParser} - It already doesn't use buffering.
+ * <li class='jc'>{@link XmlParser}, {@link HtmlParser} - These use StAX which doesn't allow for more than one root element anyway.
+ * <li>RDF parsers - These read everything into an internal model before any parsing begins.
+ * </ul>
+ * </ul>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_unbuffered}
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParser.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParser.java
index a3cf956..f105366 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParser.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParser.java
@@ -62,6 +62,7 @@ public abstract class ReaderParser extends Parser {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* The character set to use for reading <c>Files</c> from the file system.
*
@@ -74,13 +75,13 @@ public abstract class ReaderParser extends Parser {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser that reads UTF-8 files.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .fileCharset(<js>"UTF-8"</js>)
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>RPARSER_fileCharset</jsf>, <js>"UTF-8"</js>)
* .build();
@@ -114,6 +115,7 @@ public abstract class ReaderParser extends Parser {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* The character set to use for converting <c>InputStreams</c> and byte arrays to readers.
*
@@ -123,13 +125,13 @@ public abstract class ReaderParser extends Parser {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a parser that reads UTF-8 files.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .streamCharset(Charset.<jsm>forName</jsm>(<js>"UTF-8"</js>))
* .build();
*
* <jc>// Same, but use property.</jc>
- * ReaderParser p = JsonParser.
+ * ReaderParser p = JsonParser
* .<jsm>create</jsm>()
* .set(<jsf>RPARSER_streamCharset</jsf>, <js>"UTF-8"</js>)
* .build();
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParserBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParserBuilder.java
index 7fc549f..39bbef3 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParserBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ReaderParserBuilder.java
@@ -56,6 +56,24 @@ public abstract class ReaderParserBuilder extends ParserBuilder {
* <p>
* The character set to use for reading <c>Files</c> from the file system.
*
+ * <p>
+ * Used when passing in files to {@link Parser#parse(Object, Class)}.
+ *
+ * <p>
+ * <js>"DEFAULT"</js> can be used to indicate the JVM default file system charset.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser that reads UTF-8 files.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .fileCharset(<js>"UTF-8"</js>)
+ * .build();
+ *
+ * <jc>// Use it to read a UTF-8 encoded file.</jc>
+ * MyBean myBean = p.parse(<jk>new</jk> File(<js>"MyBean.txt"</js>), MyBean.<jk>class</jk>);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link ReaderParser#RPARSER_fileCharset}
* </ul>
@@ -76,6 +94,21 @@ public abstract class ReaderParserBuilder extends ParserBuilder {
* <p>
* The character set to use for converting <c>InputStreams</c> and byte arrays to readers.
*
+ * <p>
+ * Used when passing in input streams and byte arrays to {@link Parser#parse(Object, Class)}.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser that reads UTF-8 files.</jc>
+ * ReaderParser p = JsonParser
+ * .<jsm>create</jsm>()
+ * .streamCharset(Charset.<jsm>forName</jsm>(<js>"UTF-8"</js>))
+ * .build();
+ *
+ * <jc>// Use it to read a UTF-8 encoded input stream.</jc>
+ * MyBean myBean = p.parse(<jk>new</jk> FileInputStream(<js>"MyBean.txt"</js>), MyBean.<jk>class</jk>);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link ReaderParser#RPARSER_streamCharset}
* </ul>
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/plaintext/PlainTextSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/plaintext/PlainTextSerializerBuilder.java
index a9f95c2..64c2cfb 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/plaintext/PlainTextSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/plaintext/PlainTextSerializerBuilder.java
@@ -884,36 +884,18 @@ public class PlainTextSerializerBuilder extends WriterSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public PlainTextSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public PlainTextSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public PlainTextSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public PlainTextSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public PlainTextSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public PlainTextSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
index 294387f..88b43d1 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
@@ -51,6 +51,7 @@ public abstract class OutputStreamSerializer extends Serializer {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* When using the {@link #serializeToString(Object)} method on stream-based serializers, this defines the format to use
* when converting the resulting byte array to a string.
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializerBuilder.java
index 7eaf678..ec46d0f 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/OutputStreamSerializerBuilder.java
@@ -53,9 +53,25 @@ public class OutputStreamSerializerBuilder extends SerializerBuilder {
* Configuration property: Binary output format.
*
* <p>
- * When using the {@link Serializer#serializeToString(Object)} method on stream-based serializers, this defines the format to use
+ * When using the {@link OutputStreamSerializer#serializeToString(Object)} method on stream-based serializers, this defines the format to use
* when converting the resulting byte array to a string.
*
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that serializes to BASE64.</jc>
+ * OutputStreamSerializer s = MsgPackSerializer
+ * .<jsm>create</jsm>()
+ * .binaryFormat(<jsf>BASE64</jsf>)
+ * .build();
+ *
+ * <jc>// The bean we want to serialize.</jc>
+ * <jk>public class</jk> MyBean {...}
+ *
+ * <jc>// MessagePack will generate BASE64-encoded string.</jc>
+ * String msgPack = s.serializeToString(<jk>new</jk> MyBean());
+ * </p>
+ *
* <ul class='javatree'>
* <li class='jf'>{@link OutputStreamSerializer#OSSERIALIZER_binaryFormat}
* </ul>
@@ -922,36 +938,18 @@ public class OutputStreamSerializerBuilder extends SerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public OutputStreamSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public OutputStreamSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public OutputStreamSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public OutputStreamSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public OutputStreamSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public OutputStreamSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/Serializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/Serializer.java
index a00159d..7b063d2 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/Serializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/Serializer.java
@@ -72,8 +72,9 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
+ * When enabled, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
* through reflection.
*
* <p>
@@ -139,6 +140,10 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
+ * <p>
+ * When enabled, <js>"_type"</js> properties will be added to top-level beans.
+ *
* <p>
* When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
* type information that might normally be included to determine the data type will not be serialized.
@@ -199,6 +204,7 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Class used to listen for errors and warnings that occur during serialization.
*
@@ -218,13 +224,13 @@ public abstract class Serializer extends BeanTraverseContext {
* }
*
* <jc>// Create a serializer using our listener.</jc>
- * WriterSerializer s = JsonSerializer.
+ * WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .listener(MySerializerListener.<jk>class</jk>)
* .build();
*
* <jc>// Same, but use property.</jc>
- * WriterSerializer s = JsonSerializer.
+ * WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_listener</jsf>, MySerializerListener.<jk>class</jk>)
* .build();
@@ -270,14 +276,12 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
- * <p>
- * If <jk>true</jk>, null bean values will be serialized to the output.
*
* <p>
- * Note that not enabling this setting has the following effects on parsing:
- * <ul class='spaced-list'>
- * <li>
- * Map entries with <jk>null</jk> values will be lost.
+ * When enabled, null bean values will be serialized to the output.
+ *
+ * <ul class='notes'>
+ * <li>Not enabling this setting will cause <c>Map</c>s with <jk>null</jk> values to be lost during parsing.
* </ul>
*
* <h5 class='section'>Example:</h5>
@@ -293,6 +297,14 @@ public abstract class Serializer extends BeanTraverseContext {
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_keepNullProperties</jsf>, <jk>true</jk>)
* .build();
+ *
+ * <jc>// Our bean to serialize.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
+ * }
+ *
+ * <jc>// Will contain "{foo:null}".</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
* </p>
*/
public static final String SERIALIZER_keepNullProperties = PREFIX + ".keepNullProperties.b";
@@ -323,10 +335,10 @@ public abstract class Serializer extends BeanTraverseContext {
* <h5 class='section'>Description:</h5>
*
* <p>
- * Copies and sorts the contents of arrays and collections before serializing them.
+ * When enabled, copies and sorts the contents of arrays and collections before serializing them.
*
* <p>
- * Note that this introduces a performance penalty.
+ * Note that this introduces a performance penalty since it requires copying the existing collection.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
@@ -341,6 +353,12 @@ public abstract class Serializer extends BeanTraverseContext {
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_sortCollections</jsf>, <jk>true</jk>)
* .build();
+ *
+ * <jc>// An unsorted array</jc>
+ * String[] array = {<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>}
+ *
+ * <jc>// Produces ["bar","baz","foo"]</jc>
+ * String json = s.serialize(array);
* </p>
*/
public static final String SERIALIZER_sortCollections = PREFIX + ".sortCollections.b";
@@ -371,7 +389,7 @@ public abstract class Serializer extends BeanTraverseContext {
* <h5 class='section'>Description:</h5>
*
* <p>
- * Copies and sorts the contents of maps by their keys before serializing them.
+ * When enabled, copies and sorts the contents of maps by their keys before serializing them.
*
* <p>
* Note that this introduces a performance penalty.
@@ -389,6 +407,12 @@ public abstract class Serializer extends BeanTraverseContext {
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_sortMaps</jsf>, <jk>true</jk>)
* .build();
+ *
+ * <jc>// An unsorted map.</jc>
+ * OMap m = OMap.<jsm>of</jsm>(<js>"foo"</js>,1,<js>"bar"</js>,2,<js>"baz"</js>,3);
+ *
+ * <jc>// Produces {"bar":2,"baz":3,"foo":1}</jc>
+ * String json = s.serialize(array);
* </p>
*/
public static final String SERIALIZER_sortMaps = PREFIX + ".sortMaps.b";
@@ -419,7 +443,7 @@ public abstract class Serializer extends BeanTraverseContext {
* <h5 class='section'>Description:</h5>
*
* <p>
- * If <jk>true</jk>, empty lists and arrays will not be serialized.
+ * When enabled, empty lists and arrays will not be serialized.
*
* <p>
* Note that enabling this setting has the following effects on parsing:
@@ -443,6 +467,14 @@ public abstract class Serializer extends BeanTraverseContext {
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_trimEmptyCollections</jsf>, <jk>true</jk>)
* .build();
+ *
+ * <jc>// A bean with a field with an empty array.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String[] <jf>foo</jf> = {};
+ * }
+ *
+ * <jc>// Produces {}</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
* </p>
*/
public static final String SERIALIZER_trimEmptyCollections = PREFIX + ".trimEmptyCollections.b";
@@ -471,8 +503,9 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, empty map values will not be serialized to the output.
+ * When enabled, empty map values will not be serialized to the output.
*
* <p>
* Note that enabling this setting has the following effects on parsing:
@@ -494,6 +527,14 @@ public abstract class Serializer extends BeanTraverseContext {
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_trimEmptyMaps</jsf>, <jk>true</jk>)
* .build();
+ *
+ * <jc>// A bean with a field with an empty map.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> OMap <jf>foo</jf> = OMap.<jsm>of</jsm>();
+ * }
+ *
+ * <jc>// Produces {}</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
* </p>
*/
public static final String SERIALIZER_trimEmptyMaps = PREFIX + ".trimEmptyMaps.b";
@@ -522,8 +563,9 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, null bean values will not be serialized to the output.
+ * When enabled, null bean values will not be serialized to the output.
*
* <p>
* Note that enabling this setting has the following effects on parsing:
@@ -575,8 +617,9 @@ public abstract class Serializer extends BeanTraverseContext {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
@@ -592,11 +635,12 @@ public abstract class Serializer extends BeanTraverseContext {
* .set(<jsf>SERIALIZER_trimStrings</jsf>, <jk>true</jk>)
* .build();
*
- * Map<String,String> m = <jk>new</jk> HashMap<>();
+ * <jc>// A map with space-padded keys/values</jc>
+ * Map<String,String> map = <jk>new</jk> HashMap<>();
* m.put(<js>" foo "</js>, <js>" bar "</js>);
*
* <jc>// Produces "{foo:'bar'}"</jc>
- * String json = SimpleJsonSerializer.<jsf>DEFAULT</jsf>.toString(m);
+ * String json = s.toString(map);
* </p>
*/
public static final String SERIALIZER_trimStrings = PREFIX + ".trimStrings.b";
@@ -620,11 +664,11 @@ public abstract class Serializer extends BeanTraverseContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link org.apache.juneau.serializer.SerializerBuilder#uriContext(UriContext)}
- * <li class='jm'>{@link org.apache.juneau.serializer.SerializerBuilder#uriContext(String)}
* </ul>
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Bean used for resolution of URIs to absolute or root-relative form.
*
@@ -643,18 +687,24 @@ public abstract class Serializer extends BeanTraverseContext {
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .uriContext(uriContext)
+ * .uriRelativity(<jsf>RESOURCE</jsf>) <jc>// Assume relative paths are relative to servlet.</jc>
+ * .uriResolution(<jsf>ABSOLUTE</jsf>) <jc>// Serialize URLs as absolute paths.</jc>
* .build();
*
* <jc>// Same, but specify as a JSON string.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>)
+ * .uriRelativity(<jsf>RESOURCE</jsf>) <jc>// Assume relative paths are relative to servlet.</jc>
+ * .uriResolution(<jsf>ABSOLUTE</jsf>) <jc>// Serialize URLs as absolute paths.</jc>
* .build();
*
- * <jc>// Same, but use property.</jc>
+ * <jc>// Same, but use properties.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .set(<jsf>SERIALIZER_uriContext</jsf>, uriContext)
+ * .set(<jsf>SERIALIZER_uriRelativity</jsf>, <js>"RESOURCE"</js>)
+ * .set(<jsf>SERIALIZER_uriResolution</jsf>, <js>"ABSOLUTE"</js>)
* .build();
*
* <jc>// Same, but define it on the session args instead.</jc>
@@ -662,7 +712,17 @@ public abstract class Serializer extends BeanTraverseContext {
* <jk>try</jk> (WriterSerializerSession session = s.createSession(sessionArgs)) {
* ...
* }
+ *
+ * <jc>// A relative URL</jc>
+ * URL url = <jk>new</jk> URL(<js>"bar"</js>);
+ *
+ * <jc>// Produces "http://localhost:10000/myContext/myServlet/foo/bar"</jc>
+ * String json = s.toString(url);
* </p>
+ *
+ * <ul class='seealso'>
+ * <li class='link'>{@doc juneau-marshall.URIs}
+ * </ul>
*/
public static final String SERIALIZER_uriContext = PREFIX + ".uriContext.s";
@@ -685,11 +745,11 @@ public abstract class Serializer extends BeanTraverseContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link org.apache.juneau.serializer.SerializerBuilder#uriRelativity(UriRelativity)}
- * <li class='jm'>{@link org.apache.juneau.serializer.SerializerBuilder#uriRelativity(String)}
* </ul>
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Defines what relative URIs are relative to when serializing any of the following:
* <ul>
@@ -701,22 +761,14 @@ public abstract class Serializer extends BeanTraverseContext {
* <p>
* Possible values are:
* <ul class='javatree'>
- * <li class='jf'>{@link UriRelativity#RESOURCE}
+ * <li class='jf'>{@link org.apache.juneau.UriRelativity#RESOURCE}
* - Relative URIs should be considered relative to the servlet URI.
- * <li class='jf'>{@link UriRelativity#PATH_INFO}
+ * <li class='jf'>{@link org.apache.juneau.UriRelativity#PATH_INFO}
* - Relative URIs should be considered relative to the request URI.
* </ul>
*
- * <h5 class='figure'>Example:</h5>
- * <p class='bcode w800'>
- * <jc>// Define a serializer that converts resource-relative URIs to absolute form.</jc>
- * WriterSerializer s = JsonSerializer
- * .<jsm>create</jsm>()
- * .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>)
- * .uriResolution(<jsf>ABSOLUTE</jsf>)
- * .uriRelativity(<jsf>RESOURCE</jsf>)
- * .build();
- * </p>
+ * <p>
+ * See {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriContext} for examples.
*
* <ul class='seealso'>
* <li class='link'>{@doc juneau-marshall.URIs}
@@ -743,11 +795,11 @@ public abstract class Serializer extends BeanTraverseContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link org.apache.juneau.serializer.SerializerBuilder#uriResolution(UriResolution)}
- * <li class='jm'>{@link org.apache.juneau.serializer.SerializerBuilder#uriResolution(String)}
* </ul>
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Defines the resolution level for URIs when serializing any of the following:
* <ul>
@@ -767,16 +819,8 @@ public abstract class Serializer extends BeanTraverseContext {
* - Don't do any URL resolution.
* </ul>
*
- * <h5 class='figure'>Example:</h5>
- * <p class='bcode w800'>
- * <jc>// Define a serializer that converts resource-relative URIs to absolute form.</jc>
- * WriterSerializer s = JsonSerializer
- * .<jsm>create</jsm>()
- * .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>)
- * .uriResolution(<jsf>ABSOLUTE</jsf>)
- * .uriRelativity(<jsf>RESOURCE</jsf>)
- * .build();
- * </p>
+ * <p>
+ * See {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriContext} for examples.
*
* <ul class='seealso'>
* <li class='link'>{@doc juneau-marshall.URIs}
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
index f0844f4..d3a27f8 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
@@ -19,6 +19,7 @@ import java.lang.reflect.*;
import java.util.*;
import org.apache.juneau.*;
+import org.apache.juneau.annotation.*;
import org.apache.juneau.http.*;
import org.apache.juneau.internal.*;
import org.apache.juneau.reflect.*;
@@ -53,9 +54,40 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Add <js>"_type"</js> properties when needed.
*
* <p>
- * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
+ * When enabled, <js>"_type"</js> properties will be added to beans if their type cannot be inferred
* through reflection.
*
+ * <p>
+ * This is used to recreate the correct objects during parsing if the object types cannot be inferred.
+ * <br>For example, when serializing a <c>Map<String,Object></c> field where the bean class cannot be determined from
+ * the type of the values.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that adds _type to nodes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .addBeanTypes()
+ * .build();
+ *
+ * <jc>// A map of objects we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * Map<String,Object> m = new HashMap<>();
+ * m.put(<js>"foo"</js>, <jk>new</jk> MyBean());
+ *
+ * <jc>// Will contain '_type' attribute.</jc>
+ * String json = s.serialize(m);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes}
* </ul>
@@ -74,7 +106,39 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Add <js>"_type"</js> properties when needed.
*
* <p>
- * Shortcut for calling <code>addBeanTypes(<jk>true</jk>)</code>.
+ * When enabled, <js>"_type"</js> properties will be added to beans if their type cannot be inferred
+ * through reflection.
+ *
+ * <p>
+ * This is used to recreate the correct objects during parsing if the object types cannot be inferred.
+ * <br>For example, when serializing a <c>Map<String,Object></c> field where the bean class cannot be determined from
+ * the type of the values.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that adds _type to nodes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .addBeanTypes()
+ * .build();
+ *
+ * <jc>// A map of objects we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * Map<String,Object> m = new HashMap<>();
+ * m.put(<js>"foo"</js>, <jk>new</jk> MyBean());
+ *
+ * <jc>// Will contain '_type' attribute.</jc>
+ * String json = s.serialize(m);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes}
@@ -91,9 +155,39 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Add type attribute to root nodes.
*
* <p>
+ * When enabled, <js>"_type"</js> properties will be added to top-level beans.
+ *
+ * <p>
* When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
* type information that might normally be included to determine the data type will not be serialized.
*
+ * <p>
+ * For example, when serializing a top-level POJO with a {@link Bean#typeName() @Bean(typeName)} value, a
+ * <js>'_type'</js> attribute will only be added when this setting is enabled.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that adds _type to root node.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .addRootType()
+ * .build();
+ *
+ * <jc>// The bean we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * <jc>// Will contain '_type' attribute.</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_addRootType}
* </ul>
@@ -112,7 +206,38 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Add type attribute to root nodes.
*
* <p>
- * Shortcut for calling <code>addRootType(<jk>true</jk>)</code>.
+ * When enabled, <js>"_type"</js> properties will be added to top-level beans.
+ *
+ * <p>
+ * When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
+ * type information that might normally be included to determine the data type will not be serialized.
+ *
+ * <p>
+ * For example, when serializing a top-level POJO with a {@link Bean#typeName() @Bean(typeName)} value, a
+ * <js>'_type'</js> attribute will only be added when this setting is enabled.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that adds _type to root node.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .addRootType(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// The bean we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * <jc>// Will contain '_type' attribute.</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_addRootType}
@@ -129,7 +254,28 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Don't trim null bean property values.
*
* <p>
- * If <jk>true</jk>, null bean values will be serialized to the output.
+ * When enabled, null bean values will be serialized to the output.
+ *
+ * <ul class='notes'>
+ * <li>Not enabling this setting will cause <c>Map</c>s with <jk>null</jk> values to be lost during parsing.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that serializes null properties.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .keepNullProperties(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Our bean to serialize.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
+ * }
+ *
+ * <jc>// Will contain "{foo:null}".</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_keepNullProperties}
@@ -151,6 +297,27 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* <p>
* When enabled, null bean values will be serialized to the output.
*
+ * <ul class='notes'>
+ * <li>Not enabling this setting will cause <c>Map</c>s with <jk>null</jk> values to be lost during parsing.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that serializes null properties.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .keepNullProperties()
+ * .build();
+ *
+ * <jc>// Our bean to serialize.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
+ * }
+ *
+ * <jc>// Will contain "{foo:null}".</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_keepNullProperties}
* </ul>
@@ -168,6 +335,42 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* <p>
* Class used to listen for errors and warnings that occur during serialization.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Define our serializer listener.</jc>
+ * <jc>// Simply captures all errors.</jc>
+ * <jk>public class</jk> MySerializerListener <jk>extends</jk> SerializerListener {
+ *
+ * <jc>// A simple property to store our events.</jc>
+ * <jk>public</jk> List<String> <jf>events</jf> = <jk>new</jk> LinkedList<>();
+ *
+ * <ja>@Override</ja>
+ * <jk>public</jk> <T> <jk>void</jk> onError(SerializerSession session, Throwable t, String msg) {
+ * <jf>events</jf>.add(session.getLastLocation() + <js>","</js> + msg + <js>","</js> + t);
+ * }
+ * }
+ *
+ * <jc>// Create a serializer using our listener.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .listener(MySerializerListener.<jk>class</jk>)
+ * .build();
+ *
+ * <jc>// Create a session object.</jc>
+ * <jc>// Needed because listeners are created per-session.</jc>
+ * <jk>try</jk> (WriterSerializerSession ss = s.createSession()) {
+ *
+ * <jc>// Serialize a bean.</jc>
+ * String json = ss.serialize(<jk>new</jk> MyBean());
+ *
+ * <jc>// Get the listener.</jc>
+ * MySerializerListener l = ss.getListener(MySerializerListener.<jk>class</jk>);
+ *
+ * <jc>// Dump the results to the console.</jc>
+ * SimpleJsonSerializer.<jsf>DEFAULT</jsf>.println(l.<jf>events</jf>);
+ * }
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_listener}
* </ul>
@@ -185,7 +388,25 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Sort arrays and collections alphabetically.
*
* <p>
- * Copies and sorts the contents of arrays and collections before serializing them.
+ * When enabled, copies and sorts the contents of arrays and collections before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty since it requires copying the existing collection.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that sorts arrays and collections before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sortCollections(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// An unsorted array</jc>
+ * String[] array = {<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>}
+ *
+ * <jc>// Produces ["bar","baz","foo"]</jc>
+ * String json = s.serialize(array);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortCollections}
@@ -205,7 +426,25 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Sort arrays and collections alphabetically.
*
* <p>
- * Shortcut for calling <code>sortCollections(<jk>true</jk>)</code>.
+ * When enabled, copies and sorts the contents of arrays and collections before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty since it requires copying the existing collection.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that sorts arrays and collections before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sortCollections()
+ * .build();
+ *
+ * <jc>// An unsorted array</jc>
+ * String[] array = {<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>}
+ *
+ * <jc>// Produces ["bar","baz","foo"]</jc>
+ * String json = s.serialize(array);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortCollections}
@@ -222,7 +461,25 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Sort maps alphabetically.
*
* <p>
- * Copies and sorts the contents of maps before serializing them.
+ * When enabled, copies and sorts the contents of maps by their keys before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that sorts maps before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sortMaps(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// An unsorted map.</jc>
+ * OMap m = OMap.<jsm>of</jsm>(<js>"foo"</js>,1,<js>"bar"</js>,2,<js>"baz"</js>,3);
+ *
+ * <jc>// Produces {"bar":2,"baz":3,"foo":1}</jc>
+ * String json = s.serialize(map);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortMaps}
@@ -242,7 +499,25 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Sort maps alphabetically.
*
* <p>
- * Shortcut for calling <code>sortMaps(<jk>true</jk>)</code>.
+ * When enabled, copies and sorts the contents of maps by their keys before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that sorts maps before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sortMaps()
+ * .build();
+ *
+ * <jc>// An unsorted map.</jc>
+ * OMap m = OMap.<jsm>of</jsm>(<js>"foo"</js>,1,<js>"bar"</js>,2,<js>"baz"</js>,3);
+ *
+ * <jc>// Produces {"bar":2,"baz":3,"foo":1}</jc>
+ * String json = s.serialize(map);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortMaps}
@@ -259,7 +534,33 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim empty lists and arrays.
*
* <p>
- * If <jk>true</jk>, empty list values will not be serialized to the output.
+ * When enabled, empty lists and arrays will not be serialized.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Map entries with empty list values will be lost.
+ * <li>
+ * Bean properties with empty list values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that skips empty arrays and collections.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyCollections(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty array.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String[] <jf>foo</jf> = {};
+ * }
+ *
+ * <jc>// Produces {}</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyCollections}
@@ -279,7 +580,33 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim empty lists and arrays.
*
* <p>
- * Shortcut for calling <code>trimEmptyCollections(<jk>true</jk>)</code>.
+ * When enabled, empty lists and arrays will not be serialized.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Map entries with empty list values will be lost.
+ * <li>
+ * Bean properties with empty list values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that skips empty arrays and collections.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyCollections()
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty array.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String[] <jf>foo</jf> = {};
+ * }
+ *
+ * <jc>// Produces {}</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyCollections}
@@ -296,7 +623,31 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim empty maps.
*
* <p>
- * If <jk>true</jk>, empty map values will not be serialized to the output.
+ * When enabled, empty map values will not be serialized to the output.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Bean properties with empty map values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that skips empty maps.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyMaps(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty map.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> OMap <jf>foo</jf> = OMap.<jsm>of</jsm>();
+ * }
+ *
+ * <jc>// Produces {}</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyMaps}
@@ -316,7 +667,31 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim empty maps.
*
* <p>
- * Shortcut for calling <code>trimEmptyMaps(<jk>true</jk>)</code>.
+ * When enabled, empty map values will not be serialized to the output.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Bean properties with empty map values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that skips empty maps.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyMaps()
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty map.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> OMap <jf>foo</jf> = OMap.<jsm>of</jsm>();
+ * }
+ *
+ * <jc>// Produces {}</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyMaps}
@@ -333,7 +708,7 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim null bean property values.
*
* <p>
- * If <jk>true</jk>, null bean values will not be serialized to the output.
+ * When enabled, null bean values will not be serialized to the output.
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimNullProperties}
@@ -355,7 +730,7 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim null bean property values.
*
* <p>
- * If <jk>true</jk>, null bean values will not be serialized to the output.
+ * When enabled, null bean values will not be serialized to the output.
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimNullProperties}
@@ -374,7 +749,23 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim strings.
*
* <p>
- * If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that trims strings before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimStrings(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A map with space-padded keys/values</jc>
+ * Map<String,String> map = <jk>new</jk> HashMap<>();
+ * m.put(<js>" foo "</js>, <js>" bar "</js>);
+ *
+ * <jc>// Produces "{foo:'bar'}"</jc>
+ * String json = s.toString(map);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimStrings}
@@ -394,7 +785,23 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: Trim strings.
*
* <p>
- * Shortcut for calling <code>trimStrings(<jk>true</jk>)</code>.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that trims strings before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimStrings()
+ * .build();
+ *
+ * <jc>// A map with space-padded keys/values</jc>
+ * Map<String,String> map = <jk>new</jk> HashMap<>();
+ * m.put(<js>" foo "</js>, <js>" bar "</js>);
+ *
+ * <jc>// Produces "{foo:'bar'}"</jc>
+ * String json = s.toString(map);
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimStrings}
@@ -413,41 +820,42 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* <p>
* Bean used for resolution of URIs to absolute or root-relative form.
*
- * <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_uriContext}
- * </ul>
- *
- * @param value The new value for this property.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public SerializerBuilder uriContext(UriContext value) {
- return set(SERIALIZER_uriContext, value);
- }
-
- /**
- * Configuration property: URI context bean.
- *
- * <p>
- * Same as {@link #uriContext(UriContext)} but allows you to pass in a JSON string.
- *
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
+ * <jc>// Our URI contextual information.</jc>
+ * String authority = <js>"http://localhost:10000"</js>;
+ * String contextRoot = <js>"/myContext"</js>;
+ * String servletPath = <js>"/myServlet"</js>;
+ * String pathInfo = <js>"/foo"</js>;
+ *
+ * <jc>// Create a UriContext object.</jc>
+ * UriContext uriContext = <jk>new</jk> UriContext(authority, contextRoot, servletPath, pathInfo);
+ *
+ * <jc>// Associate it with our serializer.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
- * .uriContext(<js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>)
+ * .uriContext(uriContext)
+ * .uriRelativity(<jsf>RESOURCE</jsf>) <jc>// Assume relative paths are relative to servlet.</jc>
+ * .uriResolution(<jsf>ABSOLUTE</jsf>) <jc>// Serialize URLs as absolute paths.</jc>
* .build();
+ *
+ * <jc>// A relative URL</jc>
+ * URL url = <jk>new</jk> URL(<js>"bar"</js>);
+ *
+ * <jc>// Produces "http://localhost:10000/myContext/myServlet/foo/bar"</jc>
+ * String json = s.toString(url);
* </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_uriContext}
+ * <li class='link'>{@doc juneau-marshall.URIs}
* </ul>
*
* @param value The new value for this property.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public SerializerBuilder uriContext(String value) {
+ public SerializerBuilder uriContext(UriContext value) {
return set(SERIALIZER_uriContext, value);
}
@@ -455,38 +863,28 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: URI relativity.
*
* <p>
- * Defines what relative URIs are relative to when serializing URI/URL objects.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_uriRelativity}
+ * Defines what relative URIs are relative to when serializing any of the following:
+ * <ul>
+ * <li>{@link java.net.URI}
+ * <li>{@link java.net.URL}
+ * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
*
- * @param value
- * The new value for this property.
- * <br>The default is {@link UriRelativity#RESOURCE}
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public SerializerBuilder uriRelativity(UriRelativity value) {
- return set(SERIALIZER_uriRelativity, value);
- }
-
- /**
- * Configuration property: URI relativity.
- *
* <p>
- * Same as {@link #uriRelativity(UriRelativity)} but allows you to pass in a string.
+ * Possible values are:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link org.apache.juneau.UriRelativity#RESOURCE}
+ * - Relative URIs should be considered relative to the servlet URI.
+ * <li class='jf'>{@link org.apache.juneau.UriRelativity#PATH_INFO}
+ * - Relative URIs should be considered relative to the request URI.
+ * </ul>
*
- * <h5 class='section'>Example:</h5>
- * <p class='bcode w800'>
- * WriterSerializer s = JsonSerializer
- * .<jsm>create</jsm>()
- * .uriRelativity(<js>"PATH_INFO"</js>)
- * .build();
- * </p>
+ * <p>
+ * See {@link #uriContext(UriContext)} for examples.
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_uriRelativity}
+ * <li class='link'>{@doc juneau-marshall.URIs}
* </ul>
*
* @param value
@@ -495,7 +893,7 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public SerializerBuilder uriRelativity(String value) {
+ public SerializerBuilder uriRelativity(UriRelativity value) {
return set(SERIALIZER_uriRelativity, value);
}
@@ -503,38 +901,30 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* Configuration property: URI resolution.
*
* <p>
- * Defines the resolution level for URIs when serializing URI/URL objects.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_uriResolution}
+ * Defines the resolution level for URIs when serializing any of the following:
+ * <ul>
+ * <li>{@link java.net.URI}
+ * <li>{@link java.net.URL}
+ * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
*
- * @param value
- * The new value for this property.
- * <br>The default is {@link UriResolution#NONE}
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public SerializerBuilder uriResolution(UriResolution value) {
- return set(SERIALIZER_uriResolution, value);
- }
-
- /**
- * Configuration property: URI resolution.
- *
* <p>
- * Same as {@link #uriResolution(UriResolution)} but allows you to pass in a string.
+ * Possible values are:
+ * <ul>
+ * <li class='jf'>{@link UriResolution#ABSOLUTE}
+ * - Resolve to an absolute URL (e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>).
+ * <li class='jf'>{@link UriResolution#ROOT_RELATIVE}
+ * - Resolve to a root-relative URL (e.g. <js>"/context-root/servlet-path/path-info"</js>).
+ * <li class='jf'>{@link UriResolution#NONE}
+ * - Don't do any URL resolution.
+ * </ul>
*
- * <h5 class='section'>Example:</h5>
- * <p class='bcode w800'>
- * WriterSerializer s = JsonSerializer
- * .<jsm>create</jsm>()
- * .uriResolution(<js>"ROOT_RELATIVE"</js>)
- * .build();
- * </p>
+ * <p>
+ * See {@link #uriContext(UriContext)} for examples.
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_uriResolution}
+ * <li class='link'>{@doc juneau-marshall.URIs}
* </ul>
*
* @param value
@@ -543,7 +933,7 @@ public class SerializerBuilder extends BeanTraverseBuilder {
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public SerializerBuilder uriResolution(String value) {
+ public SerializerBuilder uriResolution(UriResolution value) {
return set(SERIALIZER_uriResolution, value);
}
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
index abe5334..c7ce897 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
@@ -55,6 +55,7 @@ public abstract class WriterSerializer extends Serializer {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* The character set to use for writing <c>Files</c> to the file system.
*
@@ -67,13 +68,13 @@ public abstract class WriterSerializer extends Serializer {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a serializer that writes UTF-8 files.</jc>
- * WriterSerializer s = JsonSerializer.
+ * WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .fileCharset(Charset.<jsm>forName</jsm>(<js>"UTF-8"</js>))
* .build();
*
* <jc>// Same, but use property.</jc>
- * WriterSerializer s = JsonSerializer.
+ * WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .set(<jsf>WSERIALIZER_fileCharset</jsf>, <js>"UTF-8"</js>)
* .build();
@@ -107,24 +108,27 @@ public abstract class WriterSerializer extends Serializer {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Specifies the maximum indentation level in the serialized document.
*
- * <p>
- * This setting does not apply to the RDF serializers.
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a serializer that indents a maximum of 20 tabs.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
+ * .ws() <jc>// Enable whitespace</jc>
* .maxIndent(20)
* .build();
*
* <jc>// Same, but use property.</jc>
* WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
- * .set(<jsf>SERIALIZER_maxIndent</jsf>, 20)
+ * .set(<jsf>WSERIALIZER_maxIndent</jsf>, 20)
* .build();
* </p>
*/
@@ -154,11 +158,13 @@ public abstract class WriterSerializer extends Serializer {
* </ul>
*
* <h5 class='section'>Description:</h5>
- * <p>
- * This is the character used for quoting attributes and values.
*
* <p>
- * This setting does not apply to the RDF serializers.
+ * Specifies the character to use for quoting attributes and values.
+ *
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
@@ -173,6 +179,14 @@ public abstract class WriterSerializer extends Serializer {
* .<jsm>create</jsm>()
* .set(<jsf>WSERIALIZER_quoteChar</jsf>, <js>'\''</js>)
* .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces {'foo':'bar'}</jc>
+ * String json = s.toString(<jk>new</jk> MyBean());
* </p>
*/
public static final String WSERIALIZER_quoteChar = PREFIX + ".quoteChar.s";
@@ -200,6 +214,7 @@ public abstract class WriterSerializer extends Serializer {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* The character set to use when writing to <c>OutputStreams</c>.
*
@@ -209,13 +224,13 @@ public abstract class WriterSerializer extends Serializer {
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a serializer that writes UTF-8 files.</jc>
- * WriterSerializer s = JsonSerializer.
+ * WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .streamCharset(Charset.<jsm>forName</jsm>(<js>"UTF-8"</js>))
* .build();
*
* <jc>// Same, but use property.</jc>
- * WriterSerializer s = JsonSerializer.
+ * WriterSerializer s = JsonSerializer
* .<jsm>create</jsm>()
* .set(<jsf>WSERIALIZER_streamCharset</jsf>, <js>"UTF-8"</js>)
* .build();
@@ -251,8 +266,9 @@ public abstract class WriterSerializer extends Serializer {
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
- * If <jk>true</jk>, whitespace is added to the output to improve readability.
+ * When enabled, whitespace is added to the output to improve readability.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
@@ -268,7 +284,12 @@ public abstract class WriterSerializer extends Serializer {
* .set(<jsf>WSERIALIZER_useWhitespace</jsf>, <jk>true</jk>)
* .build();
*
- * <jc>// Produces "\{\n\t'foo': 'bar'\n\}\n"</jc>
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces "\{\n\t"foo": "bar"\n\}\n"</jc>
* String json = s.serialize(<jk>new</jk> MyBean());
* </p>
*/
@@ -451,7 +472,7 @@ public abstract class WriterSerializer extends Serializer {
*
* @see #WSERIALIZER_useWhitespace
* @return
- * If <jk>true</jk>, whitespace is added to the output to improve readability.
+ * When enabled, whitespace is added to the output to improve readability.
*/
protected final boolean isUseWhitespace() {
return useWhitespace;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializerBuilder.java
index 3dd2e92..212353d 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/WriterSerializerBuilder.java
@@ -54,11 +54,26 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: File charset.
*
* <p>
- * The character set to use for writing Files to the file system.
+ * The character set to use for writing <c>Files</c> to the file system.
*
* <p>
* Used when passing in files to {@link Serializer#serialize(Object, Object)}.
*
+ * <p>
+ * <js>"DEFAULT"</js> can be used to indicate the JVM default file system charset.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that writes UTF-8 files.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .fileCharset(Charset.<jsm>forName</jsm>(<js>"UTF-8"</js>))
+ * .build();
+ *
+ * <jc>// Use it to read a UTF-8 encoded file.</jc>
+ * s.serialize(<jk>new</jk> File(<js>"MyBean.txt"</js>), myBean);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_fileCharset}
* </ul>
@@ -79,6 +94,20 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* <p>
* Specifies the maximum indentation level in the serialized document.
*
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that indents a maximum of 20 tabs.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .ws() <jc>// Enable whitespace</jc>
+ * .maxIndent(20)
+ * .build();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_maxIndent}
* </ul>
@@ -97,7 +126,28 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: Quote character.
*
* <p>
- * This is the character used for quoting attributes and values.
+ * Specifies the character to use for quoting attributes and values.
+ *
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that uses single quotes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .quoteChar(<js>'\''</js>)
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces {'foo':'bar'}</jc>
+ * String json = s.toString(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar}
@@ -117,7 +167,28 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: Quote character.
*
* <p>
- * Shortcut for calling <code>quoteChar(<js>'\''</js>)</code>.
+ * Specifies to use single quotes for quoting attributes and values.
+ *
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that uses single quotes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sq()
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces {'foo':'bar'}</jc>
+ * String json = s.toString(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar}
@@ -134,11 +205,23 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: Output stream charset.
*
* <p>
- * The character set to use when writing to OutputStreams.
+ * The character set to use when writing to <c>OutputStreams</c>.
*
* <p>
* Used when passing in output streams and byte arrays to {@link WriterSerializer#serialize(Object, Object)}.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that writes UTF-8 files.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .streamCharset(Charset.<jsm>forName</jsm>(<js>"UTF-8"</js>))
+ * .build();
+ *
+ * <jc>// Use it to write to a UTF-8 encoded output stream.</jc>
+ * s.serializer(<jk>new</jk> FileOutputStreamStream(<js>"MyBean.txt"</js>), myBean);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_streamCharset}
* </ul>
@@ -157,7 +240,24 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: Use whitespace.
*
* <p>
- * If <jk>true</jk>, newlines and indentation and spaces are added to the output to improve readability.
+ * When enabled, whitespace is added to the output to improve readability.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer with whitespace enabled.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .useWhitespace(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces "\{\n\t"foo": "bar"\n\}\n"</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
@@ -177,7 +277,24 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: Use whitespace.
*
* <p>
- * Shortcut for calling <code>useWhitespace(<jk>true</jk>)</code>.
+ * When enabled, whitespace is added to the output to improve readability.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer with whitespace enabled.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .useWhitespace()
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces "\{\n\t"foo": "bar"\n\}\n"</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
@@ -193,7 +310,24 @@ public class WriterSerializerBuilder extends SerializerBuilder {
* Configuration property: Use whitespace.
*
* <p>
- * Shortcut for calling <code>useWhitespace(<jk>true</jk>)</code>.
+ * When enabled, whitespace is added to the output to improve readability.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer with whitespace enabled.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .ws()
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Produces "\{\n\t"foo": "bar"\n\}\n"</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
@@ -1037,36 +1171,18 @@ public class WriterSerializerBuilder extends SerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public WriterSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public WriterSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public WriterSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public WriterSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public WriterSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public WriterSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
index 5d7c20a..fb32a15 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
@@ -904,36 +904,18 @@ public class SoapXmlSerializerBuilder extends XmlSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public SoapXmlSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public SoapXmlSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public SoapXmlSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public SoapXmlSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public SoapXmlSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public SoapXmlSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
index da8afda..56f536f 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializer.java
@@ -240,25 +240,26 @@ public class UonSerializer extends WriterSerializer implements HttpPartSerialize
* </ul>
*
* <h5 class='section'>Description:</h5>
+ *
* <p>
* Specifies the format to use for URL GET parameter keys and values.
*
* <p>
* Possible values:
* <ul class='javatree'>
- * <li class='jf'>{@link ParamFormat#UON} - Use UON notation for parameters.
+ * <li class='jf'>{@link ParamFormat#UON} (default) - Use UON notation for parameters.
* <li class='jf'>{@link ParamFormat#PLAINTEXT} - Use plain text for parameters.
* </ul>
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
* <jc>// Create a normal UON serializer.</jc>
- * UonSerializer s1 = UonSerializer.
+ * UonSerializer s1 = UonSerializer
* .<jsm>create</jsm>()
* .build();
*
* <jc>// Create a plain-text UON serializer.</jc>
- * UonSerializer s2 = UonSerializer.
+ * UonSerializer s2 = UonSerializer
* .<jsm>create</jsm>()
* .paramFormat(<jsf>PLAIN_TEXT</jsf>)
* .build();
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializerBuilder.java
index 7658a1d..792c5d1 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/uon/UonSerializerBuilder.java
@@ -99,6 +99,38 @@ public class UonSerializerBuilder extends WriterSerializerBuilder {
* <p>
* Specifies the format to use for URL GET parameter keys and values.
*
+ * <p>
+ * Possible values:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link ParamFormat#UON} (default) - Use UON notation for parameters.
+ * <li class='jf'>{@link ParamFormat#PLAINTEXT} - Use plain text for parameters.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a normal UON serializer.</jc>
+ * UonSerializer s1 = UonSerializer
+ * .<jsm>create</jsm>()
+ * .build();
+ *
+ * <jc>// Create a plain-text UON serializer.</jc>
+ * UonSerializer s2 = UonSerializer
+ * .<jsm>create</jsm>()
+ * .paramFormat(<jsf>PLAIN_TEXT</jsf>)
+ * .build();
+ *
+ * OMap m = OMap.<jsm>of</jsm>(
+ * <js>"foo"</js>, <js>"bar"</js>,
+ * <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
+ * );
+ *
+ * <jc>// Produces: "(foo=bar,baz=@(qux,'true','123'))"</jc>
+ * String uon1 = s1.serialize(m)
+ *
+ * <jc>// Produces: "foo=bar,baz=qux,true,123"</jc>
+ * String uon2 = s2.serialize(m)
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link UonSerializer#UON_paramFormat}
* </ul>
@@ -117,27 +149,24 @@ public class UonSerializerBuilder extends WriterSerializerBuilder {
* Configuration property: Format to use for query/form-data/header values.
*
* <p>
- * Specifies the format to use for URL GET parameter keys and values.
+ * Specifies plain-text for the format to use for URL GET parameter keys and values.
*
- * <ul class='seealso'>
- * <li class='jf'>{@link UonSerializer#UON_paramFormat}
- * </ul>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a plain-text UON serializer.</jc>
+ * UonSerializer s = UonSerializer
+ * .<jsm>create</jsm>()
+ * .paramFormatPlain()
+ * .build();
*
- * @param value
- * The new value for this property.
- * <br>The default value is {@link ParamFormat#UON}.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public UonSerializerBuilder paramFormat(String value) {
- return set(UON_paramFormat, ParamFormat.valueOf(value));
- }
-
- /**
- * Configuration property: Format to use for query/form-data/header values.
+ * OMap m = OMap.<jsm>of</jsm>(
+ * <js>"foo"</js>, <js>"bar"</js>,
+ * <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
+ * );
*
- * <p>
- * Shortcut for calling <code>paramFormat(<jsf>PLAINTEXT</jsf>)</code>.
+ * <jc>// Produces: "foo=bar,baz=qux,true,123"</jc>
+ * String uon = s.serialize(m)
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link UonSerializer#UON_paramFormat}
@@ -981,36 +1010,18 @@ public class UonSerializerBuilder extends WriterSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public UonSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public UonSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public UonSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public UonSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public UonSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public UonSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
index 6a1226a..d201964 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/urlencoding/UrlEncodingSerializerBuilder.java
@@ -925,36 +925,18 @@ public class UrlEncodingSerializerBuilder extends UonSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public UrlEncodingSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public UrlEncodingSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public UrlEncodingSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public UrlEncodingSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public UrlEncodingSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public UrlEncodingSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
@@ -1021,12 +1003,6 @@ public class UrlEncodingSerializerBuilder extends UonSerializerBuilder {
}
@Override /* GENERATED - UonSerializerBuilder */
- public UrlEncodingSerializerBuilder paramFormat(String value) {
- super.paramFormat(value);
- return this;
- }
-
- @Override /* GENERATED - UonSerializerBuilder */
public UrlEncodingSerializerBuilder paramFormat(ParamFormat value) {
super.paramFormat(value);
return this;
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
index 18d8db4..9519808 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
@@ -1115,36 +1115,18 @@ public class XmlSerializerBuilder extends WriterSerializerBuilder {
}
@Override /* GENERATED - SerializerBuilder */
- public XmlSerializerBuilder uriContext(String value) {
- super.uriContext(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public XmlSerializerBuilder uriContext(UriContext value) {
super.uriContext(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public XmlSerializerBuilder uriRelativity(String value) {
- super.uriRelativity(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public XmlSerializerBuilder uriRelativity(UriRelativity value) {
super.uriRelativity(value);
return this;
}
@Override /* GENERATED - SerializerBuilder */
- public XmlSerializerBuilder uriResolution(String value) {
- super.uriResolution(value);
- return this;
- }
-
- @Override /* GENERATED - SerializerBuilder */
public XmlSerializerBuilder uriResolution(UriResolution value) {
super.uriResolution(value);
return this;
diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html
index f7a61a3..50687b3 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -30102,6 +30102,36 @@
</tr>
<tr>
<td></td>
+ <td>{@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logRequests RESTCLIENT_logRequests}</td>
+ <td>Log requests.</td>
+ <td style='max-width:250px;overflow:hidden'><ul><li>{@link org.apache.juneau.DetailLevel}</ul></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>{@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logRequestsLevel RESTCLIENT_logRequestsLevel}</td>
+ <td>Log requests log level.</td>
+ <td style='max-width:250px;overflow:hidden'><ul><li>{@link java.util.logging.Level}</ul></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>{@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logRequestsPredicate RESTCLIENT_logRequestsPredicate}</td>
+ <td>Log requests predicate.</td>
+ <td style='max-width:250px;overflow:hidden'><ul><li>{@link java.util.function.BiPredicate}<{@link org.apache.juneau.rest.client2.RestRequest},{@link org.apache.juneau.rest.client2.RestResponse}></ul></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>{@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logToConsole RESTCLIENT_logToConsole}</td>
+ <td>Log to console.</td>
+ <td style='max-width:250px;overflow:hidden'><ul><li><jk>boolean</jk></ul></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>{@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logger RESTCLIENT_logger}</td>
+ <td>Logger.</td>
+ <td style='max-width:250px;overflow:hidden'><ul><li>{@link java.util.logging.Logger}</ul></td>
+ </tr>
+ <tr>
+ <td></td>
<td>{@link org.apache.juneau.rest.client.RestClient#RESTCLIENT_parser RESTCLIENT_parser}</td>
<td>Parser.</td>
<td style='max-width:250px;overflow:hidden'><ul><li><c>Class<{@link org.apache.juneau.parser.Parser}></c><li>{@link org.apache.juneau.parser.Parser}</ul></td>
diff --git a/juneau-rest/juneau-rest-client-utest/src/test/java/org/apache/juneau/rest/client2/RestClientTest.java b/juneau-rest/juneau-rest-client-utest/src/test/java/org/apache/juneau/rest/client2/RestClientTest.java
index f05b49d..27a5735 100644
--- a/juneau-rest/juneau-rest-client-utest/src/test/java/org/apache/juneau/rest/client2/RestClientTest.java
+++ b/juneau-rest/juneau-rest-client-utest/src/test/java/org/apache/juneau/rest/client2/RestClientTest.java
@@ -2238,26 +2238,6 @@ public class RestClientTest {
}
}
- public static class L10a {
- public int getFoo() {
- throw new RuntimeException("Foo!");
- }
- }
-
- @Test
- public void l10_serializer_serializerListener() throws Exception {
- MockRestClient
- .create(A.class)
- .simpleJson()
- .serializerListener(L10.class)
- .ws()
- .build()
- .post("/echoBody", new L10a())
- .run();
- assertTrue(L10.T.getLocalizedMessage().contains("Exception occurred while getting property 'foo'"));
- assertTrue(L10.MSG.contains("Exception occurred while getting property 'foo'"));
- }
-
public static class L11 {
public Bean f;
@@ -2648,50 +2628,6 @@ public class RestClientTest {
// Parser properties
//-----------------------------------------------------------------------------------------------------------------
- @Test
- public void m01_parser_autoCloseStreams() throws Exception {
- String x = "foo";
- RestClient rc = null;
-
- rc = MockRestClient
- .create(A.class)
- .simpleJson()
- .autoCloseStreams()
- .build();
-
- assertTrue(rc.parsers.getParser("application/json").toMap().getMap("Parser").getBoolean("autoCloseStreams"));
-
- rc
- .post("/echoBody", x)
- .run()
- .getBody().assertValue("'foo'");
-
- rc = MockRestClient
- .create(A.class)
- .simpleJson()
- .autoCloseStreams(true)
- .build();
-
- assertTrue(rc.parsers.getParser("application/json").toMap().getMap("Parser").getBoolean("autoCloseStreams"));
-
- rc
- .post("/echoBody", x)
- .run()
- .getBody().assertValue("'foo'");
-
- rc = MockRestClient
- .create(A.class)
- .simpleJson()
- .autoCloseStreams(false)
- .build();
-
- assertFalse(rc.parsers.getParser("application/json").toMap().getMap("Parser").getBoolean("autoCloseStreams", false));
-
- rc
- .post("/echoBody", x)
- .run()
- .getBody().assertValue("'foo'");
- }
@Test
public void m03_parser_debugOutputLines() throws Exception {
@@ -2717,30 +2653,6 @@ public class RestClientTest {
}
}
- public static class M4 {
- public void setF(String f) {
- throw new RuntimeException("foo");
- }
- }
-
- @Test
- public void m04_parser_parserListener() throws Exception {
- try {
- MockRestClient
- .create(A.class)
- .parser(JsonParser.class)
- .parserListener(M4L.class)
- .build()
- .post("/echoBody", "{f:'1'}")
- .run()
- .getBody().as(M4.class);
- fail("Exception expected");
- } catch (Exception e) {
- assertTrue(M4L.T instanceof RuntimeException);
- assertTrue(M4L.MSG.contains("Error occurred trying to set property 'f'"));
- }
- }
-
public static class M5 {
public int f;
}
@@ -2822,80 +2734,6 @@ public class RestClientTest {
assertEquals(" 1 ", x.f);
}
- @Test
- public void m09_parser_unbufferedBoolean() throws Exception {
- RestClient rc = null;
-
- rc = MockRestClient
- .create(A.class)
- .simpleJson()
- .unbuffered()
- .build();
-
- assertTrue(rc.parsers.getParser("application/json").toMap().getMap("Parser").getBoolean("unbuffered"));
-
- M7 x = rc
- .post("/echoBody", new StringReader("{f:'1'}"))
- .run()
- .getBody().as(M7.class);
- assertEquals("1", x.f);
-
- rc = MockRestClient
- .create(A.class)
- .simpleJson()
- .unbuffered(true)
- .build();
-
- assertTrue(rc.parsers.getParser("application/json").toMap().getMap("Parser").getBoolean("unbuffered"));
-
- rc = MockRestClient
- .create(A.class)
- .simpleJson()
- .unbuffered(false)
- .build();
-
- assertFalse(rc.parsers.getParser("application/json").toMap().getMap("Parser").getBoolean("unbuffered", false));
- }
-
- @Test
- public void m11_parser_fileCharset() throws Exception {
- RestClient rc = null;
-
- rc = MockRestClient
- .create(A.class)
- .json()
- .fileCharset("UTF-8")
- .build();
-
- assertEquals("UTF-8", rc.parsers.getParser("application/json").toMap().getMap("ReaderParser").getString("fileCharset"));
- }
-
- @Test
- public void m12_parser_inputStreamCharset() throws Exception {
- RestClient rc = null;
-
- rc = MockRestClient
- .create(A.class)
- .json()
- .inputStreamCharset("UTF-8")
- .build();
-
- assertEquals("UTF-8", rc.parsers.getParser("application/json").toMap().getMap("ReaderParser").getString("streamCharset"));
- }
-
- @Test
- public void m13_parser_binaryInputFormat() throws Exception {
- RestClient rc = null;
-
- rc = MockRestClient
- .create(A.class)
- .msgPack()
- .binaryInputFormat(BinaryFormat.BASE64)
- .build();
-
- assertEquals("BASE64", rc.parsers.getParser("octal/msgpack").toMap().getMap("InputStreamParser").getString("binaryFormat"));
- }
-
//-----------------------------------------------------------------------------------------------------------------
// OpenApi properties
//-----------------------------------------------------------------------------------------------------------------
diff --git a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClient.java b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClient.java
index 50f57ac..93d6549 100644
--- a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClient.java
+++ b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClient.java
@@ -1396,13 +1396,13 @@ public class RestClient extends BeanContext implements HttpClient, Closeable {
*
* <p>
* <jsf>SIMPLE</jsf> detail produces a log message like the following:
- * <p class='bpcode w800'>
+ * <p class='bcode w800 console'>
* POST http://localhost:10000/testUrl, HTTP/1.1 200 OK
* </p>
*
* <p>
* <jsf>FULL</jsf> detail produces a log message like the following:
- * <p class='bpcode w800 console'>
+ * <p class='bcode w800 console'>
* === HTTP Call (outgoing) =======================================================
* === REQUEST ===
* POST http://localhost:10000/testUrl
diff --git a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClientBuilder.java b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClientBuilder.java
index 47edce9..8b6bf75 100644
--- a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClientBuilder.java
+++ b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client2/RestClientBuilder.java
@@ -13,7 +13,6 @@
package org.apache.juneau.rest.client2;
import static org.apache.juneau.parser.InputStreamParser.*;
-import static org.apache.juneau.parser.ReaderParser.*;
import static org.apache.juneau.rest.client2.RestClient.*;
import static org.apache.juneau.BeanTraverseContext.*;
import static org.apache.juneau.httppart.HttpPartType.*;
@@ -51,6 +50,7 @@ import org.apache.http.impl.client.*;
import org.apache.http.impl.conn.*;
import org.apache.http.protocol.*;
import org.apache.juneau.*;
+import org.apache.juneau.annotation.*;
import org.apache.juneau.collections.*;
import org.apache.juneau.html.*;
import org.apache.juneau.http.*;
@@ -61,6 +61,7 @@ import org.apache.juneau.marshall.*;
import org.apache.juneau.msgpack.*;
import org.apache.juneau.oapi.*;
import org.apache.juneau.parser.*;
+import org.apache.juneau.parser.ParseException;
import org.apache.juneau.plaintext.*;
import org.apache.juneau.reflect.*;
import org.apache.juneau.rest.client2.ext.*;
@@ -842,7 +843,7 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <p>
* If not specified, uses the following logger:
- * <p class='bpcode w800'>
+ * <p class='bcode w800'>
* Logger.<jsm>getLogger</jsm>(RestClient.<jk>class</jk>.getName());
* </p>
*
@@ -932,13 +933,13 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <p>
* <jsf>SIMPLE</jsf> detail produces a log message like the following:
- * <p class='bpcode w800'>
+ * <p class='bcode w800 console'>
* POST http://localhost:10000/testUrl, HTTP/1.1 200 OK
* </p>
*
* <p>
* <jsf>FULL</jsf> detail produces a log message like the following:
- * <p class='bpcode w800 console'>
+ * <p class='bcode w800 console'>
* === HTTP Call (outgoing) =======================================================
* === REQUEST ===
* POST http://localhost:10000/testUrl
@@ -963,8 +964,8 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <p>
* By default, the message is logged to the default logger. It can be logged to a different logger via the
- * {@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logger} setting or logged to the console using the
- * {@link org.apache.juneau.rest.client2.RestClient#RESTCLIENT_logToConsole} setting.
+ * {@link #logger(Logger)} method or logged to the console using the
+ * {@link #logToConsole()} method.
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_logRequests}
@@ -1811,10 +1812,10 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * client
- * .get(<jsf>URL</jsf>)
+ * RestClient c = RestClient
+ * .<jsm>create</jsm>()
* .query(<js>"foo"</js>, <js>"bar"</js>)
- * .run();
+ * .build();
* </p>
*
* @param name The parameter name.
@@ -1836,10 +1837,10 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * client
- * .get(<jsf>URL</jsf>)
+ * RestClient c = RestClient
+ * .<jsm>create</jsm>()
* .query(<jk>new</jk> BasicNameValuePair(<js>"foo"</js>, <js>"bar"</js>))
- * .run();
+ * .build();
* </p>
*
* <p>
@@ -1888,10 +1889,10 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * client
- * .get(<jsf>URL</jsf>)
- * .query(<js>"key1"</js>,<js>"val1"</js>,<js>"key2"</js>,<js>"val2"</js>)
- * .run();
+ * RestClient c = RestClient
+ * .<jsm>create</jsm>()
+ * .queryPairs(<js>"key1"</js>,<js>"val1"</js>,<js>"key2"</js>,<js>"val2"</js>)
+ * .build();
* </p>
*
* @param pairs The query key/value pairs.
@@ -1994,10 +1995,10 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * client
- * .formPost(<jsf>URL</jsf>)
+ * RestClient c = RestClient
+ * .<jsm>create</jsm>()
* .formData(<js>"foo"</js>, <js>"bar"</js>)
- * .run();
+ * .build();
* </p>
*
* @param name The parameter name.
@@ -2019,10 +2020,10 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * client
- * .formPost(<jsf>URL</jsf>)
+ * RestClient c = RestClient
+ * .<jsm>create</jsm>()
* .formData(<jk>new</jk> BasicNameValuePair(<js>"foo"</js>, <js>"bar"</js>))
- * .run();
+ * .build();
* </p>
*
* <p>
@@ -2071,10 +2072,10 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * client
- * .formPost(<jsf>URL</jsf>)
- * .formData(<js>"key1"</js>,<js>"val1"</js>,<js>"key2"</js>,<js>"val2"</js>)
- * .run();
+ * RestClient c = RestClient
+ * .<jsm>create</jsm>()
+ * .formDataPairs(<js>"key1"</js>,<js>"val1"</js>,<js>"key2"</js>,<js>"val2"</js>)
+ * .build();
* </p>
*
* @param pairs The form-data key/value pairs.
@@ -2221,6 +2222,8 @@ public class RestClientBuilder extends BeanContextBuilder {
* This executor service is used to create {@link Future} objects on the following methods:
* <ul>
* <li class='jm'>{@link RestRequest#runFuture()}
+ * <li class='jm'>{@link RestRequest#completeFuture()}
+ * <li class='jm'>{@link RestResponseBody#asFuture(Class)} (and similar methods)
* </ul>
*
* <p>
@@ -2240,12 +2243,10 @@ public class RestClientBuilder extends BeanContextBuilder {
* <jc>// Do some other stuff</jc>
* <jk>try</jk> {
* String body = f.get().getBody().asString();
- * <jc>// Succeeded!</jc>
* } <jk>catch</jk> (RestCallException e) {
- * <jc>// Failed!</jc>
* }
* <jc>// Use it to asynchronously retrieve a response.</jc>
- * Future<MyBean> f
+ * client
* .get(<jsf>URL</jsf>)
* .run()
* .getBody().asFuture(MyBean.<jk>class</jk>);
@@ -2275,7 +2276,7 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Create a client with a customized client and don't close the client service.</jc>
+ * <jc>// Create a client with a customized client and don't close the http client on close.</jc>
* RestClient client = RestClient
* .<jsm>create</jsm>()
* .httpClient(myHttpClient)
@@ -2340,7 +2341,7 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Customized interceptor (note you can also extend from BasicRestCallInterceptor as well.</jc>
+ * <jc>// Customized interceptor (note you can also extend from BasicRestCallInterceptor as well.</jc>
* <jk>public class</jk> MyRestCallInterceptor <jk>implements</jk> RestCallInterceptor {
*
* <ja>@Override</ja> <jc>// RestCallInterceptor</jc>
@@ -2366,7 +2367,7 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <ja>@Override</ja> <jc>// RestCallInterceptor</jc>
* <jk>public void</jk> close(RestRequest req, RestResponse res) <jk>throws</jk> Exception {
- * <jc>// Intercept when the response body is consumed.
+ * <jc>// Intercept when the response body is consumed.</jc>
* }
* }
*
@@ -2402,10 +2403,6 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <h5 class='section'>Example:</h5>
* <p class='bcode w800'>
- * <jc>// Customized interceptor (note you can also extend from BasicRestCallInterceptor as well.</jc>
- * <jk>public class</jk> MyRestCallInterceptor <jk>implements</jk> RestCallInterceptor {
- * }
- *
* <jc>// Create a client with a customized interceptor.</jc>
* RestClient client = RestClient
* .<jsm>create</jsm>()
@@ -2425,7 +2422,7 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <ja>@Override</ja> <jc>// RestCallInterceptor</jc>
* <jk>public void</jk> connect(RestRequest req, RestResponse res) <jk>throws</jk> Exception {
- * <jc>// Intercept immediately after an HTTP response has been received.</jc>
+ * <jc>// Intercept immediately after an HTTP response has been received.</jc>
* }
*
* <ja>@Override</ja> <jc>// HttpResponseInterceptor</jc>
@@ -2435,7 +2432,7 @@ public class RestClientBuilder extends BeanContextBuilder {
*
* <ja>@Override</ja> <jc>// RestCallInterceptor</jc>
* <jk>public void</jk> close(RestRequest req, RestResponse res) <jk>throws</jk> Exception {
- * <jc>// Intercept when the response body is consumed.
+ * <jc>// Intercept when the response body is consumed.</jc>
* }
* }
* )
@@ -2477,6 +2474,7 @@ public class RestClientBuilder extends BeanContextBuilder {
* RestClient client = RestClient
* .<jsm>create</jsm>()
* .leakDetection()
+ * .logToConsole() <jc>// Also log the error message to System.err</jc>
* .build();
*
* client.closeQuietly(); <jc>// Customized HttpClient won't be closed.</jc>
@@ -2506,6 +2504,18 @@ public class RestClientBuilder extends BeanContextBuilder {
* <p>
* Automatically enabled with {@link RestClient#RESTCLIENT_debug}.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that logs a message if the client is not properly closed.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .leakDetection(<jk>true</jk>)
+ * .logToConsole() <jc>// Also log the error message to System.err</jc>
+ * .build();
+ *
+ * client.closeQuietly(); <jc>// Customized HttpClient won't be closed.</jc>
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_leakDetection}
* </ul>
@@ -2526,6 +2536,21 @@ public class RestClientBuilder extends BeanContextBuilder {
* Shortcut for specifying the {@link RestClient#RESTCLIENT_serializers} and {@link RestClient#RESTCLIENT_parsers}
* using the serializer and parser defined in a marshall.
*
+ * <ul class='notes'>
+ * <li>When using this method that takes in a pre-instantiated serializers and parsers, the serializer property setters (e.g. {@link #sortCollections()}),
+ * parser property setters (e.g. {@link #strict()}), bean context property setters (e.g. {@link #pojoSwaps(Class...)}),
+ * or generic property setters (e.g. {@link #set(String, Object)}) defined on this builder class have no effect.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses Simplified-JSON transport using an existing marshall.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .marshall(SimpleJson.<jsf>DEFAULT_READABLE</jsf>)
+ * .build();
+ * </p>
+ *
* @param value The values to add to this setting.
* @return This object (for method chaining).
*/
@@ -2543,15 +2568,29 @@ public class RestClientBuilder extends BeanContextBuilder {
* Shortcut for specifying the {@link RestClient#RESTCLIENT_serializers} and {@link RestClient#RESTCLIENT_parsers}
* using the serializer and parser defined in a marshall.
*
+ * <ul class='notes'>
+ * <li>When using this method that takes in a pre-instantiated serializers and parsers, the serializer property setters (e.g. {@link #sortCollections()}),
+ * parser property setters (e.g. {@link #strict()}), bean context property setters (e.g. {@link #pojoSwaps(Class...)}),
+ * or generic property setters (e.g. {@link #set(String, Object)}) defined on this builder class have no effect.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses JSON and XML transport using existing marshalls.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .marshall(Json.<jsf>DEFAULT_READABLE</jsf>, Xml.<jsf>DEFAULT_READABLE</jsf>)
+ * .build();
+ * </p>
+ *
* @param value The values to add to this setting.
* @return This object (for method chaining).
*/
@ConfigurationProperty
public RestClientBuilder marshalls(Marshall...value) {
- for (Marshall m : value) {
+ for (Marshall m : value)
if (m != null)
serializer(m.getSerializer()).parser(m.getParser());
- }
return this;
}
@@ -2559,7 +2598,25 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Parser.
*
* <p>
- * Shortcut for calling {@link #parsers(Class...)}.
+ * Associates the specified {@link Parser Parser} with the HTTP client.
+ *
+ * <p>
+ * The parser is used to parse the HTTP response body into a POJO.
+ *
+ * <ul class='notes'>
+ * <li>When using this method that takes in a class, the parser can be configured using any of the parser property setters (e.g. {@link #strict()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined on this builder class.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses JSON transport for response bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .parser(JsonParser.<jk>class</jk>)
+ * .strict() <jc>// Enable strict mode on JsonParser.</jc>
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_parsers}
@@ -2580,7 +2637,25 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Parser.
*
* <p>
- * Shortcut for calling {@link #parsers(Parser...)}.
+ * Associates the specified {@link Parser Parser} with the HTTP client.
+ *
+ * <p>
+ * The parser is used to parse the HTTP response body into a POJO.
+ *
+ * <ul class='notes'>
+ * <li>When using this method that takes in a pre-instantiated parser, the parser property setters (e.g. {@link #strict()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined
+ * on this builder class have no effect.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses a predefined JSON parser for response bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .parser(JsonParser.<jsf>DEFAULT_STRICT</jsf>)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_parsers}
@@ -2603,9 +2678,27 @@ public class RestClientBuilder extends BeanContextBuilder {
* Associates the specified {@link Parser Parsers} with the HTTP client.
*
* <p>
+ * The parsers are used to parse the HTTP response body into a POJO.
+ *
+ * <p>
* The parser that best matches the <c>Accept</c> header will be used to parse the response body.
* <br>If no <c>Accept</c> header is specified, the first parser in the list will be used.
*
+ * <ul class='notes'>
+ * <li>When using this method that takes in classes, the parsers can be configured using any of the parser property setters (e.g. {@link #strict()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined on this builder class.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses JSON and XML transport for response bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .parser(JsonParser.<jk>class</jk>, XmlParser.<jk>class</jk>)
+ * .strict() <jc>// Enable strict mode on parsers.</jc>
+ * .build();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_parsers}
* </ul>
@@ -2625,7 +2718,29 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Parsers.
*
* <p>
- * Same as {@link #parsers(Class...)} except takes in a parser instance.
+ * Associates the specified {@link Parser Parsers} with the HTTP client.
+ *
+ * <p>
+ * The parsers are used to parse the HTTP response body into a POJO.
+ *
+ * <p>
+ * The parser that best matches the <c>Accept</c> header will be used to parse the response body.
+ * <br>If no <c>Accept</c> header is specified, the first parser in the list will be used.
+ *
+ * <ul class='notes'>
+ * <li>When using this method that takes in pre-instantiated parsers, the parser property setters (e.g. {@link #strict()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined
+ * on this builder class have no effect.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses JSON and XML transport for response bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .parser(JsonParser.<jsf>DEFAULT_STRICT</jsf>, XmlParser.<jsf>DEFAULT</jsf>)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_parsers}
@@ -2647,6 +2762,18 @@ public class RestClientBuilder extends BeanContextBuilder {
* <p>
* The parser to use for parsing POJOs from form data, query parameters, headers, and path variables.
*
+ * <p>
+ * The default part parser is {@link OpenApiParser} which allows for schema-driven marshalling.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses UON format by default for incoming HTTP parts.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .partParser(UonParser.<js>class</js>)
+ * .build();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_partParser}
* </ul>
@@ -2665,7 +2792,19 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Part parser.
*
* <p>
- * Same as {@link #partParser(Class)} but takes in a parser instance.
+ * The parser to use for parsing POJOs from form data, query parameters, headers, and path variables.
+ *
+ * <p>
+ * The default part parser is {@link OpenApiParser} which allows for schema-driven marshalling.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses UON format by default for incoming HTTP parts.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .partParser(UonParser.<jsf>DEFAULT</jsf>)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_partParser}
@@ -2687,6 +2826,18 @@ public class RestClientBuilder extends BeanContextBuilder {
* <p>
* The serializer to use for serializing POJOs in form data, query parameters, headers, and path variables.
*
+ * <p>
+ * The default part serializer is {@link OpenApiSerializer} which allows for schema-driven marshalling.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses UON format by default for outgoing HTTP parts.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .partSerializer(UonSerializer.<js>class</js>)
+ * .build();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_partSerializer}
* </ul>
@@ -2705,7 +2856,19 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Part serializer.
*
* <p>
- * Same as {@link #partSerializer(Class)} but takes in a parser instance.
+ * The serializer to use for serializing POJOs in form data, query parameters, headers, and path variables.
+ *
+ * <p>
+ * The default part serializer is {@link OpenApiSerializer} which allows for schema-driven marshalling.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses UON format by default for outgoing HTTP parts.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .partSerializer(UonSerializer.<jsf>DEFAULT</jsf>)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_partSerializer}
@@ -2729,6 +2892,20 @@ public class RestClientBuilder extends BeanContextBuilder {
* will be prefixed with the specified root.
* <br>This root URL is ignored on those methods if you pass in a {@link URL}, {@link URI}, or an absolute URL string.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses UON format by default for HTTP parts.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .rootUri(<js>"http://localhost:10000/foo"</js>)
+ * .build();
+ *
+ * Bar bar = client
+ * .get(<js>"/bar"</js>) // Relative to http://localhost:10000/foo
+ * .run()
+ * .getBody().as(Bar.<jk>class</jk>);
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_rootUri}
* </ul>
@@ -2748,7 +2925,25 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Serializer.
*
* <p>
- * Shortcut for calling {@link #serializers(Class...)}.
+ * Associates the specified {@link Serializer Serializer} with the HTTP client.
+ *
+ * <p>
+ * The serializer is used to serialize POJOs into the HTTP request body.
+ *
+ * <ul class='notes'>
+ * <li>When using this method that takes in a class, the serializer can be configured using any of the serializer property setters (e.g. {@link #sortCollections()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined on this builder class.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses JSON transport for request bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .serializer(JsonSerializer.<jk>class</jk>)
+ * .sortCollections() <jc>// Sort any collections being serialized.</jc>
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_serializers}
@@ -2769,7 +2964,25 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Serializer.
*
* <p>
- * Shortcut for calling {@link #serializers(Serializer...)}.
+ * Associates the specified {@link Serializer Serializer} with the HTTP client.
+ *
+ * <p>
+ * The serializer is used to serialize POJOs into the HTTP request body.
+ *
+ * <ul class='notes'>
+ * <li>When using this method that takes in a pre-instantiated serializer, the serializer property setters (e.g. {@link #sortCollections()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined
+ * on this builder class have no effect.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses a predefined JSON serializer request bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .serializer(JsonSerializer.<jsf>DEFAULT_READABLE</jsf>)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_serializers}
@@ -2792,9 +3005,27 @@ public class RestClientBuilder extends BeanContextBuilder {
* Associates the specified {@link Serializer Serializers} with the HTTP client.
*
* <p>
+ * The serializer is used to serialize POJOs into the HTTP request body.
+ *
+ * <p>
* The serializer that best matches the <c>Content-Type</c> header will be used to serialize the request body.
* <br>If no <c>Content-Type</c> header is specified, the first serializer in the list will be used.
*
+ * <ul class='notes'>
+ * <li>When using this method that takes in classes, the serializers can be configured using any of the serializer property setters (e.g. {@link #sortCollections()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined on this builder class.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses JSON and XML transport for request bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .serializers(JsonSerializer.<jk>class</jk>,XmlSerializer.<jk>class</jk>)
+ * .sortCollections() <jc>// Sort any collections being serialized.</jc>
+ * .build();
+ * </p>
+
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_serializers}
* </ul>
@@ -2814,7 +3045,29 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Serializers.
*
* <p>
- * Same as {@link #serializers(Class...)} but takes in serializer instances.
+ * Associates the specified {@link Serializer Serializers} with the HTTP client.
+ *
+ * <p>
+ * The serializer is used to serialize POJOs into the HTTP request body.
+ *
+ * <p>
+ * The serializer that best matches the <c>Content-Type</c> header will be used to serialize the request body.
+ * <br>If no <c>Content-Type</c> header is specified, the first serializer in the list will be used.
+ *
+ * <ul class='notes'>
+ * <li>When using this method that takes in a pre-instantiated serializers, the serializer property setters (e.g. {@link #sortCollections()}),
+ * bean context property setters (e.g. {@link #pojoSwaps(Class...)}), or generic property setters (e.g. {@link #set(String, Object)}) defined
+ * on this builder class have no effect.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a client that uses predefined JSON and XML serializers for request bodies.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .serializers(JsonSerializer.<jsf>DEFAULT_READABLE</jsf>,XmlSerializer.<jsf>DEFAULT_READABLE</jsf>)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link RestClient#RESTCLIENT_serializers}
@@ -2830,15 +3083,55 @@ public class RestClientBuilder extends BeanContextBuilder {
return prependTo(RESTCLIENT_serializers, value);
}
+ //-----------------------------------------------------------------------------------------------------------------
+ // BeanTraverse Properties
+ //-----------------------------------------------------------------------------------------------------------------
+
/**
- * Configuration property: Add <js>"_type"</js> properties when needed.
+ * Configuration property: Automatically detect POJO recursions.
*
* <p>
- * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
- * through reflection.
+ * When enabled, specifies that recursions should be checked for during traversal.
+ *
+ * <p>
+ * Recursions can occur when traversing models that aren't true trees but rather contain loops.
+ * <br>In general, unchecked recursions cause stack-overflow-errors.
+ * <br>These show up as {@link BeanRecursionException BeanRecursionException} with the message <js>"Depth too deep. Stack overflow occurred."</js>.
+ *
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that automatically checks for recursions.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .detectRecursions(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Create a POJO model with a recursive loop.</jc>
+ * <jk>public class</jk> A {
+ * <jk>public</jk> Object <jf>f</jf>;
+ * }
+ * A a = <jk>new</jk> A();
+ * a.<jf>f</jf> = a;
+ *
+ * <jc>// Throws a RestCallException with an inner SerializeException and not a StackOverflowError</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
+ *
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes}
+ * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_detectRecursions}
* </ul>
*
* @param value
@@ -2847,36 +3140,107 @@ public class RestClientBuilder extends BeanContextBuilder {
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder addBeanTypes(boolean value) {
- return set(SERIALIZER_addBeanTypes, value);
+ public RestClientBuilder detectRecursions(boolean value) {
+ return set(BEANTRAVERSE_detectRecursions, value);
}
/**
- * Configuration property: Add <js>"_type"</js> properties when needed.
+ * Configuration property: Automatically detect POJO recursions.
+ *
+ * <p>
+ * When enabled, specifies that recursions should be checked for during traversal.
*
* <p>
- * Shortcut for calling <code>addBeanTypes(<jk>true</jk>)</code>.
+ * Recursions can occur when traversing models that aren't true trees but rather contain loops.
+ * <br>In general, unchecked recursions cause stack-overflow-errors.
+ * <br>These show up as {@link BeanRecursionException BeanRecursionException} with the message <js>"Depth too deep. Stack overflow occurred."</js>.
+ *
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that automatically checks for recursions.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .detectRecursions()
+ * .build();
+ *
+ * <jc>// Create a POJO model with a recursive loop.</jc>
+ * <jk>public class</jk> A {
+ * <jk>public</jk> Object <jf>f</jf>;
+ * }
+ * A a = <jk>new</jk> A();
+ * a.<jf>f</jf> = a;
+ *
+ * <jc>// Throws a RestCallException with an inner SerializeException and not a StackOverflowError</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
+ *
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes}
+ * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_detectRecursions}
* </ul>
*
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder addBeanTypes() {
- return set(SERIALIZER_addBeanTypes, true);
+ public RestClientBuilder detectRecursions() {
+ return set(BEANTRAVERSE_detectRecursions, true);
}
/**
- * Configuration property: Add type attribute to root nodes.
+ * Configuration property: Ignore recursion errors.
*
* <p>
- * When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
- * type information that might normally be included to determine the data type will not be serialized.
+ * When enabled, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
+ *
+ * <p>
+ * For example, if a model contains the links A->B->C->A, then the JSON generated will look like
+ * the following when <jsf>BEANTRAVERSE_ignoreRecursions</jsf> is <jk>true</jk>...
+ *
+ * <p class='bcode w800'>
+ * {A:{B:{C:<jk>null</jk>}}}
+ * </p>
+ *
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that ignores recursions.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .ignoreRecursions(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Create a POJO model with a recursive loop.</jc>
+ * <jk>public class</jk> A {
+ * <jk>public</jk> Object <jf>f</jf>;
+ * }
+ * A a = <jk>new</jk> A();
+ * a.<jf>f</jf> = a;
+ *
+ * <jc>// Produces request body "{f:null}"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_addRootType}
+ * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_ignoreRecursions}
* </ul>
*
* @param value
@@ -2885,83 +3249,184 @@ public class RestClientBuilder extends BeanContextBuilder {
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder addRootType(boolean value) {
- return set(SERIALIZER_addRootType, value);
+ public RestClientBuilder ignoreRecursions(boolean value) {
+ return set(BEANTRAVERSE_ignoreRecursions, value);
}
/**
- * Configuration property: Add type attribute to root nodes.
+ * Configuration property: Ignore recursion errors.
*
* <p>
- * Shortcut for calling <code>addRootType(<jk>true</jk>)</code>.
+ * When enabled, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>.
+ *
+ * <p>
+ * For example, if a model contains the links A->B->C->A, then the JSON generated will look like
+ * the following when <jsf>BEANTRAVERSE_ignoreRecursions</jsf> is <jk>true</jk>...
+ *
+ * <p class='bcode w800'>
+ * {A:{B:{C:<jk>null</jk>}}}
+ * </p>
+ *
+ * <ul class='notes'>
+ * <li>
+ * Checking for recursion can cause a small performance penalty.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that ignores recursions.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .ignoreRecursions()
+ * .build();
+ *
+ * <jc>// Create a POJO model with a recursive loop.</jc>
+ * <jk>public class</jk> A {
+ * <jk>public</jk> Object <jf>f</jf>;
+ * }
+ * A a = <jk>new</jk> A();
+ * a.<jf>f</jf> = a;
+ *
+ * <jc>// Produces request body "{f:null}"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_addRootType}
+ * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_ignoreRecursions}
* </ul>
*
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder addRootType() {
- return set(SERIALIZER_addRootType, true);
+ public RestClientBuilder ignoreRecursions() {
+ return set(BEANTRAVERSE_ignoreRecursions, true);
}
/**
- * Configuration property: Automatically detect POJO recursions.
+ * Configuration property: Initial depth.
*
* <p>
- * Specifies that recursions should be checked for during serialization.
+ * The initial indentation level at the root.
*
- * <ul class='notes'>
- * <li>
- * Checking for recursion can cause a small performance penalty.
- * </ul>
+ * <p>
+ * Useful when constructing document fragments that need to be indented at a certain level when whitespace is enabled.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer with whitespace enabled and an initial depth of 2.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .ws()
+ * .initialDepth(2)
+ * .build();
+ *
+ * <jc>// Produces request body "\t\t{\n\t\t\t'foo':'bar'\n\t\t}\n"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_detectRecursions}
+ * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_initialDepth}
* </ul>
*
* @param value
* The new value for this property.
- * <br>The default is <jk>false</jk>.
+ * <br>The default is <c>0</c>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder detectRecursions(boolean value) {
- return set(BEANTRAVERSE_detectRecursions, value);
+ public RestClientBuilder initialDepth(int value) {
+ return set(BEANTRAVERSE_initialDepth, value);
}
/**
- * Configuration property: Automatically detect POJO recursions.
+ * Configuration property: Max serialization depth.
+ *
+ * <p>
+ * When enabled, abort traversal if specified depth is reached in the POJO tree.
+ *
+ * <p>
+ * If this depth is exceeded, an exception is thrown.
*
* <p>
- * Shortcut for calling <code>detectRecursions(<jk>true</jk>)</code>.
+ * This prevents stack overflows from occurring when trying to traverse models with recursive references.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that throws an exception if the depth reaches greater than 20.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .maxDepth(20)
+ * .build();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_detectRecursions}
+ * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_maxDepth}
* </ul>
*
+ * @param value
+ * The new value for this property.
+ * <br>The default is <c>100</c>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder detectRecursions() {
- return set(BEANTRAVERSE_detectRecursions, true);
+ public RestClientBuilder maxDepth(int value) {
+ return set(BEANTRAVERSE_maxDepth, value);
}
+ //-----------------------------------------------------------------------------------------------------------------
+ // Serializer Properties
+ //-----------------------------------------------------------------------------------------------------------------
+
/**
- * Configuration property: Ignore recursion errors.
+ * Configuration property: Add <js>"_type"</js> properties when needed.
*
* <p>
- * If <jk>true</jk>, when we encounter the same object when serializing a tree, we set the value to <jk>null</jk>.
- * Otherwise, an exception is thrown.
+ * When enabled, <js>"_type"</js> properties will be added to beans if their type cannot be inferred
+ * through reflection.
*
- * <ul class='notes'>
- * <li>
- * Checking for recursion can cause a small performance penalty.
+ * <p>
+ * This is used to recreate the correct objects during parsing if the object types cannot be inferred.
+ * <br>For example, when serializing a <c>Map<String,Object></c> field where the bean class cannot be determined from
+ * the type of the values.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
* </ul>
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that adds _type to nodes in the request body.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .addBeanTypes(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A map of objects we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * Map<String,Object> m = new HashMap<>();
+ * m.put(<js>"foo"</js>, <jk>new</jk> MyBean());
+ *
+ * <jc>// Request body will contain '_type' attribute.</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
+ *
* <ul class='seealso'>
- * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_ignoreRecursions}
+ * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes}
* </ul>
*
* @param value
@@ -2970,65 +3435,165 @@ public class RestClientBuilder extends BeanContextBuilder {
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder ignoreRecursions(boolean value) {
- return set(BEANTRAVERSE_ignoreRecursions, value);
+ public RestClientBuilder addBeanTypes(boolean value) {
+ return set(SERIALIZER_addBeanTypes, value);
}
/**
- * Configuration property: Ignore recursion errors.
+ * Configuration property: Add <js>"_type"</js> properties when needed.
+ *
+ * <p>
+ * When enabled, <js>"_type"</js> properties will be added to beans if their type cannot be inferred
+ * through reflection.
*
* <p>
- * Shortcut for calling <code>ignoreRecursions(<jk>true</jk>)</code>.
+ * This is used to recreate the correct objects during parsing if the object types cannot be inferred.
+ * <br>For example, when serializing a <c>Map<String,Object></c> field where the bean class cannot be determined from
+ * the type of the values.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that adds _type to nodes in the request body.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .addBeanTypes()
+ * .build();
+ *
+ * <jc>// A map of objects we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * Map<String,Object> m = new HashMap<>();
+ * m.put(<js>"foo"</js>, <jk>new</jk> MyBean());
+ *
+ * <jc>// Request body will contain '_type' attribute.</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_ignoreRecursions}
+ * <li class='jf'>{@link Serializer#SERIALIZER_addBeanTypes}
* </ul>
*
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder ignoreRecursions() {
- return set(BEANTRAVERSE_ignoreRecursions, true);
+ public RestClientBuilder addBeanTypes() {
+ return set(SERIALIZER_addBeanTypes, true);
}
/**
- * Configuration property: Initial depth.
+ * Configuration property: Add type attribute to root nodes.
*
* <p>
- * The initial indentation level at the root.
+ * When enabled, <js>"_type"</js> properties will be added to top-level beans.
+ *
+ * <p>
+ * When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
+ * type information that might normally be included to determine the data type will not be serialized.
+ *
+ * <p>
+ * For example, when serializing a top-level POJO with a {@link Bean#typeName() @Bean(typeName)} value, a
+ * <js>'_type'</js> attribute will only be added when this setting is enabled.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that adds _type to root node.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .addRootType(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// The bean we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * <jc>// Request body will contain '_type' attribute.</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_initialDepth}
+ * <li class='jf'>{@link Serializer#SERIALIZER_addRootType}
* </ul>
*
* @param value
* The new value for this property.
- * <br>The default is <c>0</c>.
+ * <br>The default is <jk>false</jk>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder initialDepth(int value) {
- return set(BEANTRAVERSE_initialDepth, value);
+ public RestClientBuilder addRootType(boolean value) {
+ return set(SERIALIZER_addRootType, value);
}
/**
- * Configuration property: Don't trim null bean property values.
+ * Configuration property: Add type attribute to root nodes.
+ *
+ * <p>
+ * When enabled, <js>"_type"</js> properties will be added to top-level beans.
+ *
+ * <p>
+ * When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level
+ * type information that might normally be included to determine the data type will not be serialized.
+ *
+ * <p>
+ * For example, when serializing a top-level POJO with a {@link Bean#typeName() @Bean(typeName)} value, a
+ * <js>'_type'</js> attribute will only be added when this setting is enabled.
*
* <p>
- * If <jk>true</jk>, null bean values will be serialized to the output.
+ * Note the differences between the following settings:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link #addRootType()} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #addBeanTypes()} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a JSON client that adds _type to root node.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .addRootType()
+ * .build();
+ *
+ * <jc>// The bean we want to serialize.</jc>
+ * <ja>@Bean</ja>(typeName=<js>"mybean"</js>)
+ * <jk>public class</jk> MyBean {...}
+ *
+ * <jc>// Request body will contain '_type' attribute.</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, m)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_keepNullProperties}
+ * <li class='jf'>{@link Serializer#SERIALIZER_addRootType}
* </ul>
*
- * @param value
- * The new value for this property.
- * <br>The default is <jk>false</jk>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder keepNullProperties(boolean value) {
- return set(SERIALIZER_keepNullProperties, value);
+ public RestClientBuilder addRootType() {
+ return set(SERIALIZER_addRootType, true);
}
/**
@@ -3037,63 +3602,111 @@ public class RestClientBuilder extends BeanContextBuilder {
* <p>
* When enabled, null bean values will be serialized to the output.
*
- * <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_keepNullProperties}
+ * <ul class='notes'>
+ * <li>Not enabling this setting will cause <c>Map</c>s with <jk>null</jk> values to be lost during parsing.
* </ul>
*
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder keepNullProperties() {
- return set(SERIALIZER_keepNullProperties, true);
- }
-
- /**
- * Configuration property: Serializer listener.
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that serializes null properties.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .keepNullProperties(<jk>true</jk>)
+ * .build();
*
- * <p>
- * Class used to listen for errors and warnings that occur during serialization.
+ * <jc>// Our bean to serialize.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
+ * }
+ *
+ * <jc>// Request body will contain "{foo:null}".</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_listener}
+ * <li class='jf'>{@link Serializer#SERIALIZER_keepNullProperties}
* </ul>
*
* @param value
* The new value for this property.
+ * <br>The default is <jk>false</jk>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder serializerListener(Class<? extends SerializerListener> value) {
- return set(SERIALIZER_listener, value);
+ public RestClientBuilder keepNullProperties(boolean value) {
+ return set(SERIALIZER_keepNullProperties, value);
}
/**
- * Configuration property: Max serialization depth.
+ * Configuration property: Don't trim null bean property values.
*
* <p>
- * Abort serialization if specified depth is reached in the POJO tree.
- * <br>If this depth is exceeded, an exception is thrown.
- * <br>This prevents stack overflows from occurring when trying to serialize models with recursive references.
+ * When enabled, null bean values will be serialized to the output.
+ *
+ * <ul class='notes'>
+ * <li>Not enabling this setting will cause <c>Map</c>s with <jk>null</jk> values to be lost during parsing.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that serializes null properties.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .keepNullProperties()
+ * .build();
+ *
+ * <jc>// Our bean to serialize.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <jk>null</jk>;
+ * }
+ *
+ * <jc>// Request body will contain "{foo:null}".</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link BeanTraverseContext#BEANTRAVERSE_maxDepth}
+ * <li class='jf'>{@link Serializer#SERIALIZER_keepNullProperties}
* </ul>
*
- * @param value
- * The new value for this property.
- * <br>The default is <c>100</c>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder maxDepth(int value) {
- return set(BEANTRAVERSE_maxDepth, value);
+ public RestClientBuilder keepNullProperties() {
+ return set(SERIALIZER_keepNullProperties, true);
}
/**
* Configuration property: Sort arrays and collections alphabetically.
*
* <p>
- * Copies and sorts the contents of arrays and collections before serializing them.
+ * When enabled, copies and sorts the contents of arrays and collections before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty since it requires copying the existing collection.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that sorts arrays and collections before serialization.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .sortCollections(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// An unsorted array</jc>
+ * String[] array = {<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>}
+ *
+ * <jc>// Request body will contain ["bar","baz","foo"]</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, array)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortCollections}
@@ -3113,7 +3726,28 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Sort arrays and collections alphabetically.
*
* <p>
- * Shortcut for calling <code>sortCollections(<jk>true</jk>)</code>.
+ * When enabled, copies and sorts the contents of arrays and collections before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty since it requires copying the existing collection.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that sorts arrays and collections before serialization.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .sortCollections()
+ * .build();
+ *
+ * <jc>// An unsorted array</jc>
+ * String[] array = {<js>"foo"</js>,<js>"bar"</js>,<js>"baz"</js>}
+ *
+ * <jc>// Request body will contain ["bar","baz","foo"]</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, array)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortCollections}
@@ -3130,7 +3764,28 @@ public class RestClientBuilder extends BeanContextBuilder {
* Sets the {@link Serializer#SERIALIZER_sortMaps} property on all serializers in this group.
*
* <p>
- * Copies and sorts the contents of maps before serializing them.
+ * When enabled, copies and sorts the contents of maps by their keys before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that sorts maps before serialization.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .sortMaps(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// An unsorted map.</jc>
+ * OMap m = OMap.<jsm>of</jsm>(<js>"foo"</js>,1,<js>"bar"</js>,2,<js>"baz"</js>,3);
+ *
+ * <jc>// Request body will contain {"bar":2,"baz":3,"foo":1}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, map)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortMaps}
@@ -3148,7 +3803,28 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Sort maps alphabetically.
*
* <p>
- * Shortcut for calling <code>sortMaps(<jk>true</jk>)</code>.
+ * When enabled, copies and sorts the contents of maps by their keys before serializing them.
+ *
+ * <p>
+ * Note that this introduces a performance penalty.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that sorts maps before serialization.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .sortMaps()
+ * .build();
+ *
+ * <jc>// An unsorted map.</jc>
+ * OMap m = OMap.<jsm>of</jsm>(<js>"foo"</js>,1,<js>"bar"</js>,2,<js>"baz"</js>,3);
+ *
+ * <jc>// Request body will contain {"bar":2,"baz":3,"foo":1}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, map)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_sortMaps}
@@ -3165,7 +3841,35 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim empty lists and arrays.
*
* <p>
- * If <jk>true</jk>, empty list values will not be serialized to the output.
+ * When enabled, empty lists and arrays will not be serialized.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Map entries with empty list values will be lost.
+ * <li>
+ * Bean properties with empty list values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that skips empty arrays and collections.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyCollections(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty array.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String[] <jf>foo</jf> = {};
+ * }
+ *
+ * <jc>// Request body will contain {}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyCollections}
@@ -3185,7 +3889,35 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim empty lists and arrays.
*
* <p>
- * Shortcut for calling <code>trimEmptyCollections(<jk>true</jk>)</code>.
+ * When enabled, empty lists and arrays will not be serialized.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Map entries with empty list values will be lost.
+ * <li>
+ * Bean properties with empty list values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a serializer that skips empty arrays and collections.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyCollections()
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty array.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String[] <jf>foo</jf> = {};
+ * }
+ *
+ * <jc>// Request body will contain {}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyCollections}
@@ -3202,7 +3934,34 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim empty maps.
*
* <p>
- * If <jk>true</jk>, empty map values will not be serialized to the output.
+ * When enabled, empty map values will not be serialized to the output.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Bean properties with empty map values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that skips empty maps.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .trimEmptyMaps(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty map.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> OMap <jf>foo</jf> = OMap.<jsm>of</jsm>();
+ * }
+ *
+ * <jc>// Request body will contain {}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyMaps}
@@ -3222,7 +3981,34 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim empty maps.
*
* <p>
- * Shortcut for calling <code>trimEmptyMaps(<jk>true</jk>)</code>.
+ * When enabled, empty map values will not be serialized to the output.
+ *
+ * <p>
+ * Note that enabling this setting has the following effects on parsing:
+ * <ul class='spaced-list'>
+ * <li>
+ * Bean properties with empty map values will not be set.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that skips empty maps.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .trimEmptyMaps()
+ * .build();
+ *
+ * <jc>// A bean with a field with an empty map.</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> OMap <jf>foo</jf> = OMap.<jsm>of</jsm>();
+ * }
+ *
+ * <jc>// Request body will contain {}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimEmptyMaps}
@@ -3236,32 +4022,29 @@ public class RestClientBuilder extends BeanContextBuilder {
}
/**
- * Configuration property: Trim null bean property values.
+ * Configuration property: Trim strings.
*
* <p>
- * If <jk>true</jk>, null bean values will not be serialized to the output.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
*
- * <ul class='seealso'>
- * <li class='jf'>{@link Serializer#SERIALIZER_trimNullProperties}
- * </ul>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that trims strings before serialization.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .trimStrings(<jk>true</jk>)
+ * .build();
*
- * @param value
- * The new value for this property.
- * <br>The default is <jk>true</jk>.
- * @return This object (for method chaining).
- * @deprecated Use {@link #keepNullProperties(boolean)}
- */
- @Deprecated
- @ConfigurationProperty
- public RestClientBuilder trimNullProperties(boolean value) {
- return set(SERIALIZER_trimNullProperties, value);
- }
-
- /**
- * Configuration property: Trim strings.
+ * <jc>// A map with space-padded keys/values</jc>
+ * Map<String,String> map = <jk>new</jk> HashMap<>();
+ * m.put(<js>" foo "</js>, <js>" bar "</js>);
*
- * <p>
- * If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ * <jc>// Request body will contain "{"foo":"bar"}"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, map)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimStrings}
@@ -3281,7 +4064,26 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim strings.
*
* <p>
- * Shortcut for calling <code>trimStrings(<jk>true</jk>)</code>.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that trims strings before serialization.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .trimStrings()
+ * .build();
+ *
+ * <jc>// A map with space-padded keys/values</jc>
+ * Map<String,String> map = <jk>new</jk> HashMap<>();
+ * m.put(<js>" foo "</js>, <js>" bar "</js>);
+ *
+ * <jc>// Request body will contain "{"foo":"bar"}"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, map)
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_trimStrings}
@@ -3300,8 +4102,38 @@ public class RestClientBuilder extends BeanContextBuilder {
* <p>
* Bean used for resolution of URIs to absolute or root-relative form.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Our URI contextual information.</jc>
+ * String authority = <js>"http://localhost:10000"</js>;
+ * String contextRoot = <js>"/myContext"</js>;
+ * String servletPath = <js>"/myServlet"</js>;
+ * String pathInfo = <js>"/foo"</js>;
+ *
+ * <jc>// Create a UriContext object.</jc>
+ * UriContext uriContext = <jk>new</jk> UriContext(authority, contextRoot, servletPath, pathInfo);
+ *
+ * <jc>// Create a REST client with JSON serializer and associate our context.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .uriContext(uriContext)
+ * .uriRelativity(<jsf>RESOURCE</jsf>) <jc>// Assume relative paths are relative to servlet.</jc>
+ * .uriResolution(<jsf>ABSOLUTE</jsf>) <jc>// Serialize URLs as absolute paths.</jc>
+ * .build();
+ *
+ * <jc>// A relative URL</jc>
+ * URL url = <jk>new</jk> URL(<js>"bar"</js>);
+ *
+ * <jc>// Request body will contain "http://localhost:10000/myContext/myServlet/foo/bar"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, url)
+ * .complete();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_uriContext}
+ * <li class='link'>{@doc juneau-marshall.URIs}
* </ul>
*
* @param value The new value for this property.
@@ -3316,10 +4148,28 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: URI relativity.
*
* <p>
- * Defines what relative URIs are relative to when serializing URI/URL objects.
+ * Defines what relative URIs are relative to when serializing any of the following:
+ * <ul>
+ * <li>{@link java.net.URI}
+ * <li>{@link java.net.URL}
+ * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI}
+ * </ul>
+ *
+ * <p>
+ * Possible values are:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link org.apache.juneau.UriRelativity#RESOURCE}
+ * - Relative URIs should be considered relative to the servlet URI.
+ * <li class='jf'>{@link org.apache.juneau.UriRelativity#PATH_INFO}
+ * - Relative URIs should be considered relative to the request URI.
+ * </ul>
+ *
+ * <p>
+ * See {@link #uriContext(UriContext)} for examples.
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_uriRelativity}
+ * <li class='link'>{@doc juneau-marshall.URIs}
* </ul>
*
* @param value
@@ -3336,10 +4186,30 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: URI resolution.
*
* <p>
- * Defines the resolution level for URIs when serializing URI/URL objects.
+ * Defines the resolution level for URIs when serializing any of the following:
+ * <ul>
+ * <li>{@link java.net.URI}
+ * <li>{@link java.net.URL}
+ * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI}
+ * </ul>
+ *
+ * <p>
+ * Possible values are:
+ * <ul>
+ * <li class='jf'>{@link UriResolution#ABSOLUTE}
+ * - Resolve to an absolute URL (e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>).
+ * <li class='jf'>{@link UriResolution#ROOT_RELATIVE}
+ * - Resolve to a root-relative URL (e.g. <js>"/context-root/servlet-path/path-info"</js>).
+ * <li class='jf'>{@link UriResolution#NONE}
+ * - Don't do any URL resolution.
+ * </ul>
+ *
+ * <p>
+ * See {@link #uriContext(UriContext)} for examples.
*
* <ul class='seealso'>
* <li class='jf'>{@link Serializer#SERIALIZER_uriResolution}
+ * <li class='link'>{@doc juneau-marshall.URIs}
* </ul>
*
* @param value
@@ -3352,12 +4222,31 @@ public class RestClientBuilder extends BeanContextBuilder {
return set(SERIALIZER_uriResolution, value);
}
+ //-----------------------------------------------------------------------------------------------------------------
+ // WriterSerializer Properties
+ //-----------------------------------------------------------------------------------------------------------------
+
/**
* Configuration property: Maximum indentation.
*
* <p>
* Specifies the maximum indentation level in the serialized document.
*
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that indents a maximum of 20 tabs.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .ws() <jc>// Enable whitespace</jc>
+ * .maxIndent(20)
+ * .build();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_maxIndent}
* </ul>
@@ -3376,7 +4265,31 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Quote character.
*
* <p>
- * This is the character used for quoting attributes and values.
+ * Specifies the character to use for quoting attributes and values.
+ *
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that uses single quotes.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .quoteChar(<js>'\''</js>)
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Request body will contain {'foo':'bar'}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar}
@@ -3396,136 +4309,192 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Quote character.
*
* <p>
- * Shortcut for calling <code>quoteChar(<js>'\''</js>)</code>.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar}
- * </ul>
- *
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder sq() {
- return set(WSERIALIZER_quoteChar, '\'');
- }
-
- /**
- * Configuration property: Use whitespace.
- *
- * <p>
- * If <jk>true</jk>, newlines and indentation and spaces are added to the output to improve readability.
+ * Specifies to use single quotes for quoting attributes and values.
*
- * <ul class='seealso'>
- * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
+ * <ul class='notes'>
+ * <li>This setting does not apply to the RDF serializers.
* </ul>
*
- * @param value
- * The new value for this property.
- * <br>The default is <jk>false</jk>.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder useWhitespace(boolean value) {
- return set(WSERIALIZER_useWhitespace, value);
- }
-
- /**
- * Configuration property: Use whitespace.
- *
- * <p>
- * Shortcut for calling <code>useWhitespace(<jk>true</jk>)</code>.
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer that uses single quotes.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .sq()
+ * .build();
*
- * <ul class='seealso'>
- * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
- * </ul>
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder useWhitespace() {
- return set(WSERIALIZER_useWhitespace, true);
- }
-
- /**
- * Configuration property: Use whitespace.
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
*
- * <p>
- * Shortcut for calling <code>useWhitespace(<jk>true</jk>)</code>.
+ * <jc>// Request body will contain {'foo':'bar'}</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
+ * <li class='jf'>{@link WriterSerializer#WSERIALIZER_quoteChar}
* </ul>
*
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder ws() {
- return set(WSERIALIZER_useWhitespace, true);
+ public RestClientBuilder sq() {
+ return set(WSERIALIZER_quoteChar, '\'');
}
/**
- * Configuration property: Binary string format.
+ * Configuration property: Use whitespace.
*
* <p>
- * When using the {@link Serializer#serializeToString(Object)} method on stream-based serializers, this defines the format to use
- * when converting the resulting byte array to a string.
+ * When enabled, whitespace is added to the output to improve readability.
*
- * <ul class='javatree'>
- * <li class='jf'>{@link OutputStreamSerializer#OSSERIALIZER_binaryFormat}
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer with whitespace enabled.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .useWhitespace(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Request body will contain "\{\n\t"foo": "bar"\n\}\n"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
+ *
+ * <ul class='seealso'>
+ * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
* </ul>
*
* @param value
* The new value for this property.
- * <br>The default is {@link BinaryFormat#HEX}.
+ * <br>The default is <jk>false</jk>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder binaryOutputFormat(BinaryFormat value) {
- return set(OSSERIALIZER_binaryFormat, value);
+ public RestClientBuilder useWhitespace(boolean value) {
+ return set(WSERIALIZER_useWhitespace, value);
}
/**
- * Configuration property: Auto-close streams.
+ * Configuration property: Use whitespace.
+ *
+ * <p>
+ * When enabled, whitespace is added to the output to improve readability.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer with whitespace enabled.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .useWhitespace()
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
*
- * If <jk>true</jk>, <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed
- * after parsing is complete.
+ * <jc>// Request body will contain "\{\n\t"foo": "bar"\n\}\n"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Parser#PARSER_autoCloseStreams}
+ * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
* </ul>
- *
- * @param value
- * The new value for this property.
- * <br>The default value is <jk>false</jk>.
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder autoCloseStreams(boolean value) {
- return set(PARSER_autoCloseStreams, value);
+ public RestClientBuilder useWhitespace() {
+ return set(WSERIALIZER_useWhitespace, true);
}
/**
- * Configuration property: Auto-close streams.
+ * Configuration property: Use whitespace.
*
* <p>
- * Shortcut for calling <code>autoCloseStreams(<jk>true</jk>)</code>.
+ * When enabled, whitespace is added to the output to improve readability.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON serializer with whitespace enabled.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .ws()
+ * .build();
+ *
+ * <jc>// A bean with a single property</jc>
+ * <jk>public class</jk> MyBean {
+ * <jk>public</jk> String <jf>foo</jf> = <js>"bar"</js>;
+ * }
+ *
+ * <jc>// Request body will contain "\{\n\t"foo": "bar"\n\}\n"</jc>
+ * client
+ * .doPost(<js>"http://localhost:10000/foo"</js>, <jk>new</jk> MyBean())
+ * .complete();
+ * </p>
*
* <ul class='seealso'>
- * <li class='jf'>{@link Parser#PARSER_autoCloseStreams}
+ * <li class='jf'>{@link WriterSerializer#WSERIALIZER_useWhitespace}
* </ul>
*
* @return This object (for method chaining).
*/
@ConfigurationProperty
- public RestClientBuilder autoCloseStreams() {
- return set(PARSER_autoCloseStreams, true);
+ public RestClientBuilder ws() {
+ return set(WSERIALIZER_useWhitespace, true);
}
+ //-----------------------------------------------------------------------------------------------------------------
+ // OutputStreamSerializer Properties
+ //-----------------------------------------------------------------------------------------------------------------
+
+ //-----------------------------------------------------------------------------------------------------------------
+ // Parser Properties
+ //-----------------------------------------------------------------------------------------------------------------
+
/**
* Configuration property: Debug output lines.
*
+ * <p>
* When parse errors occur, this specifies the number of lines of input before and after the
* error location to be printed as part of the exception message.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a parser whose exceptions print out 100 lines before and after the parse error location.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .debug() <jc>// Enable debug mode to capture Reader contents as strings.</jc>
+ * .debugOuputLines(100)
+ * .build();
+ *
+ * <jc>// Try to parse some bad JSON.</jc>
+ * <jk>try</jk> {
+ * client
+ * .get(<js>"/pathToBadJson"</js>)
+ * .run()
+ * .getBody().as(Object.<jk>class</jk>); <jc>// Try to parse it.</jc>
+ * } <jk>catch</jk> (RestCallException e) {
+ * System.<jsf>err</jsf>.println(e.getMessage()); <jc>// Will display 200 lines of the output.</jc>
+ * }
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_debugOutputLines}
* </ul>
@@ -3542,28 +4511,58 @@ public class RestClientBuilder extends BeanContextBuilder {
}
/**
- * Configuration property: Parser listener.
+ * Configuration property: Strict mode.
*
* <p>
- * Class used to listen for errors and warnings that occur during parsing.
+ * When enabled, strict mode for the parser is enabled.
+ *
+ * <p>
+ * Strict mode can mean different things for different parsers.
+ *
+ * <table class='styled'>
+ * <tr><th>Parser class</th><th>Strict behavior</th></tr>
+ * <tr>
+ * <td>All reader-based parsers</td>
+ * <td>
+ * When enabled, throws {@link ParseException ParseExceptions} on malformed charset input.
+ * Otherwise, malformed input is ignored.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link JsonParser}</td>
+ * <td>
+ * When enabled, throws exceptions on the following invalid JSON syntax:
+ * <ul>
+ * <li>Unquoted attributes.
+ * <li>Missing attribute values.
+ * <li>Concatenated strings.
+ * <li>Javascript comments.
+ * <li>Numbers and booleans when Strings are expected.
+ * <li>Numbers valid in Java but not JSON (e.g. octal notation, etc...)
+ * </ul>
+ * </td>
+ * </tr>
+ * </table>
*
- * <ul class='seealso'>
- * <li class='jf'>{@link Parser#PARSER_listener}
- * </ul>
- *
- * @param value The new value for this property.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder parserListener(Class<? extends ParserListener> value) {
- return set(PARSER_listener, value);
- }
-
- /**
- * Configuration property: Strict mode.
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON parser using strict mode.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .strict(<jk>true</jk>)
+ * .build();
*
- * <p>
- * If <jk>true</jk>, strict mode for the parser is enabled.
+ * <jc>// Try to parse some bad JSON.</jc>
+ * <jk>try</jk> {
+ * client
+ * .get(<js>"/pathToBadJson"</js>)
+ * .run()
+ * .getBody().as(Object.<jk>class</jk>); <jc>// Try to parse it.</jc>
+ * } <jk>catch</jk> (RestCallException e) {
+ * <jc>// Handle exception.</jc>
+ * }
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_strict}
@@ -3583,7 +4582,55 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Strict mode.
*
* <p>
- * Shortcut for calling <code>strict(<jk>true</jk>)</code>.
+ * When enabled, strict mode for the parser is enabled.
+ *
+ * <p>
+ * Strict mode can mean different things for different parsers.
+ *
+ * <table class='styled'>
+ * <tr><th>Parser class</th><th>Strict behavior</th></tr>
+ * <tr>
+ * <td>All reader-based parsers</td>
+ * <td>
+ * When enabled, throws {@link ParseException ParseExceptions} on malformed charset input.
+ * Otherwise, malformed input is ignored.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td>{@link JsonParser}</td>
+ * <td>
+ * When enabled, throws exceptions on the following invalid JSON syntax:
+ * <ul>
+ * <li>Unquoted attributes.
+ * <li>Missing attribute values.
+ * <li>Concatenated strings.
+ * <li>Javascript comments.
+ * <li>Numbers and booleans when Strings are expected.
+ * <li>Numbers valid in Java but not JSON (e.g. octal notation, etc...)
+ * </ul>
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON parser using strict mode.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .strict(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Try to parse some bad JSON.</jc>
+ * <jk>try</jk> {
+ * client
+ * .get(<js>"/pathToBadJson"</js>)
+ * .run()
+ * .getBody().as(Object.<jk>class</jk>); <jc>// Try to parse it.</jc>
+ * } <jk>catch</jk> (RestCallException e) {
+ * <jc>// Handle exception.</jc>
+ * }
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_strict}
@@ -3600,9 +4647,28 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim parsed strings.
*
* <p>
- * If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
*
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON parser with trim-strings enabled.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .trimStrings(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Try to parse JSON containing {" foo ":" bar "}.</jc>
+ * Map<String,String> map = client
+ * .get(<js>"/pathToJson"</js>)
+ * .run()
+ * .getBody().as(HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
+ *
+ * <jc>// Make sure strings are trimmed.</jc>
+ * <jsm>assertEquals</jsm>(<js>"bar"</js>, map.get(<js>"foo"</js>));
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_trimStrings}
* </ul>
@@ -3621,7 +4687,27 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Trim parsed strings.
*
* <p>
- * Shortcut for calling <code>trimStrings(<jk>true</jk>)</code>.
+ * When enabled, string values will be trimmed of whitespace using {@link String#trim()} before being added to
+ * the POJO.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with JSON parser with trim-strings enabled.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .json()
+ * .trimStrings(<jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Try to parse JSON containing {" foo ":" bar "}.</jc>
+ * Map<String,String> map = client
+ * .get(<js>"/pathToJson"</js>)
+ * .run()
+ * .getBody().as(HashMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
+ *
+ * <jc>// Make sure strings are trimmed.</jc>
+ * <jsm>assertEquals</jsm>(<js>"bar"</js>, map.get(<js>"foo"</js>));
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link Parser#PARSER_trimStrings}
@@ -3634,108 +4720,59 @@ public class RestClientBuilder extends BeanContextBuilder {
return set(PARSER_trimStrings, true);
}
- /**
- * Configuration property: Unbuffered.
- *
- * If <jk>true</jk>, don't use internal buffering during parsing.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link Parser#PARSER_unbuffered}
- * </ul>
- *
- * @param value
- * The new value for this property.
- * <br>The default value is <jk>false</jk>.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder unbuffered(boolean value) {
- return set(PARSER_unbuffered, value);
- }
+ //-----------------------------------------------------------------------------------------------------------------
+ // ReaderParser Properties
+ //-----------------------------------------------------------------------------------------------------------------
- /**
- * Configuration property: Unbuffered.
- *
- * <p>
- * Shortcut for calling <code>unbuffered(<jk>true</jk>)</code>.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link Parser#PARSER_unbuffered}
- * </ul>
- *
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder unbuffered() {
- return set(PARSER_unbuffered, true);
- }
+ //-----------------------------------------------------------------------------------------------------------------
+ // InputStreamParser Properties
+ //-----------------------------------------------------------------------------------------------------------------
- /**
- * Configuration property: File charset.
- *
- * <p>
- * The character set to use for reading <c>Files</c> from the file system.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link ReaderParser#RPARSER_fileCharset}
- * </ul>
- *
- * @param value
- * The new value for this property.
- * <br>The default value is <js>"DEFAULT"</js> which causes the system default to be used.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder fileCharset(String value) {
- return set(RPARSER_fileCharset, value);
- }
+ //-----------------------------------------------------------------------------------------------------------------
+ // OpenApi Properties
+ //-----------------------------------------------------------------------------------------------------------------
/**
- * Configuration property: Input stream charset.
+ * Configuration property: Default OpenAPI format for HTTP parts.
*
* <p>
- * The character set to use for converting <c>InputStreams</c> and byte arrays to readers.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link ReaderParser#RPARSER_streamCharset}
- * </ul>
- *
- * @param value
- * The new value for this property.
- * <br>The default value is <js>"UTF-8"</js>.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder inputStreamCharset(String value) {
- return set(RPARSER_streamCharset, value);
- }
-
- /**
- * Configuration property: Binary input format.
+ * Specifies the format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#format()} for
+ * the OpenAPI serializer and parser on this client.
*
* <p>
- * When using the {@link Parser#parse(Object,Class)} method on stream-based parsers and the input is a string, this defines the format to use
- * when converting the string into a byte array.
- *
- * <ul class='seealso'>
- * <li class='jf'>{@link InputStreamParser#ISPARSER_binaryFormat}
+ * Possible values:
+ * <ul class='javatree'>
+ * <li class='jc'>{@link org.apache.juneau.httppart.HttpPartFormat}
+ * <ul>
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#UON UON} - UON notation (e.g. <js>"'foo bar'"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#INT32 INT32} - Signed 32 bits.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#INT64 INT64} - Signed 64 bits.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#FLOAT FLOAT} - 32-bit floating point number.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#DOUBLE DOUBLE} - 64-bit floating point number.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#BYTE BYTE} - BASE-64 encoded characters.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#BINARY BINARY} - Hexadecimal encoded octets (e.g. <js>"00FF"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#BINARY_SPACED BINARY_SPACED} - Spaced-separated hexadecimal encoded octets (e.g. <js>"00 FF"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#DATE DATE} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#DATE_TIME DATE_TIME} - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#PASSWORD PASSWORD} - Used to hint UIs the input needs to be obscured.
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartFormat#NO_FORMAT NO_FORMAT} - (default) Not specified.
+ * </ul>
* </ul>
*
- * @param value
- * The new value for this property.
- * <br>The default value is {@link BinaryFormat#HEX}.
- * @return This object (for method chaining).
- */
- @ConfigurationProperty
- public RestClientBuilder binaryInputFormat(BinaryFormat value) {
- return set(ISPARSER_binaryFormat, value);
- }
-
- /**
- * Configuration property: Default OpenAPI format for HTTP parts.
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with UON part serialization and parsing.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .oapiFormat(<jsf>UON</jsf>)
+ * .build();
*
- * <p>
- * Specifies the format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#format()}.
+ * <jc>// Set a header with a value in UON format.</jc>
+ * client
+ * .get(<js>"/url"</js>)
+ * .header(<js>"Foo"</js>, <js>"bar baz"</js>) // Will be serialized as [Foo: 'bar baz']
+ * .run();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link OpenApiCommon#OAPI_format}
@@ -3755,7 +4792,46 @@ public class RestClientBuilder extends BeanContextBuilder {
* Configuration property: Default collection format for HTTP parts.
*
* <p>
- * Specifies the collection format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#collectionFormat()}.
+ * Specifies the collection format to use for HTTP parts when not otherwise specified via {@link org.apache.juneau.jsonschema.annotation.Schema#collectionFormat()} for the
+ * OpenAPI serializer and parser on this client.
+ *
+ * <p>
+ * Possible values:
+ * <ul class='javatree'>
+ * <li class='jc'>{@link org.apache.juneau.httppart.HttpPartFormat}
+ * <ul>
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#CSV CSV} - (default) Comma-separated values (e.g. <js>"foo,bar"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#SSV SSV} - Space-separated values (e.g. <js>"foo bar"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#TSV TSV} - Tab-separated values (e.g. <js>"foo\tbar"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#PIPES PIPES} - Pipe-separated values (e.g. <js>"foo|bar"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#MULTI MULTI} - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>).
+ * <li class='jf'>{@link org.apache.juneau.httppart.HttpPartCollectionFormat#UONC UONC} - UON collection notation (e.g. <js>"@(foo,bar)"</js>).
+ * </ul>
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with CSV format for http parts.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .collectionFormat(<jsf>CSV</jsf>)
+ * .build();
+ *
+ * <jc>// An arbitrary data structure.</jc>
+ * OList l = OList.<jsm>of</jsm>(
+ * <js>"foo"</js>,
+ * <js>"bar"</js>,
+ * OMap.<jsm>of</jsm>(
+ * <js>"baz"</js>, OList.<jsm>of</jsm>(<js>"qux"</js>,<js>"true"</js>,<js>"123"</js>)
+ * )
+ * );
+ *
+ * <jc>// Set a header with a comma-separated list.</jc>
+ * client
+ * .get(<js>"/url"</js>)
+ * .header(<js>"Foo"</js>, l) // Will be serialized as [Foo: foo=bar,baz=qux\,true\,123]
+ * .run();
+ * </p>
*
* <ul class='seealso'>
* <li class='jf'>{@link OpenApiCommon#OAPI_collectionFormat}
@@ -3771,12 +4847,47 @@ public class RestClientBuilder extends BeanContextBuilder {
return set(OAPI_collectionFormat, value);
}
+ //-----------------------------------------------------------------------------------------------------------------
+ // UON Properties
+ //-----------------------------------------------------------------------------------------------------------------
+
/**
* Configuration property: Parameter format.
*
* <p>
* Specifies the format of parameters when using the {@link UrlEncodingSerializer} to serialize Form Posts.
*
+ * <p>
+ * Specifies the format to use for URL GET parameter keys and values.
+ *
+ * <p>
+ * Possible values:
+ * <ul class='javatree'>
+ * <li class='jf'>{@link ParamFormat#UON} (default) - Use UON notation for parameters.
+ * <li class='jf'>{@link ParamFormat#PLAINTEXT} - Use plain text for parameters.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with URL-Encoded serializer that serializes values in plain-text format.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .urlEnc()
+ * .paramFormat(<jsf>PLAINTEXT</jsf>)
+ * .build();
+ *
+ * <jc>// An arbitrary data structure.</jc>
+ * OMap map = OMap.<jsm>of</jsm>(
+ * <js>"foo"</js>, <js>"bar"</js>,
+ * <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
+ * );
+ *
+ * <jc>// Request body will be serialize as "foo=bar,baz=qux,true,123"</jc>
+ * client
+ * .post(<js>"/url"</js>, map)
+ * .run();
+ * </p>
+ *
* <ul class='seealso'>
* <li class='jf'>{@link UonSerializer#UON_paramFormat}
* </ul>
@@ -3795,6 +4906,29 @@ public class RestClientBuilder extends BeanContextBuilder {
* <p>
* Specifies the format of parameters when using the {@link UrlEncodingSerializer} to serialize Form Posts.
*
+ * <p>
+ * Specifies plaintext as the format to use for URL GET parameter keys and values.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Create a REST client with URL-Encoded serializer that serializes values in plain-text format.</jc>
+ * RestClient client = RestClient
+ * .<jsm>create</jsm>()
+ * .urlEnc()
+ * .paramFormatPlain()
+ * .build();
+ *
+ * <jc>// An arbitrary data structure.</jc>
+ * OMap map = OMap.<jsm>of</jsm>(
+ * <js>"foo"</js>, <js>"bar"</js>,
+ * <js>"baz"</js>, <jk>new</jk> String[]{<js>"qux"</js>, <js>"true"</js>, <js>"123"</js>}
+ * );
+ *
+ * <jc>// Request body will be serialize as "foo=bar,baz=qux,true,123"</jc>
+ * client
+ * .post(<js>"/url"</js>, map)
+ * .run();
+ * </p>
* <ul class='seealso'>
* <li class='jf'>{@link UonSerializer#UON_paramFormat}
* </ul>
diff --git a/juneau-rest/juneau-rest-mock/src/main/java/org/apache/juneau/rest/mock2/MockRestClient.java b/juneau-rest/juneau-rest-mock/src/main/java/org/apache/juneau/rest/mock2/MockRestClient.java
index 309221b..bfa28af 100644
--- a/juneau-rest/juneau-rest-mock/src/main/java/org/apache/juneau/rest/mock2/MockRestClient.java
+++ b/juneau-rest/juneau-rest-mock/src/main/java/org/apache/juneau/rest/mock2/MockRestClient.java
@@ -866,36 +866,12 @@ public class MockRestClient extends RestClientBuilder {
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient autoCloseStreams() {
- super.autoCloseStreams();
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
- public MockRestClient autoCloseStreams(boolean value) {
- super.autoCloseStreams(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
public MockRestClient basicAuth(String host, int port, String user, String pw) {
super.basicAuth(host, port, user, pw);
return this;
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient binaryInputFormat(BinaryFormat value) {
- super.binaryInputFormat(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
- public MockRestClient binaryOutputFormat(BinaryFormat value) {
- super.binaryOutputFormat(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
public MockRestClient cacheControl(Object value) {
super.cacheControl(value);
return this;
@@ -980,12 +956,6 @@ public class MockRestClient extends RestClientBuilder {
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient fileCharset(String value) {
- super.fileCharset(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
public MockRestClient formData(Object...params) {
super.formData(params);
return this;
@@ -1148,12 +1118,6 @@ public class MockRestClient extends RestClientBuilder {
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient inputStreamCharset(String value) {
- super.inputStreamCharset(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
@SuppressWarnings("unchecked")
public MockRestClient interceptors(java.lang.Class<? extends org.apache.juneau.rest.client2.RestCallInterceptor>...values) throws Exception{
super.interceptors(values);
@@ -1323,12 +1287,6 @@ public class MockRestClient extends RestClientBuilder {
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient parserListener(Class<? extends org.apache.juneau.parser.ParserListener> value) {
- super.parserListener(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
@SuppressWarnings("unchecked")
public MockRestClient parsers(java.lang.Class<? extends org.apache.juneau.parser.Parser>...value) {
super.parsers(value);
@@ -1456,12 +1414,6 @@ public class MockRestClient extends RestClientBuilder {
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient serializerListener(Class<? extends org.apache.juneau.serializer.SerializerListener> value) {
- super.serializerListener(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
@SuppressWarnings("unchecked")
public MockRestClient serializers(java.lang.Class<? extends org.apache.juneau.serializer.Serializer>...value) {
super.serializers(value);
@@ -1552,12 +1504,6 @@ public class MockRestClient extends RestClientBuilder {
return this;
}
- @Deprecated @Override /* GENERATED - RestClientBuilder */
- public MockRestClient trimNullProperties(boolean value) {
- super.trimNullProperties(value);
- return this;
- }
-
@Override /* GENERATED - RestClientBuilder */
public MockRestClient trimStringsOnRead() {
super.trimStringsOnRead();
@@ -1583,18 +1529,6 @@ public class MockRestClient extends RestClientBuilder {
}
@Override /* GENERATED - RestClientBuilder */
- public MockRestClient unbuffered() {
- super.unbuffered();
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
- public MockRestClient unbuffered(boolean value) {
- super.unbuffered(value);
- return this;
- }
-
- @Override /* GENERATED - RestClientBuilder */
public MockRestClient uon() {
super.uon();
return this;