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. *
