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 2018/01/13 22:12:02 UTC
[3/4] juneau git commit: Update javadocs.
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSessionArgs.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSessionArgs.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSessionArgs.java
index 4a69e82..b6debb8 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSessionArgs.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSessionArgs.java
@@ -26,26 +26,31 @@ public class BeanSessionArgs extends SessionArgs {
*/
public static final BeanSessionArgs DEFAULT = new BeanSessionArgs(ObjectMap.EMPTY_MAP, null, null, null);
- final Locale locale;
- final TimeZone timeZone;
- final MediaType mediaType;
+ Locale locale;
+ TimeZone timeZone;
+ MediaType mediaType;
/**
+ * Constructor
+ */
+ public BeanSessionArgs() {}
+
+ /**
* Constructor.
*
* @param properties
* Session-level properties.
- * These override context-level properties.
- * Can be <jk>null</jk>.
+ * <br>These override context-level properties.
+ * <br>Can be <jk>null</jk>.
* @param locale
* The session locale.
- * If <jk>null</jk>, then the locale defined on the context is used.
+ * <br>If <jk>null</jk>, then the locale defined on the context is used.
* @param timeZone
* The session timezone.
- * If <jk>null</jk>, then the timezone defined on the context is used.
+ * <br>If <jk>null</jk>, then the timezone defined on the context is used.
* @param mediaType
* The session media type (e.g. <js>"application/json"</js>).
- * Can be <jk>null</jk>.
+ * <br>Can be <jk>null</jk>.
*/
public BeanSessionArgs(ObjectMap properties, Locale locale, TimeZone timeZone, MediaType mediaType) {
super(properties);
@@ -53,4 +58,49 @@ public class BeanSessionArgs extends SessionArgs {
this.timeZone = timeZone;
this.mediaType = mediaType;
}
+
+ /**
+ * The session locale.
+ *
+ * @param locale
+ * The session locale.
+ * <br>If <jk>null</jk>, then the locale defined on the context is used.
+ * @return This object (for method chaining).
+ */
+ public BeanSessionArgs locale(Locale locale) {
+ this.locale = locale;
+ return this;
+ }
+
+ /**
+ * The session timezone.
+ *
+ * @param timeZone
+ * The session timezone.
+ * <br>If <jk>null</jk>, then the timezone defined on the context is used.
+ * @return This object (for method chaining).
+ */
+ public BeanSessionArgs timeZone(TimeZone timeZone) {
+ this.timeZone = timeZone;
+ return this;
+ }
+
+ /**
+ * The session media type.
+ *
+ * @param mediaType
+ * The session media type (e.g. <js>"application/json"</js>).
+ * <br>Can be <jk>null</jk>.
+ * @return This object (for method chaining).
+ */
+ public BeanSessionArgs mediaType(MediaType mediaType) {
+ this.mediaType = mediaType;
+ return this;
+ }
+
+ @Override /* SessionArgs */
+ public BeanSessionArgs properties(ObjectMap properties) {
+ super.properties(properties);
+ return this;
+ }
}
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/SessionArgs.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/SessionArgs.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/SessionArgs.java
index 17f4e8d..7c26085 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/SessionArgs.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/SessionArgs.java
@@ -22,17 +22,37 @@ public class SessionArgs {
*/
public static final SessionArgs DEFAULT = new SessionArgs(ObjectMap.EMPTY_MAP);
- final ObjectMap properties;
+ ObjectMap properties;
+
+ /**
+ * Constructor.
+ */
+ public SessionArgs() {}
/**
* Constructor.
*
* @param properties
* Session-level properties.
- * These override context-level properties.
- * Can be <jk>null</jk>.
+ * <br>These override context-level properties.
+ * <br>Can be <jk>null</jk>.
*/
public SessionArgs(ObjectMap properties) {
this.properties = properties != null ? properties : ObjectMap.EMPTY_MAP;
}
+
+ /**
+ * Session-level properties.
+ *
+ * @param properties
+ * Session-level properties.
+ * <br>These override context-level properties.
+ * <br>Can be <jk>null</jk>.
+ * @return This object (for method chaining).
+ */
+ public SessionArgs properties(ObjectMap properties) {
+ this.properties = properties != null ? properties : ObjectMap.EMPTY_MAP;
+ return this;
+ }
+
}
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/BeanProperty.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/BeanProperty.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/BeanProperty.java
index ef24e47..d57bb52 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/BeanProperty.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/BeanProperty.java
@@ -57,7 +57,7 @@ public @interface BeanProperty {
* beans.
*
* <p>
- * The following examples show how to define dynamic bean properties.
+ * The following examples show how to define dynamic bean properties.
* <p class='bcode'>
* <jc>// Option #1 - A simple public Map field.
* // The field name can be anything.</jc>
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Swap.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Swap.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Swap.java
index c118b0b..f51f2ce 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Swap.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Swap.java
@@ -66,10 +66,10 @@ public @interface Swap {
* }
* </p>
*
- * <h5 class='section'>Documentation:</h5>
- * <ul>
- * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.PerMediaTypePojoSwaps">Overview > Per-media-type PojoSwaps</a>
- * </ul>
+ * <h5 class='section'>Documentation:</h5>
+ * <ul>
+ * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.PerMediaTypePojoSwaps">Overview > Per-media-type PojoSwaps</a>
+ * </ul>
*/
String[] mediaTypes() default {};
@@ -103,10 +103,10 @@ public @interface Swap {
* <jk>public class</jk> MyPojo {}
* </p>
*
- * <h5 class='section'>Documentation:</h5>
- * <ul>
- * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.TemplatedSwaps">Overview > Templated Swaps</a>
- * </ul>
+ * <h5 class='section'>Documentation:</h5>
+ * <ul>
+ * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.TemplatedSwaps">Overview > Templated Swaps</a>
+ * </ul>
*/
String template() default "";
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializer.java
index abd6e06..13306ad 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializer.java
@@ -79,7 +79,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Aside section contents.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.aside.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -87,7 +87,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Allows you to specify the contents of the aside section on the HTML page.
* The aside section floats on the right of the page for providing content supporting the serialized content of
@@ -116,7 +116,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Footer section contents.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.footer.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -124,7 +124,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Allows you to specify the contents of the footer section on the HTML page.
*
@@ -147,7 +147,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Additional head section content.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.head.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -155,7 +155,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Adds the specified HTML content to the head section of the page.
*
@@ -186,7 +186,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Header section contents.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -194,7 +194,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Allows you to override the contents of the header section on the HTML page.
* The header section normally contains the title and description at the top of the page.
@@ -215,7 +215,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Nav section contents.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.nav.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -223,7 +223,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Allows you to override the contents of the nav section on the HTML page.
* The nav section normally contains the page links at the top of the page.
@@ -247,7 +247,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Page navigation links.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.navlinks.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -255,7 +255,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Adds a list of hyperlinks immediately under the title and description but above the content of the page.
*
@@ -319,7 +319,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: No-results message.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.noResultsMessage.s"</js>
* <li><b>Data type:</b> <code>String</code>
@@ -327,7 +327,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Allows you to specify the string message used when trying to serialize an empty array or empty list.
*
@@ -348,7 +348,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Prevent word wrap on page.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.nowrap.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -356,7 +356,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Adds <js>"* {white-space:nowrap}"</js> to the CSS instructions on the page to prevent word wrapping.
*/
@@ -365,7 +365,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Javascript code.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.script.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -373,7 +373,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Adds the specified Javascript code to the HTML page.
*
@@ -409,7 +409,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: CSS style code.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.style.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -417,7 +417,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Adds the specified CSS instructions to the HTML page.
*
@@ -454,7 +454,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: Stylesheet import URLs.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.stylesheet.ls"</js>
* <li><b>Data type:</b> <code>List<String></code>
@@ -462,7 +462,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Adds a link to the specified stylesheet URL.
*
@@ -479,7 +479,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
/**
* Configuration property: HTML document template.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlDocSerializer.template.c"</js>
* <li><b>Data type:</b> <code>Class<? <jk>extends</jk> HtmlDocTemplate></code>
@@ -487,7 +487,7 @@ public class HtmlDocSerializer extends HtmlStrippedDocSerializer {
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Specifies the template to use for serializing the page.
*
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java
index 3ee1da9..2d8fcfc 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java
@@ -157,8 +157,8 @@ public class HtmlDocSerializerSession extends HtmlStrippedDocSerializerSession {
*
* @return
* The {@link HtmlDocSerializer#HTMLDOC_navlinks} setting value in this context.
- * <jk>null</jk> if not specified.
- * Never an empty map.
+ * <jk>null</jk> if not specified.
+ * Never an empty map.
*/
public final String[] getNavLinks() {
return navlinks;
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializer.java
index 901e252..d46f053 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/html/HtmlSerializer.java
@@ -134,7 +134,7 @@ public class HtmlSerializer extends XmlSerializer {
/**
* Configuration property: Add <js>"_type"</js> properties when needed.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlSerializer.addBeanTypeProperties.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -146,7 +146,7 @@ public class HtmlSerializer extends XmlSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <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
* through reflection.
@@ -163,7 +163,7 @@ public class HtmlSerializer extends XmlSerializer {
/**
* Configuration property: Add key/value headers on bean/map tables.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlSerializer.addKeyValueTableHeaders.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -185,7 +185,7 @@ public class HtmlSerializer extends XmlSerializer {
/**
* Configuration property: Look for URLs in {@link String Strings}.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlSerializer.detectLinksInStrings.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -197,7 +197,7 @@ public class HtmlSerializer extends XmlSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If a string looks like a URL (e.g. starts with <js>"http://"</js> or <js>"https://"</js>, then treat it like a URL
* and make it into a hyperlink based on the rules specified by {@link #HTML_uriAnchorText}.
@@ -207,7 +207,7 @@ public class HtmlSerializer extends XmlSerializer {
/**
* Configuration property: The parameter name to use when using {@link #HTML_lookForLabelParameters}.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlSerializer.labelParameter.s"</js>
* <li><b>Data type:</b> <code>String</code>
@@ -224,7 +224,7 @@ public class HtmlSerializer extends XmlSerializer {
/**
* Configuration property: Look for link labels in the <js>"label"</js> parameter of the URL.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlSerializer.lookForLabelParameters.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -236,7 +236,7 @@ public class HtmlSerializer extends XmlSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If the URL has a label parameter (e.g. <js>"?label=foobar"</js>), then use that as the anchor text of the link.
*
@@ -248,7 +248,7 @@ public class HtmlSerializer extends XmlSerializer {
/**
* Configuration property: Anchor text source.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"HtmlSerializer.uriAnchorText.s"</js>
* <li><b>Data type:</b> <code>String</code> ({@link AnchorText})
@@ -264,7 +264,7 @@ public class HtmlSerializer extends XmlSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* When creating anchor tags (e.g. <code><xt><a</xt> <xa>href</xa>=<xs>'...'</xs>
* <xt>></xt>text<xt></a></xt></code>) in HTML, this setting defines what to set the inner text to.
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/internal/JuneauLogger.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/internal/JuneauLogger.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/internal/JuneauLogger.java
index 51429a4..61c4736 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/internal/JuneauLogger.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/internal/JuneauLogger.java
@@ -80,7 +80,7 @@ public class JuneauLogger extends java.util.logging.Logger {
* The name of the resource bundle.
* Can be any of the following formats:
* <ol>
- * <li>An absolute path. E.g. <js>"com/foo/nls/Messages"</js>.
+ * <li>An absolute path. E.g. <js>"com/foo/nls/Messages"</js>.
* <li>A path relative to the package of the class. E.g. <js>"nls/Messages"</js>.
* </ol>
* Both <js>'.'</js> and <js>'/'</js> can be used as path delimiters.
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializer.java
index 21c0aaf..ef188e6 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/json/JsonSerializer.java
@@ -97,7 +97,7 @@ public class JsonSerializer extends WriterSerializer {
/**
* Configuration property: Add <js>"_type"</js> properties when needed.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"JsonSerializer.addBeanTypeProperties.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -109,7 +109,7 @@ public class JsonSerializer extends WriterSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <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
* through reflection.
@@ -126,7 +126,7 @@ public class JsonSerializer extends WriterSerializer {
/**
* Configuration property: Prefix solidus <js>'/'</js> characters with escapes.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"JsonSerializer.escapeSolidus.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -139,7 +139,7 @@ public class JsonSerializer extends WriterSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, solidus (e.g. slash) characters should be escaped.
* The JSON specification allows for either format.
@@ -151,7 +151,7 @@ public class JsonSerializer extends WriterSerializer {
/**
* Configuration property: Simple JSON mode.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"JsonSerializer.simpleMode.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -164,7 +164,7 @@ public class JsonSerializer extends WriterSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, JSON attribute names will only be quoted when necessary.
* Otherwise, they are always quoted.
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java
index f32cf22..31d3f16 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java
@@ -36,7 +36,7 @@ public class MsgPackSerializer extends OutputStreamSerializer {
/**
* Configuration property: Add <js>"_type"</js> properties when needed.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"MsgPackSerializer.addBeanTypeProperties.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -48,7 +48,7 @@ public class MsgPackSerializer extends OutputStreamSerializer {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <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
* through reflection.
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/package.html
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/package.html b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/package.html
index effb78f..6375f33 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/package.html
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/package.html
@@ -56,182 +56,5 @@
}
</script>
-<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
-<ol class='toc'>
- <li><p><a class='doclink' href='#BeanContext_Api'>Bean Context API</a></p>
- <ol>
- <li><p><a class='doclink' href='#BeanMap'>The BeanMap class</a></p>
- <li><p><a class='doclink' href='#BeanContext'>The BeanContext class</a></p>
- <li><p><a class='doclink' href='#Bean'>Bean annotations</a></p>
- </ol>
-</ol>
-
-<!-- ======================================================================================================== -->
-<a id="BeanContext_Api"></a>
-<h2 class='topic' onclick='toggle(this)'>1 - Bean Context API</h2>
-<div class='topic'>
- <p>
- The {@link org.apache.juneau.BeanContext} class is the core class in the Juneau architecture. It serves
- multiple functions...
- </p>
- <ul class='normal'>
- <li>It provides the ability to create instances of {@link org.apache.juneau.BeanMap BeanMaps}.
- <li>It serves as a repository for {@link org.apache.juneau.transform.BeanFilter BeanFilters} and
- {@link org.apache.juneau.transform.PojoSwap PojoSwaps}, which are used to tailor how Java objects are
- handled.
- <li>It's used by all built-in {@link org.apache.juneau.serializer.Serializer Serializers} and
- {@link org.apache.juneau.parser.Parser Parsers} for working with POJOs in a consistent way.
- </ul>
-
- <!-- ======================================================================================================== -->
- <a id="BeanMap"></a>
- <h3 class='topic' onclick='toggle(this)'>1.1 - The BeanMap class</h3>
- <div class='topic'>
- <p>
- The {@link org.apache.juneau.BeanMap} class allows you to access the properties of a bean through the
- familiar {@code Map} interface.
- So, for example, you can use the {@code Map.get(key)} method to retrieve a property value in lieu of it's
- getter method, and the {@code Map.put(key, value)} method to set a property value in lieu of it's
- setter method.
- </p>
- <p>
- The serialization and parsing of beans in Juneau is accomplished by wrapping Java beans inside instances of
- the class {@code BeanMap}.
- </p>
- <p>
- <b>Note:</b> Instances of {@link org.apache.juneau.BeanMap} objects are always retrieved through the
- {@link org.apache.juneau.BeanContext} class. You cannot instantiate {@code BeanMaps} directly since the
- rules for defining what constitutes a bean depend on various settings in the bean context.
- </p>
- <p>
- In general, the performance on using the {@link org.apache.juneau.BeanMap} class to access properties is
- equivalent to using reflection directly.
- </p>
- <p>
- See the {@link org.apache.juneau.BeanMap} javadoc for more information.
- </p>
- </div>
-
- <!-- ======================================================================================================== -->
- <a id="BeanContext"></a>
- <h3 class='topic' onclick='toggle(this)'>1.2 - The BeanContext and BeanSession classes</h3>
- <div class='topic'>
- <p>
- The {@link org.apache.juneau.BeanContext} and {@link org.apache.juneau.BeanSession} classes are the
- workhorse class used to wrap Java beans inside {@link org.apache.juneau.BeanMap BeanMaps}.
- There are several options provided on the {@link org.apache.juneau.BeanContext} class to tailor the
- definition of a bean.
- </p>
- <p>
- The following is a very simple example of how to wrap a bean inside a {@link org.apache.juneau.BeanMap}
- wrapper and use the wrapper interface to get and set property values on the bean.
- In this case, we're using the DEFAULT bean context.
- </p>
- <p class='bcode'>
- <jc>// A sample pseudo bean class.</jc>
- <jk>public class</jk> Person {
- <jk>public</jk> String getName();
- <jk>public void</jk> setName(String name);
- <jk>public int</jk> getAge();
- <jk>public void</jk> setAge(<jk>int</jk> age);
- }
-
- <jc>// Get an instance of a bean context.
- // In this case, just use the default bean context.</jc>
- BeanSession beanSession = BeanContext.<jsf>DEFAULT</jsf>.createSession();
-
- <jc>// Create an instance of our bean and wrap it in a bean map.</jc>
- Person p = <jk>new</jk> Person();
- BeanMap<Person> m = beanSession.toBeanMap(p);
-
- <jc>// Set some properties on the bean.</jc>
- m.put(<js>"name"</js>, <js>"John Smith"</js>);
- m.put(<js>"age"</js>, 21);
-
- <jc>// Print out bean properties.</jc>
- System.out.println(m.get(<js>"name"</js>)); <jc>// Prints "John Smith"</jc>
- System.out.println(p.getName()); <jc>// Prints "John Smith"</jc>
- System.out.println(m.get(<js>"age"</js>)); <jc>// Prints 21</jc>
- System.out.println(p.getAge()); <jc>// Prints 21</jc>
-
- <jc>// The bean context class can also create instances of bean maps.</jc>
- m = beanContext.newBeanMap(Person.<jk>class</jk>);
- p = m.getBean(); <jc>// Get the new wrapped bean.</jc>
-
- <jc>// The bean context class can also create instances of beans.</jc>
- p = beanContext.newBean(Person.<jk>class</jk>);
- </p>
- <p>
- There are 2 ways to get an instance of a {@link org.apache.juneau.BeanContext}:
- </p>
- <p class='bcode'>
- <jc>// Use one of the default bean contexts.</jc>
- BeanContext beanContext = BeanContext.<jsf>DEFAULT</jsf>;
-
- <jc>// Use the PropertyStore class.</jc>
- beanContext = <jk>new</jk> PropertyStore().pojoSwaps(DateSwap.ISO8601DT.<jk>class</jk>).getBeanContext();
- </p>
- <p>
- The {@link org.apache.juneau.BeanContext} class is a highly-customizable class.
- See the {@link org.apache.juneau.BeanContext} javadoc for more information.
- </p>
- </div>
-
- <!-- ======================================================================================================== -->
- <a id="Bean"></a>
- <h3 class='topic' onclick='toggle(this)'>1.3 - Bean annotations</h3>
- <div class='topic'>
- <p>
- Juneau provides the following annotations that can be used to fine-tune what properties are associated with
- beans:
- </p>
- <ul class='normal'>
- <li>{@link org.apache.juneau.annotation.Bean @Bean} - Fine-tune properties associated with beans.
- <li>{@link org.apache.juneau.annotation.BeanProperty @BeanProperty} - Fine-tune bean properties
- (fields / getters / setters).
- <li>{@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} - Define read-only bean properties that can only
- be set through constructor arguments.
- <li>{@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} - Prevent bean classes/methods/fields from being
- interpreted as bean constructs.
- </ul>
- <p>
- These annotations always override the settings defined in the {@link org.apache.juneau.BeanContext} class.
- </p>
- <p>
- For example, the following bean class will only have one property associated with it, <js>"name"</js>,
- since it's the only one listed in the list of properties.
- </p>
- <p class='bcode'>
- <jc>// Bean with only one 'name' property</jc>
- <ja>@Bean</ja>(properties=<js>"name"</js>)
- <jk>public class</jk> Person {
- <jk>public</jk> String getName();
- <jk>public void</jk> setName(String name);
- <jk>public int</jk> getAge();
- <jk>public void</jk> setAge(<jk>int</jk> age);
- }
- </p>
- <p>
- When this bean is serialized using one of the {@link org.apache.juneau.serializer.Serializer Serializers},
- the age property will be ignored.
- </p>
- <p>
- Using the <ja>@Bean</ja> and <ja>@BeanProperty</ja> annotations, it's also possible to include non-standard
- properties (for example, getters or setters with non-standard names), or override the names of properties
- (for example, {@code "Name"} or {@code "fullName"} instead of {@code "name"}).
- </p>
- <p>
- It should be noted that the {@link org.apache.juneau.transform.BeanFilter} class can also be used to
- exclude properties from beans.
- However, only the annotations can be used to include non-standard properties or override property names.
- </p>
- <p>
- See the {@link org.apache.juneau.annotation.Bean @Bean}, {@link org.apache.juneau.annotation.BeanProperty @BeanProperty},
- {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor}, and {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore}
- javadocs for more information.
- </p>
- </div>
-</div>
-
</body>
</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/Parser.java
----------------------------------------------------------------------
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 a19d7fd..de8900a 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
@@ -14,6 +14,7 @@ package org.apache.juneau.parser;
import java.io.*;
import java.lang.reflect.*;
+import java.nio.charset.*;
import java.util.*;
import org.apache.juneau.*;
@@ -97,7 +98,8 @@ import org.apache.juneau.utils.*;
* following syntax...
* <p class='bcode'>
* Calendar c = parser.parse(<js>"'Sun Mar 03 04:05:06 EST 2001'"</js>, GregorianCalendar.<jk>class</jk>);
- *
+ * </p>
+ *
* <p>
* If <code>Object.<jk>class</jk></code> is specified as the target type, then the parser automatically determines the
* data types and generates the following object types...
@@ -110,26 +112,6 @@ import org.apache.juneau.utils.*;
* <tr><td>boolean</td><td>{@link Boolean}</td></tr>
* <tr><td>string</td><td>{@link String}</td></tr>
* </table>
- *
- * <a id='SupportedTypes'></a>
- * <h6 class='topic'>Supported types</h6>
- *
- * Several of the methods below take {@link Type} parameters to identify the type of object to create.
- * Any of the following types can be passed in to these methods...
- * <ul>
- * <li>{@link ClassMeta}
- * <li>{@link Class}
- * <li>{@link ParameterizedType}
- * <li>{@link GenericArrayType}
- * </ul>
- *
- * <p>
- * However, {@code ParameterizedTypes} and {@code GenericArrayTypes} should not contain
- * {@link WildcardType WildcardTypes} or {@link TypeVariable TypeVariables}.
- *
- * <p>
- * Passing in <jk>null</jk> or <code>Object.<jk>class</jk></code> typically signifies that it's up to the parser
- * to determine what object type is being parsed parsed based on the rules above.
*/
public abstract class Parser extends BeanContext {
@@ -142,7 +124,7 @@ public abstract class Parser extends BeanContext {
/**
* Configuration property: File charset.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Parser.fileCharset.s"</js>
* <li><b>Data type:</b> <code>String</code>
@@ -151,10 +133,11 @@ public abstract class Parser extends BeanContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link ParserBuilder#fileCharset(String)}
+ * <li class='jm'>{@link ParserBuilder#fileCharset(Charset)}
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* The character set to use for reading <code>Files</code> from the file system.
*
@@ -162,14 +145,32 @@ public abstract class Parser extends BeanContext {
* 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.
+ * <js>"DEFAULT"</js> can be used to indicate the JVM default file system charset.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a parser that reads UTF-8 files.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .fileCharset(<js>"UTF-8"</js>)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .set(<jsf>PARSER_fileCharset</jsf>, <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>
*/
public static final String PARSER_fileCharset = PREFIX + "fileCharset.s";
/**
* Configuration property: Input stream charset.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Parser.inputStreamCharset.s"</js>
* <li><b>Data type:</b> <code>String</code>
@@ -178,22 +179,41 @@ public abstract class Parser extends BeanContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link ParserBuilder#inputStreamCharset(String)}
+ * <li class='jm'>{@link ParserBuilder#inputStreamCharset(Charset)}
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* The character set to use for converting <code>InputStreams</code> 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'>
+ * <jc>// Create a parser that reads UTF-8 files.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .inputStreamCharset(<js>"UTF-8"</js>)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .set(<jsf>PARSER_inputStreamCharset</jsf>, <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>
*/
public static final String PARSER_inputStreamCharset = PREFIX + "inputStreamCharset.s";
/**
* Configuration property: Parser listener.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Parser.listener.c"</js>
* <li><b>Data type:</b> <code>Class<? extends ParserListener></code>
@@ -205,16 +225,58 @@ public abstract class Parser extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Class used to listen for errors and warnings that occur during parsing.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <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>// Same, but use property.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .set(<jsf>PARSER_listener</jsf>, 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>
+ * JsonSerializer.<jsf>DEFAULT_LAX</jsf>.println(l.<jf>events</jf>);
+ * }
+ * </p>
*/
public static final String PARSER_listener = PREFIX + "listener.c";
/**
* Configuration property: Strict mode.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Parser.strict.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -227,7 +289,7 @@ public abstract class Parser extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, strict mode for the parser is enabled.
*
@@ -258,13 +320,36 @@ public abstract class Parser extends BeanContext {
* </td>
* </tr>
* </table>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a parser using strict mode.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .strict()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * 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>;
+ * 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>
*/
public static final String PARSER_strict = PREFIX + "strict.b";
/**
* Configuration property: Trim parsed strings.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Parser.trimStrings.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -277,10 +362,30 @@ public abstract class Parser extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <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
* the POJO.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a parser with trim-strings enabled.</jc>
+ * ReaderParser p = JsonParser.
+ * .<jsm>create</jsm>()
+ * .trimStrings()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * 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>));
+ * </p>
*/
public static final String PARSER_trimStrings = PREFIX + "trimStrings.b";
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserBuilder.java
----------------------------------------------------------------------
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 0c5d083..290270d 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
@@ -14,6 +14,7 @@ package org.apache.juneau.parser;
import static org.apache.juneau.parser.Parser.*;
+import java.nio.charset.*;
import java.util.*;
import org.apache.juneau.*;
@@ -65,6 +66,26 @@ public class ParserBuilder extends BeanContextBuilder {
}
/**
+ * Configuration property: File charset.
+ *
+ * <p>
+ * The character set to use for reading <code>Files</code> from the file system.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='jf'>{@link Parser#PARSER_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).
+ */
+ public ParserBuilder fileCharset(Charset value) {
+ return set(PARSER_fileCharset, value);
+ }
+
+ /**
* Configuration property: Input stream charset.
*
* <p>
@@ -85,6 +106,26 @@ public class ParserBuilder extends BeanContextBuilder {
}
/**
+ * Configuration property: Input stream charset.
+ *
+ * <p>
+ * The character set to use for converting <code>InputStreams</code> and byte arrays to readers.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='jf'>{@link Parser#PARSER_inputStreamCharset}
+ * </ul>
+ *
+ * @param value
+ * The new value for this property.
+ * <br>The default value is <js>"UTF-8"</js>.
+ * @return This object (for method chaining).
+ */
+ public ParserBuilder inputStreamCharset(Charset value) {
+ return set(PARSER_inputStreamCharset, value);
+ }
+
+ /**
* Configuration property: Parser listener.
*
* <p>
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSession.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSession.java
index 853cce2..2fa3b2b 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSession.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSession.java
@@ -747,4 +747,24 @@ public abstract class ParserSession extends BeanSession {
m.set(o, name);
}
}
+
+ /**
+ * Returns the listener associated with this session.
+ *
+ * @return The listener associated with this session, or <jk>null</jk> if there is no listener.
+ */
+ public ParserListener getListener() {
+ return listener;
+ }
+
+ /**
+ * Returns the listener associated with this session.
+ *
+ * @param c The listener class to cast to.
+ * @return The listener associated with this session, or <jk>null</jk> if there is no listener.
+ */
+ @SuppressWarnings("unchecked")
+ public <T extends ParserListener> T getListener(Class<T> c) {
+ return (T)listener;
+ }
}
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSessionArgs.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSessionArgs.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSessionArgs.java
index 8e43052..caa16b7 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSessionArgs.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/parser/ParserSessionArgs.java
@@ -23,28 +23,33 @@ import org.apache.juneau.http.*;
*/
public final class ParserSessionArgs extends BeanSessionArgs {
- final Method javaMethod;
- final Object outer;
+ Method javaMethod;
+ Object outer;
+
+ /**
+ * Constructor
+ */
+ public ParserSessionArgs() {}
/**
* Constructor.
*
* @param properties
* Session-level properties.
- * These override context-level properties.
- * Can be <jk>null</jk>.
+ * <br>These override context-level properties.
+ * <br>Can be <jk>null</jk>.
* @param javaMethod
* The java method that called this serializer, usually the method in a REST servlet.
- * Can be <jk>null</jk>.
+ * <br>Can be <jk>null</jk>.
* @param locale
* The session locale.
- * If <jk>null</jk>, then the locale defined on the context is used.
+ * <br>If <jk>null</jk>, then the locale defined on the context is used.
* @param timeZone
* The session timezone.
- * If <jk>null</jk>, then the timezone defined on the context is used.
+ * <br>If <jk>null</jk>, then the timezone defined on the context is used.
* @param mediaType
* The session media type (e.g. <js>"application/json"</js>).
- * Can be <jk>null</jk>.
+ * <br>Can be <jk>null</jk>.
* @param outer
* The outer object for instantiating top-level non-static inner classes.
*/
@@ -53,4 +58,54 @@ public final class ParserSessionArgs extends BeanSessionArgs {
this.javaMethod = javaMethod;
this.outer = outer;
}
+
+
+ /**
+ * The java method that called this serializer, usually the method in a REST servlet.
+ *
+ * @param javaMethod
+ * The java method that called this serializer, usually the method in a REST servlet.
+ * <br>Can be <jk>null</jk>.
+ * @return This object (for method chaining).
+ */
+ public ParserSessionArgs javaMethod(Method javaMethod) {
+ this.javaMethod = javaMethod;
+ return this;
+ }
+
+ /**
+ * The outer object for instantiating top-level non-static inner classes.
+ *
+ * @param outer
+ * The outer object for instantiating top-level non-static inner classes.
+ * @return This object (for method chaining).
+ */
+ public ParserSessionArgs outer(Object outer) {
+ this.outer = outer;
+ return this;
+ }
+
+ @Override /* BeanSessionArgs */
+ public ParserSessionArgs locale(Locale locale) {
+ super.locale(locale);
+ return this;
+ }
+
+ @Override /* BeanSessionArgs */
+ public ParserSessionArgs timeZone(TimeZone timeZone) {
+ super.timeZone(timeZone);
+ return this;
+ }
+
+ @Override /* BeanSessionArgs */
+ public ParserSessionArgs mediaType(MediaType mediaType) {
+ super.mediaType(mediaType);
+ return this;
+ }
+
+ @Override /* SessionArgs */
+ public ParserSessionArgs properties(ObjectMap properties) {
+ super.properties(properties);
+ return this;
+ }
}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/juneau/blob/0ab0b231/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/serializer/Serializer.java
----------------------------------------------------------------------
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 a283aa8..a092a88 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
@@ -17,6 +17,7 @@ import java.io.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.http.*;
+import org.apache.juneau.parser.*;
/**
* Parent class for all Juneau serializers.
@@ -48,7 +49,7 @@ public abstract class Serializer extends BeanContext {
/**
* Configuration property: Abridged output.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.abridged.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -61,21 +62,53 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* When enabled, 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 POJO with a {@link Bean#typeName() @Bean.typeName()} value, a <js>"_type"</js> will be added when
- * this setting is disabled, but not added when it is enabled.
+ * 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>
+ * <li class='jf'>{@link #SERIALIZER_abridged} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #SERIALIZER_addBeanTypeProperties} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that doesn't add _type to root node.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .abridged()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_abridged</jsf>, <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 not contain '_type' attribute even though there's a type name on the bean.</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ *
+ * <jc>// '_type' wasn't needed on the parse side because we know the type being parsed.</jc>
+ * MyBean myBean = JsonParser.<jsf>DEFAULT</jsf>.parse(json, MyBean.<jk>class</jk>);
+ * </p>
*/
public static final String SERIALIZER_abridged = PREFIX + "abridged.b";
/**
* Configuration property: Add <js>"_type"</js> properties when needed.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.addBeanTypeProperties.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -87,22 +120,55 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <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
* through reflection.
*
* <p>
* This is used to recreate the correct objects during parsing if the object types cannot be inferred.
- * For example, when serializing a {@code Map<String,Object>} field, where the bean class cannot be determined from
- * the value type.
+ * <br>For example, when serializing a {@code Map<String,Object>} field where the bean class cannot be determined from
+ * the type of the values.
+ *
+ * <p>
+ * Note the differences between the following settings:
+ * <ul>
+ * <li class='jf'>{@link #SERIALIZER_abridged} - Affects whether <js>'_type'</js> is added to root node.
+ * <li class='jf'>{@link #SERIALIZER_addBeanTypeProperties} - Affects whether <js>'_type'</js> is added to any nodes.
+ * </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .addBeanTypeProperties(<jk>false</jk>)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_addBeanTypeProperties</jsf>, <jk>false</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>// Will not contain '_type' attribute even though type name is on bean and we're serializing</jc>
+ * <jc>// a map of generic objects.</jc>
+ * String json = s.serialize(m);
+ * </p>
*/
public static final String SERIALIZER_addBeanTypeProperties = PREFIX + "addBeanTypeProperties.b";
/**
* Configuration property: Automatically detect POJO recursions.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.detectRecursions.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -115,12 +181,14 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Specifies that recursions should be checked for during serialization.
*
* <p>
- * Recursions can occur when serializing models that aren't true trees, but rather contain loops.
+ * Recursions can occur when serializing 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 ParseException ParseExceptions} with the message <js>"Depth too deep. Stack overflow occurred."</js>.
*
* <p>
* The behavior when recursions are detected depends on the value for {@link #SERIALIZER_ignoreRecursions}.
@@ -128,19 +196,49 @@ public abstract class Serializer extends BeanContext {
* <p>
* For example, if a model contains the links A->B->C->A, then the JSON generated will look like
* the following when <jsf>SERIALIZER_ignoreRecursions</jsf> is <jk>true</jk>...
- * <code>{A:{B:{C:null}}}</code>
+ *
+ * <p class='bcode'>
+ * {A:{B:{C:<jk>null</jk>}}}
+ * </p>
*
* <h5 class='section'>Notes:</h5>
* <ul>
* <li>Checking for recursion can cause a small performance penalty.
* </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that never adds _type to nodes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .detectRecursions()
+ * .ignoreRecursions()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_detectRecursions</jsf>, <jk>true</jk>)
+ * .set(<jsf>SERIALIZER_ignoreRecursions</jsf>, <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 "{f:null}"</jc>
+ * String json = s.serialize(a);
+ * </p>
*/
public static final String SERIALIZER_detectRecursions = PREFIX + "detectRecursions.b";
/**
* Configuration property: Ignore recursion errors.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.ignoreRecursions.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -153,21 +251,21 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Used in conjunction with {@link #SERIALIZER_detectRecursions}.
* <br>Setting is ignored if <jsf>SERIALIZER_detectRecursions</jsf> is <jk>false</jk>.
*
* <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.
+ * <br>Otherwise, a {@link SerializeException} is thrown with the message <js>"Recursion occurred, stack=..."</js>.
*/
public static final String SERIALIZER_ignoreRecursions = PREFIX + "ignoreRecursions.b";
/**
* Configuration property: Initial depth.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.initialDepth.i"</js>
* <li><b>Data type:</b> <code>Integer</code>
@@ -179,17 +277,37 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* The initial indentation level at the root.
- * Useful when constructing document fragments that need to be indented at a certain level.
+ * <br>Useful when constructing document fragments that need to be indented at a certain level.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <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>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_useWhitespace</jsf>, <jk>true</jk>)
+ * .set(<jsf>SERIALIZER_initialDepth</jsf>, 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>
*/
public static final String SERIALIZER_initialDepth = PREFIX + "initialDepth.i";
/**
* Configuration property: Serializer listener.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.listener.c"</js>
* <li><b>Data type:</b> <code>Class<? extends SerializerListener></code>
@@ -201,16 +319,58 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Class used to listen for errors and warnings that occur during serialization.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <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>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer.
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_listener</jsf>, 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>
+ * JsonSerializer.<jsf>DEFAULT_LAX</jsf>.println(l.<jf>events</jf>);
+ * }
+ * </p>
*/
public static final String SERIALIZER_listener = PREFIX + "listener.c";
/**
* Configuration property: Max serialization depth.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.maxDepth.i"</js>
* <li><b>Data type:</b> <code>Integer</code>
@@ -222,18 +382,32 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Abort serialization if specified depth is reached in the POJO tree.
- * If this depth is exceeded, an exception is thrown.
- * This prevents stack overflows from occurring when trying to serialize models with recursive references.
+ * <br>If this depth is exceeded, an exception is thrown.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that throws an exception if the depth is greater than 20.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .maxDepth(20)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_maxDepth</jsf>, 20)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_maxDepth = PREFIX + "maxDepth.i";
/**
* Configuration property: Maximum indentation.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.maxIndent.i"</js>
* <li><b>Data type:</b> <code>Integer</code>
@@ -245,19 +419,34 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Specifies the maximum indentation level in the serialized document.
*
* <p>
* This setting does not apply to the MessagePack or RDF serializers.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that indents a maximum of 20 tabs.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .maxIndent(20)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_maxIndent</jsf>, 20)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_maxIndent = PREFIX + "maxIndent.i";
/**
* Configuration property: Quote character.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.quoteChar.s"</js>
* <li><b>Data type:</b> <code>String</code>
@@ -270,19 +459,34 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* This is the character used for quoting attributes and values.
*
* <p>
* This setting does not apply to the MessagePack or RDF serializers.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that uses single quotes.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sq()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_quoteChar</jsf>, <js>'\''</js>)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_quoteChar = PREFIX + "quoteChar.s";
/**
* Configuration property: Sort arrays and collections alphabetically.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.sortCollections.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -295,20 +499,35 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
*
* <p>
* Copies and sorts the contents of arrays and collections before serializing them.
*
* <p>
* Note that this introduces a performance penalty.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that sorts arrays and collections before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sortCollections()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_sortCollections</jsf>, <jk>true</jk>)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_sortCollections = PREFIX + "sortCollections.b";
/**
* Configuration property: Sort maps alphabetically.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.sortMaps.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -321,20 +540,35 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
*
* <p>
- * Copies and sorts the contents of maps before serializing them.
+ * 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'>
+ * <jc>// Create a serializer that sorts maps before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .sortMaps()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_sortMaps</jsf>, <jk>true</jk>)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_sortMaps = PREFIX + "sortMaps.b";
/**
* Configuration property: Trim empty lists and arrays.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimEmptyCollections.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -347,10 +581,10 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
*
* <p>
- * If <jk>true</jk>, empty list values will not be serialized to the output.
+ * If <jk>true</jk>, empty lists and arrays will not be serialized.
*
* <p>
* Note that enabling this setting has the following effects on parsing:
@@ -360,13 +594,28 @@ public abstract class Serializer extends BeanContext {
* <li>
* Bean properties with empty list values will not be set.
* </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that skips empty arrays and collections.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyCollections()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_trimEmptyCollections</jsf>, <jk>true</jk>)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_trimEmptyCollections = PREFIX + "trimEmptyCollections.b";
/**
* Configuration property: Trim empty maps.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimEmptyMaps.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -379,7 +628,7 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, empty map values will not be serialized to the output.
*
@@ -389,13 +638,28 @@ public abstract class Serializer extends BeanContext {
* <li>
* Bean properties with empty map values will not be set.
* </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that skips empty maps.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimEmptyMaps()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_trimEmptyMaps</jsf>, <jk>true</jk>)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_trimEmptyMaps = PREFIX + "trimEmptyMaps.b";
/**
* Configuration property: Trim null bean property values.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimNullProperties.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -407,7 +671,7 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, null bean values will not be serialized to the output.
*
@@ -417,13 +681,28 @@ public abstract class Serializer extends BeanContext {
* <li>
* Map entries with <jk>null</jk> values will be lost.
* </ul>
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that serializes null properties.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimNullProperties(<jk>false</jk>)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_trimNullProperties</jsf>, <jk>false</jk>)
+ * .build();
+ * </p>
*/
public static final String SERIALIZER_trimNullProperties = PREFIX + "trimNullProperties.b";
/**
* Configuration property: Trim strings.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimStrings.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -436,16 +715,37 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer that trims strings before serialization.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .trimStrings()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_trimStrings</jsf>, <jk>true</jk>)
+ * .build();
+ *
+ * Map<String,String> m = <jk>new</jk> HashMap<>();
+ * m.put(<js>" foo "</js>, <js>" bar "</js>);
+ *
+ * <jc>// Produces "{foo:'bar'}"</jc>
+ * String json = JsonSerializer.<jsf>DEFAULT_LAX</jsf>.toString(m);
+ * </p>
*/
public static final String SERIALIZER_trimStrings = PREFIX + "trimStrings.b";
/**
* Configuration property: URI context bean.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriContext.s"</js>
* <li><b>Data type:</b> <code>String</code> (JSON object representing a {@link UriContext})
@@ -454,24 +754,61 @@ public abstract class Serializer extends BeanContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link SerializerBuilder#uriContext(UriContext)}
+ * <li class='jm'>{@link SerializerBuilder#uriContext(String)}
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* Bean used for resolution of URIs to absolute or root-relative form.
*
- * <h6 class='figure'>Example:</h6>
+ * <h5 class='section'>Example:</h5>
* <p class='bcode'>
- * <js>"{authority:'http://localhost:10000',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/foo'}"</js>
+ * <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(uriContext)
+ * .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>)
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_uriContext</jsf>, uriContext)
+ * .build();
+ *
+ * <jc>// Same, but define it on the session args instead.</jc>
+ * SerializerSessionArgs sessionArgs = <jk>new</jk> SerializerSessionArgs().uriContext(uriContext);
+ * <jk>try</jk> (WriterSerializerSession session = s.createSession(sessionArgs)) {
+ * ...
+ * }
* </p>
+ *
+ * <h5 class='section'>Documentation:</h5>
+ * <ul>
+ * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.URIs">Overview > URIs</a>
+ * </ul>
*/
public static final String SERIALIZER_uriContext = PREFIX + "uriContext.s";
/**
* Configuration property: URI relativity.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriRelativity.s"</js>
* <li><b>Data type:</b> <code>String</code> ({@link UriRelativity})
@@ -480,33 +817,50 @@ public abstract class Serializer extends BeanContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link SerializerBuilder#uriRelativity(UriRelativity)}
+ * <li class='jm'>{@link SerializerBuilder#uriRelativity(String)}
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* 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 annotated with {@link org.apache.juneau.annotation.URI @URI}
+ * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
*
* <p>
* Possible values are:
* <ul>
- * <li>{@link UriRelativity#RESOURCE}
+ * <li class='jf'>{@link UriRelativity#RESOURCE}
* - Relative URIs should be considered relative to the servlet URI.
- * <li>{@link UriRelativity#PATH_INFO}
+ * <li class='jf'>{@link UriRelativity#PATH_INFO}
* - Relative URIs should be considered relative to the request URI.
* </ul>
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <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>
+ *
+ * <h5 class='section'>Documentation:</h5>
+ * <ul>
+ * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.URIs">Overview > URIs</a>
+ * </ul>
*/
public static final String SERIALIZER_uriRelativity = PREFIX + "uriRelativity.s";
/**
* Configuration property: URI resolution.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriResolution.s"</js>
* <li><b>Data type:</b> <code>String</code> ({@link UriResolution})
@@ -515,35 +869,52 @@ public abstract class Serializer extends BeanContext {
* <li><b>Methods:</b>
* <ul>
* <li class='jm'>{@link SerializerBuilder#uriResolution(UriResolution)}
+ * <li class='jm'>{@link SerializerBuilder#uriResolution(String)}
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* 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 annotated with {@link org.apache.juneau.annotation.URI @URI}
+ * <li>Properties and classes annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
*
* <p>
* Possible values are:
* <ul>
- * <li>{@link UriResolution#ABSOLUTE}
+ * <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>{@link UriResolution#ROOT_RELATIVE}
+ * <li class='jf'>{@link UriResolution#ROOT_RELATIVE}
* - Resolve to a root-relative URL (e.g. <js>"/context-root/servlet-path/path-info"</js>).
- * <li>{@link UriResolution#NONE}
+ * <li class='jf'>{@link UriResolution#NONE}
* - Don't do any URL resolution.
* </ul>
+ *
+ * <h6 class='figure'>Example:</h6>
+ * <p class='bcode'>
+ * <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>
+ *
+ * <h5 class='section'>Documentation:</h5>
+ * <ul>
+ * <li><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.URIs">Overview > URIs</a>
+ * </ul>
*/
public static final String SERIALIZER_uriResolution = PREFIX + "uriResolution.s";
/**
* Configuration property: Use whitespace.
*
- * <h5 class='section'>Property:</h5>
+ * <h5 class='section'>Property:</h5>
* <ul>
* <li><b>Name:</b> <js>"Serializer.useWhitespace.b"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -557,12 +928,30 @@ public abstract class Serializer extends BeanContext {
* </ul>
* </ul>
*
- * <h5 class='section'>Description:</h5>
+ * <h5 class='section'>Description:</h5>
* <p>
* If <jk>true</jk>, whitespace is added to the output to improve readability.
*
* <p>
* This setting does not apply to the MessagePack serializer.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Create a serializer with whitespace enabled.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .ws()
+ * .build();
+ *
+ * <jc>// Same, but use property.</jc>
+ * WriterSerializer s = JsonSerializer
+ * .<jsm>create</jsm>()
+ * .set(<jsf>SERIALIZER_useWhitespace</jsf>, <jk>true</jk>)
+ * .build();
+ *
+ * <jc>// Produces "\{\n\t'foo': 'bar'\n\}\n"</jc>
+ * String json = s.serialize(<jk>new</jk> MyBean());
+ * </p>
*/
public static final String SERIALIZER_useWhitespace = PREFIX + "useWhitespace.b";