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 2017/06/28 23:37:24 UTC
[07/11] incubator-juneau git commit: Clean up javadocs
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
index a699b2b..10fb1bb 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerBuilder.java
@@ -53,13 +53,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Max serialization depth.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.maxDepth"</js>
* <li><b>Data type:</b> <code>Integer</code>
* <li><b>Default:</b> <code>100</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Abort serialization if specified depth is reached in the POJO tree.
* If this depth is exceeded, an exception is thrown.
@@ -80,13 +81,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Initial depth.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.initialDepth"</js>
* <li><b>Data type:</b> <code>Integer</code>
* <li><b>Default:</b> <code>0</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The initial indentation level at the root.
* Useful when constructing document fragments that need to be indented at a certain level.
@@ -106,20 +108,24 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Automatically detect POJO recursions.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.detectRecursions"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <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.
+ *
* <p>
* The behavior when recursions are detected depends on the value for
* {@link SerializerContext#SERIALIZER_ignoreRecursions}.
+ *
* <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>...
@@ -141,16 +147,18 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Ignore recursion errors.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.ignoreRecursions"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Used in conjunction with {@link SerializerContext#SERIALIZER_detectRecursions}.
* 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.
@@ -171,13 +179,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Use whitespace.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.useWhitepace"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, newlines and indentation and spaces are added to the output to improve readability.
*
@@ -205,13 +214,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Maximum indentation.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.maxIndent"</js>
* <li><b>Data type:</b> <code>Integer</code>
* <li><b>Default:</b> <code>100</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Specifies the maximum indentation level in the serialized document.
*
@@ -230,13 +240,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Add <js>"_type"</js> properties when needed.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.addBeanTypeProperties"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
* through reflection.
@@ -260,13 +271,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Quote character.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.quoteChar"</js>
* <li><b>Data type:</b> <code>Character</code>
* <li><b>Default:</b> <js>'"'</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* This is the character used for quoting attributes and values.
*
@@ -294,13 +306,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Trim null bean property values.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimNullProperties"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, null bean values will not be serialized to the output.
*
@@ -323,13 +336,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Trim empty lists and arrays.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimEmptyLists"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, empty list values will not be serialized to the output.
*
@@ -353,13 +367,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Trim empty maps.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimEmptyMaps"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, empty map values will not be serialized to the output.
*
@@ -382,13 +397,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Trim strings.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimStrings"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
*
@@ -407,13 +423,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> URI context bean.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriContext"</js>
* <li><b>Data type:</b> {@link UriContext}
* <li><b>Default:</b> {@link UriContext#DEFAULT}
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Bean used for resolution of URIs to absolute or root-relative form.
*
@@ -437,13 +454,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> URI resolution.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriResolution"</js>
* <li><b>Data type:</b> {@link UriResolution}
* <li><b>Default:</b> {@link UriResolution#ROOT_RELATIVE}
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Defines the resolution level for URIs when serializing any of the following:
* <ul>
@@ -451,6 +469,7 @@ public class SerializerBuilder extends CoreObjectBuilder {
* <li>{@link java.net.URL}
* <li>Properties annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
+ *
* <p>
* Possible values are:
* <ul>
@@ -477,13 +496,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> URI relativity.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriRelativity"</js>
* <li><b>Data type:</b> {@link UriRelativity}
* <li><b>Default:</b> {@link UriRelativity#RESOURCE}
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Defines what relative URIs are relative to when serializing any of the following:
* <ul>
@@ -491,6 +511,7 @@ public class SerializerBuilder extends CoreObjectBuilder {
* <li>{@link java.net.URL}
* <li>Properties annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
+ *
* <p>
* Possible values are:
* <ul>
@@ -515,7 +536,7 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Sort arrays and collections alphabetically.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.sortCollections"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -539,7 +560,7 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Sort maps alphabetically.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.sortMaps"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -563,20 +584,21 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Abridged output.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.parserKnowsRootTypes"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <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.
+ * 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()} 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 POJO with a {@link Bean#typeName()} value, a <js>"_type"</js> will be added when
+ * this setting is disabled, but not added when it is enabled.
*
* @param value The new value for this property.
* @return This object (for method chaining).
@@ -588,13 +610,14 @@ public class SerializerBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Serializer listener.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.listener"</js>
* <li><b>Data type:</b> <code>Class<? extends SerializerListener></code>
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Class used to listen for errors and warnings that occur during serialization.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerContext.java b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerContext.java
index 0afd2b4..4ab30cf 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerContext.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerContext.java
@@ -22,13 +22,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Max serialization depth.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.maxDepth"</js>
* <li><b>Data type:</b> <code>Integer</code>
* <li><b>Default:</b> <code>100</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Abort serialization if specified depth is reached in the POJO tree.
* If this depth is exceeded, an exception is thrown.
@@ -38,13 +39,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Initial depth.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.initialDepth"</js>
* <li><b>Data type:</b> <code>Integer</code>
* <li><b>Default:</b> <code>0</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The initial indentation level at the root.
* Useful when constructing document fragments that need to be indented at a certain level.
@@ -53,19 +55,23 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Automatically detect POJO recursions.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.detectRecursions"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <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.
+ *
* <p>
* The behavior when recursions are detected depends on the value for {@link #SERIALIZER_ignoreRecursions}.
+ *
* <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>...
@@ -80,34 +86,37 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Ignore recursion errors.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.ignoreRecursions"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Used in conjunction with {@link #SERIALIZER_detectRecursions}.
* 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>.
+ * 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.
*/
public static final String SERIALIZER_ignoreRecursions = "Serializer.ignoreRecursions";
/**
* <b>Configuration property:</b> Use whitespace.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.useWhitespace"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, whitespace is added to the output to improve readability.
+ *
* <p>
* This setting does not apply to the MessagePack serializer.
*/
@@ -115,15 +124,17 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Maximum indentation.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.maxIndent"</js>
* <li><b>Data type:</b> <code>Integer</code>
* <li><b>Default:</b> <code>100</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Specifies the maximum indentation level in the serialized document.
+ *
* <p>
* This setting does not apply to the MessagePack or RDF serializers.
*/
@@ -131,13 +142,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Add <js>"_type"</js> properties when needed.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.addBeanTypeProperties"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
* through reflection.
@@ -149,15 +161,17 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Quote character.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.quoteChar"</js>
* <li><b>Data type:</b> <code>Character</code>
* <li><b>Default:</b> <js>'"'</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* This is the character used for quoting attributes and values.
+ *
* <p>
* This setting does not apply to the MessagePack or RDF serializers.
*/
@@ -165,15 +179,17 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Trim null bean property values.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimNullProperties"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, null bean values will not be serialized to the output.
+ *
* <p>
* Note that enabling this setting has the following effects on parsing:
* <ul class='spaced-list'>
@@ -185,15 +201,17 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Trim empty lists and arrays.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimEmptyLists"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, empty list values will not be serialized to the output.
+ *
* <p>
* Note that enabling this setting has the following effects on parsing:
* <ul class='spaced-list'>
@@ -207,15 +225,17 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Trim empty maps.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimEmptyMaps"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, 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'>
@@ -227,13 +247,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Trim strings.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.trimStrings"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being serialized.
*/
@@ -241,13 +262,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> URI context bean.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriContext"</js>
* <li><b>Data type:</b> {@link UriContext}
* <li><b>Default:</b> {@link UriContext#DEFAULT}
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Bean used for resolution of URIs to absolute or root-relative form.
*
@@ -260,13 +282,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> URI resolution.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriResolution"</js>
* <li><b>Data type:</b> {@link UriResolution}
* <li><b>Default:</b> {@link UriResolution#NONE}
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Defines the resolution level for URIs when serializing any of the following:
* <ul>
@@ -274,6 +297,7 @@ public class SerializerContext extends BeanContext {
* <li>{@link java.net.URL}
* <li>Properties annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
+ *
* <p>
* Possible values are:
* <ul>
@@ -289,13 +313,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> URI relativity.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.uriRelativity"</js>
* <li><b>Data type:</b> {@link UriRelativity}
* <li><b>Default:</b> {@link UriRelativity#RESOURCE}
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Defines what relative URIs are relative to when serializing any of the following:
* <ul>
@@ -303,6 +328,7 @@ public class SerializerContext extends BeanContext {
* <li>{@link java.net.URL}
* <li>Properties annotated with {@link org.apache.juneau.annotation.URI @URI}
* </ul>
+ *
* <p>
* Possible values are:
* <ul>
@@ -316,13 +342,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Sort arrays and collections alphabetically.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.sortCollections"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Note that this introduces a performance penalty.
*/
@@ -330,13 +357,14 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Sort maps alphabetically.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.sortMaps"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Note that this introduces a performance penalty.
*/
@@ -344,32 +372,34 @@ public class SerializerContext extends BeanContext {
/**
* <b>Configuration property:</b> Abridged output.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.abridged"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <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.
+ * 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()} 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 POJO with a {@link Bean#typeName()} value, a <js>"_type"</js> will be added when
+ * this setting is disabled, but not added when it is enabled.
*/
public static final String SERIALIZER_abridged = "Serializer.abridged";
/**
* <b>Configuration property:</b> Serializer listener.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Serializer.listener"</js>
* <li><b>Data type:</b> <code>Class<? extends SerializerListener></code>
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Class used to listen for errors and warnings that occur during serialization.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroup.java b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
index 2a6d3bb..80fc063 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroup.java
@@ -22,7 +22,7 @@ import org.apache.juneau.http.*;
* Represents a group of {@link Serializer Serializers} that can be looked up by media type.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Provides the following features:
* <ul class='spaced-list'>
* <li>
@@ -36,11 +36,13 @@ import org.apache.juneau.http.*;
* </ul>
*
* <h6 class='topic'>Match ordering</h6>
- * <p>
+ *
* Serializers are matched against <code>Accept</code> strings in the order they exist in this group.
+ *
* <p>
* Adding new entries will cause the entries to be prepended to the group.
* This allows for previous serializers to be overridden through subsequent calls.
+ *
* <p>
* For example, calling <code>g.append(S1.<jk>class</jk>,S2.<jk>class</jk>).append(S3.<jk>class</jk>,S4.<jk>class</jk>)</code>
* will result in the order <code>S3, S4, S1, S2</code>.
@@ -77,11 +79,13 @@ public final class SerializerGroup {
/**
* Constructor.
*
- * @param propertyStore The modifiable properties that were used to initialize the serializers.
- * A snapshot of these will be made so that we can clone and modify this group.
- * @param serializers The serializers defined in this group.
- * The order is important because they will be tried in reverse order (e.g.newer first) in which they will be tried
- * to match against media types.
+ * @param propertyStore
+ * The modifiable properties that were used to initialize the serializers.
+ * A snapshot of these will be made so that we can clone and modify this group.
+ * @param serializers
+ * The serializers defined in this group.
+ * The order is important because they will be tried in reverse order (e.g.newer first) in which they will be tried
+ * to match against media types.
*/
public SerializerGroup(PropertyStore propertyStore, Serializer[] serializers) {
this.propertyStore = PropertyStore.create(propertyStore);
@@ -104,6 +108,7 @@ public final class SerializerGroup {
/**
* Searches the group for a serializer that can handle the specified <code>Accept</code> value.
+ *
* <p>
* The <code>accept</code> value complies with the syntax described in RFC2616, Section 14.1, as described below:
* <p class='bcode'>
@@ -117,6 +122,7 @@ public final class SerializerGroup {
* accept-params = ";" "q" "=" qvalue *( accept-extension )
* accept-extension = ";" token [ "=" ( token | quoted-string ) ]
* </p>
+ *
* <p>
* The general idea behind having the serializer resolution be a two-step process is so that the matched media type
* can be passed in to the {@link WriterSerializer#doSerialize(SerializerSession, Object)} method.
@@ -183,6 +189,7 @@ public final class SerializerGroup {
/**
* Returns the media types that all serializers in this group can handle.
+ *
* <p>
* Entries are ordered in the same order as the serializers in the group.
*
@@ -194,6 +201,8 @@ public final class SerializerGroup {
/**
* Returns a copy of the property store that was used to create the serializers in this group.
+ *
+ * <p>
* This method returns a new factory each time so is somewhat expensive.
*
* @return A new copy of the property store passed in to the constructor.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroupBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroupBuilder.java b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroupBuilder.java
index 9636597..e6992f0 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroupBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerGroupBuilder.java
@@ -40,6 +40,7 @@ public class SerializerGroupBuilder {
/**
* Create an empty serializer group using the specified property store for settings.
+ *
* <p>
* Note: Modifying the specified property store externally will also modify it here.
*
@@ -96,6 +97,7 @@ public class SerializerGroupBuilder {
/**
* Creates a new {@link SerializerGroup} object using a snapshot of the settings defined in this builder.
+ *
* <p>
* This method can be called multiple times to produce multiple serializer groups.
*
@@ -1114,9 +1116,11 @@ public class SerializerGroupBuilder {
/**
* Specifies the classloader to use when resolving classes from strings for all serializers in this group.
+ *
* <p>
* Can be used for resolving class names when the classes being created are in a different classloader from the
* Juneau code.
+ *
* <p>
* If <jk>null</jk>, the system classloader will be used to resolve classes.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerSession.java b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerSession.java
index f75d3c2..f3c03ff 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerSession.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerSession.java
@@ -28,6 +28,7 @@ import org.apache.juneau.transform.*;
/**
* Context object that lives for the duration of a single use of {@link Serializer}.
+ *
* <p>
* Used by serializers for the following purposes:
* <ul class='spaced-list'>
@@ -40,6 +41,7 @@ import org.apache.juneau.transform.*;
* <li>
* Allowing serializer properties to be overridden on method calls.
* </ul>
+ *
* <p>
* This class is NOT thread safe. It is meant to be discarded after one-time use.
*/
@@ -79,30 +81,36 @@ public class SerializerSession extends BeanSession {
/**
* Create a new session using properties specified in the context.
*
- * @param ctx The context creating this session object.
- * The context contains all the configuration settings for this object.
- * @param output The output object.
- * <br>Character-based serializers can handle the following output class types:
- * <ul>
- * <li>{@link Writer}
- * <li>{@link OutputStream} - Output will be written as UTF-8 encoded stream.
- * <li>{@link File} - Output will be written as system-default encoded stream.
- * </ul>
- * <br>Stream-based serializers can handle the following output class types:
- * <ul>
- * <li>{@link OutputStream}
- * <li>{@link File}
- * </ul>
- * @param op The override properties.
- * These override any context properties defined in the context.
+ * @param ctx
+ * The context creating this session object.
+ * The context contains all the configuration settings for this object.
+ * @param output
+ * The output object.
+ * <br>Character-based serializers can handle the following output class types:
+ * <ul>
+ * <li>{@link Writer}
+ * <li>{@link OutputStream} - Output will be written as UTF-8 encoded stream.
+ * <li>{@link File} - Output will be written as system-default encoded stream.
+ * </ul>
+ * <br>Stream-based serializers can handle the following output class types:
+ * <ul>
+ * <li>{@link OutputStream}
+ * <li>{@link File}
+ * </ul>
+ * @param op
+ * The override properties.
+ * These override any context properties defined in the context.
* @param javaMethod The java method that called this serializer, usually the method in a REST servlet.
- * @param locale The session locale.
- * 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.
+ * @param locale
+ * The session locale.
+ * 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.
* @param mediaType The session media type (e.g. <js>"application/json"</js>).
- * @param uriContext The URI context.
- * Identifies the current request URI used for resolution of URIs to absolute or root-relative form.
+ * @param uriContext
+ * The URI context.
+ * Identifies the current request URI used for resolution of URIs to absolute or root-relative form.
*/
public SerializerSession(SerializerContext ctx, ObjectMap op, Object output, Method javaMethod, Locale locale,
TimeZone timeZone, MediaType mediaType, UriContext uriContext) {
@@ -166,7 +174,10 @@ public class SerializerSession extends BeanSession {
/**
* Wraps the specified output object inside an output stream.
+ *
+ * <p>
* Subclasses can override this method to implement their own specialized output streams.
+ *
* <p>
* This method can be used if the output object is any of the following class types:
* <ul>
@@ -193,7 +204,10 @@ public class SerializerSession extends BeanSession {
/**
* Wraps the specified output object inside a writer.
+ *
+ * <p>
* Subclasses can override this method to implement their own specialized writers.
+ *
* <p>
* This method can be used if the output object is any of the following class types:
* <ul>
@@ -252,6 +266,7 @@ public class SerializerSession extends BeanSession {
/**
* Returns the Java method that invoked this serializer.
+ *
* <p>
* When using the REST API, this is the Java method invoked by the REST call.
* Can be used to access annotations defined on the method or class.
@@ -403,8 +418,9 @@ public class SerializerSession extends BeanSession {
* @param attrName The attribute name.
* @param o The current object being serialized.
* @param eType The expected class type.
- * @return The {@link ClassMeta} of the object so that <code>instanceof</code> operations only need to be performed
- * once (since they can be expensive).
+ * @return
+ * The {@link ClassMeta} of the object so that <code>instanceof</code> operations only need to be performed
+ * once (since they can be expensive).
* @throws SerializeException If recursion occurred.
*/
public ClassMeta<?> push(String attrName, Object o, ClassMeta<?> eType) throws SerializeException {
@@ -607,27 +623,28 @@ public class SerializerSession extends BeanSession {
/**
* Converts a String to an absolute URI based on the {@link UriContext} on this session.
*
- * @param uri The input URI.
- * Can be any of the following:
- * <ul>
- * <li>{@link java.net.URI}
- * <li>{@link java.net.URL}
- * <li>{@link CharSequence}
- * </ul>
- * URI can be any of the following forms:
- * <ul>
- * <li><js>"foo://foo"</js> - Absolute URI.
- * <li><js>"/foo"</js> - Root-relative URI.
- * <li><js>"/"</js> - Root URI.
- * <li><js>"context:/foo"</js> - Context-root-relative URI.
- * <li><js>"context:/"</js> - Context-root URI.
- * <li><js>"servlet:/foo"</js> - Servlet-path-relative URI.
- * <li><js>"servlet:/"</js> - Servlet-path URI.
- * <li><js>"request:/foo"</js> - Request-path-relative URI.
- * <li><js>"request:/"</js> - Request-path URI.
- * <li><js>"foo"</js> - Path-info-relative URI.
- * <li><js>""</js> - Path-info URI.
- * </ul>
+ * @param uri
+ * The input URI.
+ * Can be any of the following:
+ * <ul>
+ * <li>{@link java.net.URI}
+ * <li>{@link java.net.URL}
+ * <li>{@link CharSequence}
+ * </ul>
+ * URI can be any of the following forms:
+ * <ul>
+ * <li><js>"foo://foo"</js> - Absolute URI.
+ * <li><js>"/foo"</js> - Root-relative URI.
+ * <li><js>"/"</js> - Root URI.
+ * <li><js>"context:/foo"</js> - Context-root-relative URI.
+ * <li><js>"context:/"</js> - Context-root URI.
+ * <li><js>"servlet:/foo"</js> - Servlet-path-relative URI.
+ * <li><js>"servlet:/"</js> - Servlet-path URI.
+ * <li><js>"request:/foo"</js> - Request-path-relative URI.
+ * <li><js>"request:/"</js> - Request-path URI.
+ * <li><js>"foo"</js> - Path-info-relative URI.
+ * <li><js>""</js> - Path-info URI.
+ * </ul>
* @return The resolved URI.
*/
public String resolveUri(Object uri) {
@@ -636,8 +653,10 @@ public class SerializerSession extends BeanSession {
/**
* Opposite of {@link #resolveUri(Object)}.
+ *
* <p>
* Converts the URI to a value relative to the specified <code>relativeTo</code> parameter.
+ *
* <p>
* Both parameters can be any of the following:
* <ul>
@@ -645,6 +664,8 @@ public class SerializerSession extends BeanSession {
* <li>{@link java.net.URL}
* <li>{@link CharSequence}
* </ul>
+ *
+ * <p>
* Both URIs can be any of the following forms:
* <ul>
* <li><js>"foo://foo"</js> - Absolute URI.
@@ -824,6 +845,7 @@ public class SerializerSession extends BeanSession {
/**
* Returns the parser-side expected type for the object.
+ *
* <p>
* The return value depends on the {@link SerializerContext#SERIALIZER_abridged} setting.
* When enabled, the parser already knows the Java POJO type being parsed, so there is
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerWriter.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerWriter.java b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerWriter.java
index 628fc11..ee4f882 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerWriter.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/SerializerWriter.java
@@ -19,6 +19,7 @@ import org.apache.juneau.*;
/**
* Simple wrapper around a standard {@link Writer} with additional methods.
+ *
* <p>
* Modeled after the Java ProcessBuilder class so that you can chain commands to reduce the need for string
* concatenation for performance reasons.
@@ -50,8 +51,9 @@ public class SerializerWriter extends Writer {
/**
* @param out The writer being wrapped.
- * @param useWhitespace If <jk>true</jk>, calling {@link #cr(int)} will create an indentation and calling
- * {@link #s()} will write a space character.
+ * @param useWhitespace
+ * If <jk>true</jk>, calling {@link #cr(int)} will create an indentation and calling {@link #s()} will write a
+ * space character.
* @param maxIndent The maximum indentation level.
* @param trimStrings If <jk>true</jk>, strings should be trimmed before they're serialized.
* @param quoteChar The character to write when {@link #q()} is called.
@@ -69,6 +71,7 @@ public class SerializerWriter extends Writer {
/**
* Performs a carriage return.
+ *
* <p>
* Adds a newline and the specified number of tabs (if the {@code useWhitespace} setting is enabled) to the output.
*
@@ -84,6 +87,7 @@ public class SerializerWriter extends Writer {
/**
* Performs a carriage return at the end of a line.
+ *
* <p>
* Adds a newline and the specified number of tabs (if the {@code useWhitespace} setting is enabled) to the output.
*
@@ -165,9 +169,11 @@ public class SerializerWriter extends Writer {
/**
* Appends the specified object as a URI.
+ *
* <p>
* Object is converted to a <code>String</code> using <code>toString()</code>, so this will work on {@link URL} or
* {@link URI} objects, or any other type that returns a URI via it's <code>toString()</code> method.
+ *
* <p>
* The URI is resolved based on the {@link SerializerContext#SERIALIZER_uriRelativity} and
* {@link SerializerContext#SERIALIZER_uriResolution} settings and the {@link UriContext} that's part of the
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/WriterSerializer.java b/juneau-core/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
index bb0491f..e80cb58 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/WriterSerializer.java
@@ -25,7 +25,7 @@ import org.apache.juneau.utils.*;
* Subclass of {@link Serializer} for character-based serializers.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* This class is typically the parent class of all character-based serializers.
* It has 2 abstract methods to implement...
* <ul class='spaced-list'>
@@ -36,8 +36,9 @@ import org.apache.juneau.utils.*;
* </ul>
*
* <h6 class='topic'>@Produces annotation</h6>
- * <p>
+ *
* The media types that this serializer can produce is specified through the {@link Produces @Produces} annotation.
+ *
* <p>
* However, the media types can also be specified programmatically by overriding the {@link #getMediaTypes()}
* and {@link #getResponseContentType()} methods.
@@ -78,8 +79,9 @@ public abstract class WriterSerializer extends Serializer {
}
/**
- * Identical to {@link #serialize(Object)} except throws a {@link RuntimeException}
- * instead of a {@link SerializeException}.
+ * Identical to {@link #serialize(Object)} except throws a {@link RuntimeException} instead of a {@link SerializeException}.
+ *
+ * <p>
* This is typically good enough for debugging purposes.
*
* @param o The object to serialize.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializer.java b/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializer.java
index 7ea762b..aa5f6fa 100644
--- a/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializer.java
@@ -23,17 +23,18 @@ import org.apache.juneau.xml.*;
* Serializes POJOs to HTTP responses as XML+SOAP.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/xml+soap</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/xml+soap</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Essentially the same output as {@link XmlDocSerializer}, except wrapped in a standard SOAP envelope.
*
* <h5 class='section'>Configurable properties:</h5>
- * <p>
+ *
* This class has the following properties associated with it:
* <ul>
* <li>{@link SoapXmlSerializerContext}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java b/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
index 74dd512..f3810fc 100644
--- a/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerBuilder.java
@@ -54,7 +54,7 @@ public class SoapXmlSerializerBuilder extends XmlSerializerBuilder {
/**
* <b>Configuration property:</b> The <code>SOAPAction</code> HTTP header value to set on responses.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"SoapXmlSerializer.SOAPAction"</js>
* <li><b>Data type:</b> <code>String</code>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerContext.java b/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerContext.java
index 0746c19..e6eb5d6 100644
--- a/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerContext.java
+++ b/juneau-core/src/main/java/org/apache/juneau/soap/SoapXmlSerializerContext.java
@@ -44,7 +44,7 @@ public final class SoapXmlSerializerContext {
/**
* <b>Configuration property:</b> The <code>SOAPAction</code> HTTP header value to set on responses.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"SoapXmlSerializer.SOAPAction"</js>
* <li><b>Data type:</b> <code>String</code>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/DefaultingVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/DefaultingVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/DefaultingVar.java
index e8674ce..6c2bcd6 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/DefaultingVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/DefaultingVar.java
@@ -16,9 +16,11 @@ import static org.apache.juneau.internal.StringUtils.*;
/**
* Interface for the resolution of vars with a default value if the <code>resolve()</code> method returns <jk>null</jk>.
+ *
* <p>
* For example, to resolve the system property <js>"myProperty"</js> but resolve to <js>"not found"</js> if the
- * property doesn't exist: <js>"$S{myProperty,not found}"</js>
+ * property doesn't exist: <js>"$S{myProperty,not found}"</js>
+ *
* <p>
* Subclasses must implement the {@link #resolve(VarResolverSession, String)} method.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/MultipartVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/MultipartVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/MultipartVar.java
index 43cb6f7..9c3f2d1 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/MultipartVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/MultipartVar.java
@@ -16,6 +16,7 @@ import static org.apache.juneau.internal.StringUtils.*;
/**
* Interface for the resolution of vars that consist of a comma-delimited list.
+ *
* <p>
* (e.g. <js>"$X{foo, bar, baz}"</js>)
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/SimpleVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/SimpleVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/SimpleVar.java
index 9091698..3d926f4 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/SimpleVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/SimpleVar.java
@@ -16,10 +16,12 @@ import java.io.*;
/**
* Abstract superclass of all Simple Var Language variables that resolve to simple returned string values.
+ *
* <p>
* Note the difference between this class and {@link StreamedVar} that streams values to writers.
* Unlike the {@link StreamedVar} class, the returned value from this class can contain nested variables that will be
* recursively resolved by {@link VarResolver}.
+ *
* <p>
* Subclasses must implement the {@link #resolve(VarResolverSession, String)} method.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/StreamedVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/StreamedVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/StreamedVar.java
index 4ab4540..7fc2ead 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/StreamedVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/StreamedVar.java
@@ -14,11 +14,13 @@ package org.apache.juneau.svl;
/**
* Abstract superclass of all Simple Var Language variables that write their values directly to a writer.
+ *
* <p>
* Note the difference between this class and {@link SimpleVar} that returns simple string values.
* Unlike the {@link SimpleVar} class, the output from this class cannot contain nested variables.
* However, this class can be more efficient for variables that produce large amounts of output so that the creation
* of large in-memory strings is avoided.
+ *
* <p>
* Subclasses must implement the {@link #resolveTo(VarResolverSession, java.io.Writer, String)} method.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/Var.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/Var.java b/juneau-core/src/main/java/org/apache/juneau/svl/Var.java
index a68ecaa..7a0b6b9 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/Var.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/Var.java
@@ -18,18 +18,23 @@ import java.io.*;
/**
* Abstract superclass of all Simple Var Language variables.
+ *
* <p>
* Vars are used to convert simple variables of the form <js>"$varName{varKey}"</js> into something else by the
* {@link VarResolver} class.
+ *
* <p>
* Subclasses must implement one of the following two methods:
* <ul>
* <li>{@link #resolve(VarResolverSession,String)} - For simple vars.
* <li>{@link #resolveTo(VarResolverSession,Writer,String)} - For streamed vars.
* </ul>
+ *
+ * <p>
* Subclasses MUST implement a no-arg constructor so that class names can be passed to the
* {@link VarResolverBuilder#vars(Class...)} method.
* They must also be thread safe!
+ *
* <p>
* Two direct abstract subclasses are provided to differentiated between simple and streamed vars:
* <ul>
@@ -48,9 +53,10 @@ public abstract class Var {
* Constructor.
*
* @param name The name of this variable.
- * @param streamed Whether this variable is 'streamed', meaning the {@link #resolveTo(VarResolverSession, Writer,
- * String)} method is implemented.
- * If <jk>false</jk>, then the {@link #resolve(VarResolverSession, String)} method is implemented.
+ * @param streamed
+ * Whether this variable is 'streamed', meaning the {@link #resolveTo(VarResolverSession, Writer, String)} method
+ * is implemented.
+ * If <jk>false</jk>, then the {@link #resolve(VarResolverSession, String)} method is implemented.
*/
public Var(String name, boolean streamed) {
this.name = name;
@@ -68,6 +74,7 @@ public abstract class Var {
/**
* Return the name of this variable.
+ *
* <p>
* For example, the system property variable returns <js>"S"</js> since the format of the variable is
* <js>"$S{system.property}"</js>.
@@ -80,6 +87,8 @@ public abstract class Var {
/**
* The method called from {@link VarResolver}.
+ *
+ * <p>
* Can be overridden to intercept the request and do special handling.
* Default implementation simply calls resolve(String).
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/VarResolver.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolver.java b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolver.java
index f4d8cc9..e7af243 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolver.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolver.java
@@ -21,14 +21,17 @@ import org.apache.juneau.svl.vars.*;
/**
* Utility class for resolving variables of the form <js>"$X{key}"</js> in strings.
+ *
* <p>
* Variables are of the form <code>$X{key}</code>, where <code>X</code> can consist of zero or more ASCII characters.
* <br>The variable key can contain anything, even nested variables that get recursively resolved.
+ *
* <p>
* Variables are defined through the {@link VarResolverBuilder#vars(Class[])} method.
+ *
* <p>
* The {@link Var} interface defines how variables are converted to values.
- * <p>
+ *
* <h5 class='section'>Example:</h5>
* <p class='bcode'>
* <jk>public class</jk> SystemPropertiesVar <jk>extends</jk> SimpleVar {
@@ -52,21 +55,24 @@ import org.apache.juneau.svl.vars.*;
* </p>
*
* <h6 class='topic'>Context objects</h6>
- * <p>
+ *
* Var resolvers can have zero or more context objects associated with them.
+ *
* <p>
* Context objects are arbitrary objects associated with this var resolver, such as a {@link ConfigFile} object.
* They can be any class type.
+ *
* <p>
* Context objects can be retrieved by {@link Var} classes through the
* {@link VarResolverSession#getSessionObject(Class, String)} method.
*
* <h6 class='topic'>Session objects</h6>
- * <p>
+ *
* Session objects are considered more ephemeral than context objects.
* While a context object is unlikely to ever change, a session object may change on every use of the var resolver.
* For example, the server API defines various <code>Var</code> objects that use the <code>RestRequest</code>
* object as a session object for the duration of a single HTTP request.
+ *
* <p>
* Session objects are used by calling the {@link #createSession()} or {@link #createSession(Map)} methods to create
* an instance of a {@link VarResolverSession} object that contains {@link VarResolverSession#resolve(String)}
@@ -74,12 +80,13 @@ import org.apache.juneau.svl.vars.*;
* {@link VarResolver#resolve(String)} and {@link VarResolver#resolveTo(String, Writer)} except that the
* <code>Var</code> objects have access to the session objects through the
* {@link VarResolverSession#getSessionObject(Class, String)} method.
+ *
* <p>
* Session objects are specified through either the {@link #createSession(Map)} method or the
* {@link VarResolverSession#sessionObject(String, Object)} methods.
*
* <h6 class='topic'>Cloning</h6>
- * <p>
+ *
* Var resolvers can be cloned by using the {@link #builder()} method.
* Cloning a resolver will copy it's {@link Var} class names and context objects.
*
@@ -96,7 +103,7 @@ public class VarResolver {
/**
* Default string variable resolver with support for system properties and environment variables:
- * <p>
+ *
* <ul>
* <li><code>$S{key}</code>,<code>$S{key,default}</code> - System properties.
* <li><code>$E{key}</code>,<code>$E{key,default}</code> - Environment variables.
@@ -143,9 +150,10 @@ public class VarResolver {
/**
* Creates a new resolver session with no session objects.
+ *
* <p>
- * Session objects can be associated with the specified session using the
- * {@link VarResolverSession#sessionObject(String, Object)} method.
+ * Session objects can be associated with the specified session using the {@link VarResolverSession#sessionObject(String, Object)}
+ * method.
*
* @return A new resolver session.
*/
@@ -165,6 +173,7 @@ public class VarResolver {
/**
* Resolve variables in the specified string.
+ *
* <p>
* This is a shortcut for calling <code>createSession(<jk>null</jk>).resolve(s);</code>.
* This method can only be used if the string doesn't contain variables that rely on the existence of session
@@ -179,6 +188,7 @@ public class VarResolver {
/**
* Resolve variables in the specified string and sends the results to the specified writer.
+ *
* <p>
* This is a shortcut for calling <code>createSession(<jk>null</jk>).resolveTo(s, w);</code>.
* This method can only be used if the string doesn't contain variables that rely on the existence of session
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverBuilder.java b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverBuilder.java
index f4414dd..915d2e8 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverBuilder.java
@@ -40,8 +40,9 @@ public class VarResolverBuilder {
/**
* Register new variables with this resolver.
*
- * @param vars The variable resolver classes.
- * These classes must subclass from {@link Var} and have no-arg constructors.
+ * @param vars
+ * The variable resolver classes.
+ * These classes must subclass from {@link Var} and have no-arg constructors.
* @return This object (for method chaining).
*/
@SuppressWarnings("unchecked")
@@ -55,6 +56,7 @@ public class VarResolverBuilder {
/**
* Adds the default variables to this builder.
+ *
* <p>
* The default variables are:
* <ul>
@@ -72,6 +74,7 @@ public class VarResolverBuilder {
/**
* Associates a context object with this resolver.
+ *
* <p>
* A context object is essentially some environmental object that doesn't change but is used by vars to customize
* output.
@@ -87,6 +90,7 @@ public class VarResolverBuilder {
/**
* Associates multiple context objects with this resolver.
+ *
* <p>
* A context object is essentially some environmental object that doesn't change but is used by vars to customize
* output.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverContext.java b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverContext.java
index 1f9757d..c39d383 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverContext.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverContext.java
@@ -19,6 +19,7 @@ import java.util.concurrent.*;
/**
* Configurable properties on the {@link VarResolver} class.
+ *
* <p>
* Used to associate {@link Var Vars} and context objects with {@link VarResolver VarResolvers}.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverSession.java b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverSession.java
index ef012e3..0e4b8e1 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverSession.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/VarResolverSession.java
@@ -21,13 +21,17 @@ import org.apache.juneau.*;
/**
* A var resolver session that combines a {@link VarResolver} with one or more session objects.
+ *
* <p>
* Instances of this class are considered light-weight and fast to construct, use, and discard.
+ *
* <p>
* This class contains the workhorse code for var resolution.
+ *
* <p>
* Instances of this class are created through the {@link VarResolver#createSession()} and
* {@link VarResolver#createSession(Map)} methods.
+ *
* <p>
* Instances of this class are NOT guaranteed to be thread safe.
*
@@ -41,8 +45,9 @@ public class VarResolverSession {
/**
* Constructor.
*
- * @param context The {@link VarResolver} context object that contains the {@link Var Vars} and context objects
- * associated with that resolver.
+ * @param context
+ * The {@link VarResolver} context object that contains the {@link Var Vars} and context objects associated with
+ * that resolver.
* @param sessionObjects The session objects.
*
*/
@@ -67,8 +72,9 @@ public class VarResolverSession {
* Resolve all variables in the specified string.
*
* @param s The string to resolve variables in.
- * @return The new string with all variables resolved, or the same string if no variables were found.
- * Null input results in a blank string.
+ * @return
+ * The new string with all variables resolved, or the same string if no variables were found.
+ * Null input results in a blank string.
*/
public String resolve(String s) {
@@ -104,7 +110,7 @@ public class VarResolverSession {
}
}
- /**
+ /*
* Checks to see if string is of the simple form "$X{...}" with no embedded variables.
* This is a common case, and we can avoid using StringWriters.
*/
@@ -144,6 +150,8 @@ public class VarResolverSession {
/**
* Resolves variables in the specified string and sends the output to the specified writer.
+ *
+ * <p>
* More efficient than first parsing to a string and then serializing to the writer since this method doesn't need
* to construct a large string.
*
@@ -259,6 +267,8 @@ public class VarResolverSession {
/**
* Returns the session object with the specified name.
+ *
+ * <p>
* Casts it to the specified class type for you.
*
* @param c The class type to cast to.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/ArgsVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/ArgsVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/ArgsVar.java
index 5597a8b..b5e7fd2 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/ArgsVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/ArgsVar.java
@@ -17,8 +17,10 @@ import org.apache.juneau.utils.*;
/**
* JVM args variable resolver.
+ *
* <p>
* The format for this var is <js>"$ARG{argNameOrNum}"</js> or <js>"$ARG{argNameOrNum,defaultValue}"</js>
+ *
* <p>
* This variable resolver requires that an {@link Args} object be set as a context object on the resolver or a
* session object on the resolver session.
@@ -35,6 +37,7 @@ import org.apache.juneau.utils.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"Arg #1 is set to $ARG{1}"</js>));
* </p>
+ *
* <p>
* Since this is a {@link SimpleVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/ConfigFileVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/ConfigFileVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/ConfigFileVar.java
index 04e704f..d253c6b 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/ConfigFileVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/ConfigFileVar.java
@@ -17,9 +17,11 @@ import org.apache.juneau.svl.*;
/**
* Config file variable resolver.
+ *
* <p>
* The format for this var is <js>"$C{key}"</js> or <js>"$C{key,defaultValue}"</js>.
* See {@link ConfigFile#getString(String)} for the format of the key.
+ *
* <p>
* This variable resolver requires that a {@link ConfigFile} object be set as a context object on the resolver or a
* session object on the resolver session.
@@ -36,6 +38,7 @@ import org.apache.juneau.svl.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"Value for myKey in section MySection is $C{MySection/myKey}"</js>));
* </p>
+ *
* <p>
* Since this is a {@link SimpleVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/EnvVariablesVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/EnvVariablesVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/EnvVariablesVar.java
index ecda3fd..60c0c13 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/EnvVariablesVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/EnvVariablesVar.java
@@ -16,6 +16,7 @@ import org.apache.juneau.svl.*;
/**
* Environment variable variable resolver.
+ *
* <p>
* The format for this var is <js>"$E{envVar}"</js> or <js>"$E{envVar,defaultValue}"</js>
*
@@ -27,6 +28,7 @@ import org.apache.juneau.svl.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"Environment variable PATH is set to $E{PATH}"</js>));
* </p>
+ *
* <p>
* Since this is a {@link SimpleVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/IfVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/IfVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/IfVar.java
index b5600b5..4f7d9b6 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/IfVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/IfVar.java
@@ -18,12 +18,14 @@ import org.apache.juneau.svl.*;
/**
* A basic if-else logic variable resolver.
+ *
* <p>
* The format for this var is one of the following:
* <ul>
* <li><js>"$IF{booleanArg,thenValue}"</js>
* <li><js>"$IF{booleanArg,thenValue,elseValue}"</js>
* </ul>
+ *
* <p>
* The boolean argument is any string.
* <br>The following values are interpreted as <jk>true</jk>: <js>"true"</js>,<js>"TRUE"</js>,<js>"t"</js>,
@@ -38,6 +40,7 @@ import org.apache.juneau.svl.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"Property $IF{$S{someBooleanFlag},IS,IS NOT} set!"</js>));
* </p>
+ *
* <p>
* Since this is a {@link MultipartVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/ManifestFileVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/ManifestFileVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/ManifestFileVar.java
index 35bea2d..18eb086 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/ManifestFileVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/ManifestFileVar.java
@@ -17,8 +17,10 @@ import org.apache.juneau.utils.*;
/**
* Manifest file entries variable resolver.
+ *
* <p>
* The format for this var is <js>"$MF{key}"</js> or <js>"$MF{key,defaultValue}"</js>
+ *
* <p>
* This variable resolver requires that a {@link ManifestFile} object be set as a context object on the resolver or a
* session object on the resolver session.
@@ -35,6 +37,7 @@ import org.apache.juneau.utils.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"The main class is $MF{Main-Class}"</js>));
* </p>
+ *
* <p>
* Since this is a {@link SimpleVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/SwitchVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/SwitchVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/SwitchVar.java
index caa6108..e4f19b9 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/SwitchVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/SwitchVar.java
@@ -20,6 +20,7 @@ import org.apache.juneau.svl.*;
/**
* A basic switch/case logic variable resolver.
+ *
* <p>
* The format for this var is one of the following:
* <ul>
@@ -29,6 +30,7 @@ import org.apache.juneau.svl.*;
* <li><js>"$SWITCH{stringArg,pattern,thenValue,pattern,thenValue,elsePattern}"</js>
* <li>...
* </ul>
+ *
* <p>
* The pattern can be any string optionally containing <js>'*'</js> or <js>'?'</js> representing any or one character
* respectively.
@@ -41,6 +43,7 @@ import org.apache.juneau.svl.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"We are running on $SWITCH{$P{os.name},*win*,Windows,Something else}!"</js>));
* </p>
+ *
* <p>
* Since this is a {@link MultipartVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/svl/vars/SystemPropertiesVar.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/svl/vars/SystemPropertiesVar.java b/juneau-core/src/main/java/org/apache/juneau/svl/vars/SystemPropertiesVar.java
index 7242db4..b151360 100644
--- a/juneau-core/src/main/java/org/apache/juneau/svl/vars/SystemPropertiesVar.java
+++ b/juneau-core/src/main/java/org/apache/juneau/svl/vars/SystemPropertiesVar.java
@@ -16,6 +16,7 @@ import org.apache.juneau.svl.*;
/**
* System property variable resolver.
+ *
* <p>
* The format for this var is <js>"$S{systemProperty}"</js> or <js>"$S{systemProperty,defaultValue}"</js>
*
@@ -27,6 +28,7 @@ import org.apache.juneau.svl.*;
* <jc>// Use it!</jc>
* System.<jsf>out</jsf>.println(r.resolve(<js>"java.home is set to $S{java.home}"</js>));
* </p>
+ *
* <p>
* Since this is a {@link SimpleVar}, any variables contained in the result will be recursively resolved.
* Likewise, if the arguments contain any variables, those will be resolved before they are passed to this var.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/transform/AnnotationBeanFilterBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/transform/AnnotationBeanFilterBuilder.java b/juneau-core/src/main/java/org/apache/juneau/transform/AnnotationBeanFilterBuilder.java
index 5b03cea..7f1d942 100644
--- a/juneau-core/src/main/java/org/apache/juneau/transform/AnnotationBeanFilterBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/transform/AnnotationBeanFilterBuilder.java
@@ -21,6 +21,7 @@ import org.apache.juneau.annotation.*;
/**
* Bean filter builder initialized from the contents of a {@link Bean @Bean} annotation found on a class.
+ *
* <p>
* <b>*** Internal class - Not intended for external use ***</b>
*/
@@ -30,8 +31,8 @@ public final class AnnotationBeanFilterBuilder extends BeanFilterBuilder {
* Constructor.
*
* @param annotatedClass The class found to have a {@link Bean @Bean} annotation.
- * @param annotations The {@link Bean @Bean} annotations found on the class and all parent classes in
- * child-to-parent order.
+ * @param annotations
+ * The {@link Bean @Bean} annotations found on the class and all parent classes in child-to-parent order.
* @throws Exception Thrown from property namer constructor.
*/
public AnnotationBeanFilterBuilder(Class<?> annotatedClass, Map<Class<?>,Bean> annotations) throws Exception {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilter.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilter.java b/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilter.java
index 0cdd606..9a354f0 100644
--- a/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilter.java
+++ b/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilter.java
@@ -19,8 +19,10 @@ import org.apache.juneau.annotation.*;
/**
* Parent class for all bean filters.
+ *
* <p>
* Bean filters are used to control aspects of how beans are handled during serialization and parsing.
+ *
* <p>
* This class can be considered a programmatic equivalent to using the {@link Bean @Bean} annotation on bean classes.
* Thus, it can be used to perform the same function as the <code>@Bean</code> annotation when you don't have
@@ -75,8 +77,9 @@ public class BeanFilter {
/**
* Returns the set and order of names of properties associated with a bean class.
*
- * @return The name of the properties associated with a bean class, or <jk>null</jk> if all bean properties should
- * be used.
+ * @return
+ * The name of the properties associated with a bean class, or <jk>null</jk> if all bean properties should
+ * be used.
*/
public String[] getProperties() {
return properties;
@@ -93,6 +96,7 @@ public class BeanFilter {
/**
* Returns <jk>true</jk> if the properties defined on this bean class should be ordered alphabetically.
+ *
* <p>
* This method is only used when the {@link #getProperties()} method returns <jk>null</jk>.
* Otherwise, the ordering of the properties in the returned value is used.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilterBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilterBuilder.java b/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilterBuilder.java
index 5312693..0c76a44 100644
--- a/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilterBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/transform/BeanFilterBuilder.java
@@ -21,6 +21,7 @@ import org.apache.juneau.*;
/**
* Builder class for {@link BeanFilter} objects.
+ *
* <p>
* Bean filter builders must have a public no-arg constructor.
* Builder settings should be set in the constructor using the provided setters on this class.
@@ -78,6 +79,8 @@ public abstract class BeanFilterBuilder {
/**
* Specifies the set and order of names of properties associated with the bean class.
+ *
+ * <p>
* The order specified is the same order that the entries will be returned by the {@link BeanMap#entrySet()} and
* related methods.
* Entries in the list can also contain comma-delimited lists that will be split.
@@ -103,9 +106,11 @@ public abstract class BeanFilterBuilder {
/**
* Identifies a class to be used as the interface class for this and all subclasses.
+ *
* <p>
* When specified, only the list of properties defined on the interface class will be used during serialization.
* Additional properties on subclasses will be ignored.
+ *
* <p class='bcode'>
* <jc>// Parent class</jc>
* <jk>public abstract class</jk> A {
@@ -130,6 +135,7 @@ public abstract class BeanFilterBuilder {
* String r = s.serialize(a1);
* <jsm>assertEquals</jsm>(<js>"{f0:'f0'}"</js>, r); <jc>// Note f1 is not serialized</jc>
* </p>
+ *
* <p>
* Note that this filter can be used on the parent class so that it filters to all child classes, or can be set
* individually on the child classes.
@@ -144,12 +150,15 @@ public abstract class BeanFilterBuilder {
/**
* Identifies a stop class for this class and all subclasses.
+ *
* <p>
* Identical in purpose to the stop class specified by {@link Introspector#getBeanInfo(Class, Class)}.
* Any properties in the stop class or in its base classes will be ignored during analysis.
+ *
* <p>
* For example, in the following class hierarchy, instances of <code>C3</code> will include property <code>p3</code>,
* but not <code>p1</code> or <code>p2</code>.
+ *
* <p class='bcode'>
* <jk>public class</jk> C1 {
* <jk>public int</jk> getP1();
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/transform/InterfaceBeanFilterBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/transform/InterfaceBeanFilterBuilder.java b/juneau-core/src/main/java/org/apache/juneau/transform/InterfaceBeanFilterBuilder.java
index 64e7d1a..a15522e 100644
--- a/juneau-core/src/main/java/org/apache/juneau/transform/InterfaceBeanFilterBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/transform/InterfaceBeanFilterBuilder.java
@@ -22,6 +22,7 @@ import org.apache.juneau.internal.*;
/**
* Simple bean filter that simply identifies a class to be used as an interface class for all child classes.
+ *
* <p>
* These objects are created when you pass in non-<code>BeanFilterBuilder</code> classes to
* {@link PropertyStore#addToProperty(String,Object)}, and are equivalent to adding a
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/transform/PojoSwap.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/transform/PojoSwap.java b/juneau-core/src/main/java/org/apache/juneau/transform/PojoSwap.java
index 14e89ee..51dec68 100644
--- a/juneau-core/src/main/java/org/apache/juneau/transform/PojoSwap.java
+++ b/juneau-core/src/main/java/org/apache/juneau/transform/PojoSwap.java
@@ -24,20 +24,23 @@ import org.apache.juneau.serializer.*;
* Used to swap out non-serializable objects with serializable replacements during serialization, and vis-versa during parsing.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* <code>PojoSwaps</code> are used to extend the functionality of the serializers and parsers to be able to handle
* POJOs that aren't automatically handled by the serializers or parsers. For example, JSON does not have a standard
* representation for rendering dates.
* By defining a special {@code Date} swap and associating it with a serializer and parser, you can convert a
* {@code Date} object to a {@code String} during serialization, and convert that {@code String} object back into a
* {@code Date} object during parsing.
+ *
* <p>
* Swaps MUST declare a public no-arg constructor so that the bean context can instantiate them.
+ *
* <p>
* <code>PojoSwaps</code> are associated with instances of {@link BeanContext BeanContexts} by passing the swap
* class to the {@link CoreObjectBuilder#pojoSwaps(Class...)} method.
* <br>When associated with a bean context, fields of the specified type will automatically be converted when the
* {@link BeanMap#get(Object)} or {@link BeanMap#put(String, Object)} methods are called.
+ *
* <p>
* <code>PojoSwaps</code> have two parameters:
* <ol>
@@ -50,7 +53,7 @@ import org.apache.juneau.serializer.*;
* {@link BeanMap#put(String,Object)}.
*
* <h6 class='topic'>Subtypes</h6>
- * <p>
+ *
* The following abstract subclasses are provided for common swap types:
* <ol>
* <li>{@link StringSwap} - Objects swapped with strings.
@@ -58,7 +61,7 @@ import org.apache.juneau.serializer.*;
* </ol>
*
* <h6 class='topic'>Localization</h6>
- * <p>
+ *
* Swaps have access to the session locale and timezone through the {@link BeanSession#getLocale()} and
* {@link BeanSession#getTimeZone()} methods.
* This allows you to specify localized swap values when needed.
@@ -66,7 +69,7 @@ import org.apache.juneau.serializer.*;
* <code>Time-Zone</code> headers on the request.
*
* <h6 class='topic'>Swap Class Type {@code <S>}</h6>
- * <p>
+ *
* The swapped object representation of an object must be an object type that the serializers can natively convert to
* JSON (or language-specific equivalent).
* The list of valid transformed types are as follows...
@@ -88,11 +91,11 @@ import org.apache.juneau.serializer.*;
* </ul>
*
* <h6 class='topic'>Normal Class Type {@code <T>}</h6>
- * <p>
+ *
* The normal object representation of an object.
*
* <h6 class='topic'>One-way vs. Two-way Serialization</h6>
- * <p>
+ *
* Note that while there is a unified interface for handling swaps during both serialization and parsing,
* in many cases only one of the {@link #swap(BeanSession, Object)} or {@link #unswap(BeanSession, Object, ClassMeta)}
* methods will be defined because the swap is one-way.
@@ -105,6 +108,7 @@ import org.apache.juneau.serializer.*;
* {@code Date} from just the JSON or XML text.
*
* <h5 class='section'>Additional information:</h5>
+ *
* See <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.transform</a> for more information.
*
* @param <T> The normal form of the class.
@@ -144,6 +148,7 @@ public abstract class PojoSwap<T,S> {
/**
* If this transform is to be used to serialize non-serializable POJOs, it must implement this method.
+ *
* <p>
* The object must be converted into one of the following serializable types:
* <ul class='spaced-list'>
@@ -163,8 +168,9 @@ public abstract class PojoSwap<T,S> {
* An array of anything on this list.
* </ul>
*
- * @param session The bean session to use to get the class meta.
- * This is always going to be the same bean context that created this swap.
+ * @param session
+ * The bean session to use to get the class meta.
+ * This is always going to be the same bean context that created this swap.
* @param o The object to be transformed.
* @return The transformed object.
* @throws SerializeException If a problem occurred trying to convert the output.
@@ -176,12 +182,15 @@ public abstract class PojoSwap<T,S> {
/**
* If this transform is to be used to reconstitute POJOs that aren't true Java beans, it must implement this method.
*
- * @param session The bean session to use to get the class meta.
- * This is always going to be the same bean context that created this swap.
+ * @param session
+ * The bean session to use to get the class meta.
+ * This is always going to be the same bean context that created this swap.
* @param f The transformed object.
- * @param hint If possible, the parser will try to tell you the object type being created. For example,
- * on a serialized date, this may tell you that the object being created must be of type {@code GregorianCalendar}.
- * <br>This may be <jk>null</jk> if the parser cannot make this determination.
+ * @param hint
+ * If possible, the parser will try to tell you the object type being created.
+ * For example, on a serialized date, this may tell you that the object being created must be of type
+ * {@code GregorianCalendar}.
+ * <br>This may be <jk>null</jk> if the parser cannot make this determination.
* @return The narrowed object.
* @throws ParseException If this method is not implemented.
*/
@@ -200,6 +209,7 @@ public abstract class PojoSwap<T,S> {
/**
* Returns the G class, the generalized form of the class.
+ *
* <p>
* Subclasses must override this method if the generalized class is {@code Object}, meaning it can produce multiple
* generalized forms.
@@ -212,10 +222,13 @@ public abstract class PojoSwap<T,S> {
/**
* Returns the {@link ClassMeta} of the transformed class type.
+ *
+ * <p>
* This value is cached for quick lookup.
*
- * @param beanContext The bean context to use to get the class meta.
- * This is always going to be the same bean context that created this swap.
+ * @param beanContext
+ * The bean context to use to get the class meta.
+ * This is always going to be the same bean context that created this swap.
* @return The {@link ClassMeta} of the transformed class type.
*/
public ClassMeta<?> getSwapClassMeta(BeanContext beanContext) {
@@ -228,8 +241,9 @@ public abstract class PojoSwap<T,S> {
* Checks if the specified object is an instance of the normal class defined on this swap.
*
* @param o The object to check.
- * @return <jk>true</jk> if the specified object is a subclass of the normal class defined on this transform.
- * <jk>null</jk> always return <jk>false</jk>.
+ * @return
+ * <jk>true</jk> if the specified object is a subclass of the normal class defined on this transform.
+ * <jk>null</jk> always return <jk>false</jk>.
*/
public boolean isNormalObject(Object o) {
if (o == null)
@@ -241,8 +255,9 @@ public abstract class PojoSwap<T,S> {
* Checks if the specified object is an instance of the swap class defined on this swap.
*
* @param o The object to check.
- * @return <jk>true</jk> if the specified object is a subclass of the transformed class defined on this transform.
- * <jk>null</jk> always return <jk>false</jk>.
+ * @return
+ * <jk>true</jk> if the specified object is a subclass of the transformed class defined on this transform.
+ * <jk>null</jk> always return <jk>false</jk>.
*/
public boolean isSwappedObject(Object o) {
if (o == null)
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/transform/SurrogateSwap.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/transform/SurrogateSwap.java b/juneau-core/src/main/java/org/apache/juneau/transform/SurrogateSwap.java
index 69f3dfe..fa8b57f 100644
--- a/juneau-core/src/main/java/org/apache/juneau/transform/SurrogateSwap.java
+++ b/juneau-core/src/main/java/org/apache/juneau/transform/SurrogateSwap.java
@@ -22,9 +22,11 @@ import org.apache.juneau.serializer.*;
/**
* Specialized {@link PojoSwap} for surrogate classes.
+ *
* <p>
* Surrogate classes are used in place of other classes during serialization.
* For example, you may want to use a surrogate class to change the names or order of bean properties on a bean.
+ *
* <p>
* The following is an example of a surrogate class change changes a property name:
* <p class='bcode'>
@@ -36,6 +38,7 @@ import org.apache.juneau.serializer.*;
* }
* }
* </p>
+ *
* <p>
* Optionally, a public static method can be used to un-transform a class during parsing:
* <p class='bcode'>
@@ -46,6 +49,7 @@ import org.apache.juneau.serializer.*;
* }
* }
* </p>
+ *
* <p>
* Surrogate classes must conform to the following:
* <ul class='spaced-list'>
@@ -63,6 +67,7 @@ import org.apache.juneau.serializer.*;
* transformed class can be instantiated by the parser before being converted into the normal class by the
* un-transform method).
* </ul>
+ *
* <p>
* Surrogate classes are associated with serializers and parsers using the {@link CoreObjectBuilder#pojoSwaps(Class...)}
* method.
@@ -112,6 +117,7 @@ import org.apache.juneau.serializer.*;
* }
* }
* </p>
+ *
* <p>
* It should be noted that a surrogate class is functionally equivalent to the following {@link PojoSwap}
* implementation:
@@ -149,6 +155,8 @@ public class SurrogateSwap<T,F> extends PojoSwap<T,F> {
/**
* Given the specified surrogate class, return the list of POJO swaps.
+ *
+ * <p>
* A transform is returned for each public 1-arg constructor found.
* Returns an empty list if no public 1-arg constructors are found.
*