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:25 UTC
[08/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/parser/Parser.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/Parser.java b/juneau-core/src/main/java/org/apache/juneau/parser/Parser.java
index 22a4a5b..c28dbf9 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/Parser.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/Parser.java
@@ -30,14 +30,17 @@ import org.apache.juneau.utils.*;
* Parent class for all Juneau parsers.
*
* <h6 class='topic'>@Consumes annotation</h6>
- * <p>
+ *
* The media types that this parser can handle is specified through the {@link Consumes @Consumes} annotation.
+ *
* <p>
* However, the media types can also be specified programmatically by overriding the {@link #getMediaTypes()} method.
*
* <h6 class='topic'>Valid data conversions</h6>
+ *
* Parsers can parse any parsable POJO types, as specified in the <a class="doclink"
* href="../../../../overview-summary.html#Core.PojoCategories">POJO Categories</a>.
+ *
* <p>
* Some examples of conversions are shown below...
* </p>
@@ -92,9 +95,11 @@ import org.apache.juneau.utils.*;
* <td class='code'>String, StringBuilder</td>
* </tr>
* </table>
+ *
* <p>
* In addition, any class types with {@link PojoSwap PojoSwaps} associated with them on the registered
- * {@link #getBeanContext() beanContext} can also be passed in.
+ * {@link #getBeanContext() beanContext} can also be passed in.
+ *
* <p>
* For example, if the {@link CalendarSwap} transform is used to generalize {@code Calendar} objects to {@code String}
* objects.
@@ -102,10 +107,10 @@ import org.apache.juneau.utils.*;
* following syntax...
* <p class='bcode'>
* Calendar c = parser.parse(<js>"'Sun Mar 03 04:05:06 EST 2001'"</js>, GregorianCalendar.<jk>class</jk>);
+ *
* <p>
* If <code>Object.<jk>class</jk></code> is specified as the target type, then the parser automatically determines the
* data types and generates the following object types...
- * </p>
* <table class='styled'>
* <tr><th>JSON type</th><th>Class type</th></tr>
* <tr><td>object</td><td>{@link ObjectMap}</td></tr>
@@ -118,19 +123,20 @@ import org.apache.juneau.utils.*;
*
* <a id='SupportedTypes'></a>
* <h6 class='topic'>Supported types</h6>
- * <p>
+ *
* Several of the methods below take {@link Type} parameters to identify the type of object to create.
* Any of the following types can be passed in to these methods...
- * </p>
* <ul>
* <li>{@link ClassMeta}
* <li>{@link Class}
* <li>{@link ParameterizedType}
* <li>{@link GenericArrayType}
* </ul>
+ *
* <p>
* However, {@code ParameterizedTypes} and {@code GenericArrayTypes} should not contain
* {@link WildcardType WildcardTypes} or {@link TypeVariable TypeVariables}.
+ *
* <p>
* Passing in <jk>null</jk> or <code>Object.<jk>class</jk></code> typically signifies that it's up to the parser
* to determine what object type is being parsed parsed based on the rules above.
@@ -169,13 +175,15 @@ public abstract class Parser extends CoreObject {
/**
* Workhorse method. Subclasses are expected to implement this method.
*
- * @param session The runtime session object returned by {@link #createSession(Object, ObjectMap, Method, Object,
- * Locale, TimeZone, MediaType)}.
- * If <jk>null</jk>, one will be created using {@link #createSession(Object)}.
- * @param type The class type of the object to create.
- * If <jk>null</jk> or <code>Object.<jk>class</jk></code>, object type is based on what's being parsed.
- * For example, when parsing JSON text, it may return a <code>String</code>, <code>Number</code>,
- * <code>ObjectMap</code>, etc...
+ * @param session
+ * The runtime session object returned by {@link #createSession(Object, ObjectMap, Method, Object,
+ * Locale, TimeZone, MediaType)}.
+ * If <jk>null</jk>, one will be created using {@link #createSession(Object)}.
+ * @param type
+ * The class type of the object to create.
+ * If <jk>null</jk> or <code>Object.<jk>class</jk></code>, object type is based on what's being parsed.
+ * For example, when parsing JSON text, it may return a <code>String</code>, <code>Number</code>,
+ * <code>ObjectMap</code>, etc...
* @param <T> The class type of the object to create.
* @return The parsed object.
* @throws Exception If thrown from underlying stream, or if the input contains a syntax error or is malformed.
@@ -195,17 +203,19 @@ public abstract class Parser extends CoreObject {
/**
* Entry point for all parsing calls.
+ *
* <p>
- * Calls the {@link #doParse(ParserSession, ClassMeta)} implementation class and catches/rewraps any exceptions
+ * Calls the {@link #doParse(ParserSession, ClassMeta)} implementation class and catches/re-wraps any exceptions
* thrown.
*
- * @param session The runtime session returned by {@link #createSession(Object, ObjectMap, Method, Object, Locale,
- * TimeZone, MediaType)}.
+ * @param session
+ * The runtime session returned by {@link #createSession(Object, ObjectMap, Method, Object, Locale,
+ * TimeZone, MediaType)}.
* @param type The class type of the object to create.
* @param <T> The class type of the object to create.
* @return The parsed object.
- * @throws ParseException If the input contains a syntax error or is malformed, or is not valid for the specified
- * type.
+ * @throws ParseException
+ * If the input contains a syntax error or is malformed, or is not valid for the specified type.
*/
public final <T> T parseSession(ParserSession session, ClassMeta<T> type) throws ParseException {
try {
@@ -229,6 +239,8 @@ public abstract class Parser extends CoreObject {
/**
* Parses input into the specified object type.
+ *
+ * <p>
* The type can be a simple type (e.g. beans, strings, numbers) or parameterized type (collections/maps).
*
* <h5 class='section'>Examples:</h5>
@@ -250,10 +262,13 @@ public abstract class Parser extends CoreObject {
* <jc>// Parse into a map containing string keys and values of lists containing beans.</jc>
* Map m = p.parse(json, TreeMap.<jk>class</jk>, String.<jk>class</jk>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
* </p>
+ *
* <p>
* <code>Collection</code> classes are assumed to be followed by zero or one objects indicating the element type.
+ *
* <p>
* <code>Map</code> classes are assumed to be followed by zero or two meta objects indicating the key and value types.
+ *
* <p>
* The array can be arbitrarily long to indicate arbitrarily complex data structures.
*
@@ -263,38 +278,39 @@ public abstract class Parser extends CoreObject {
* </ul>
*
* @param <T> The class type of the object to create.
- * @param input The input.
- * <br>
- * Character-based parsers can handle the following input class types:
- * <ul>
- * <li><jk>null</jk>
- * <li>{@link Reader}
- * <li>{@link CharSequence}
- * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by
- * {@link ParserContext#PARSER_inputStreamCharset} property value).
- * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by
- * {@link ParserContext#PARSER_inputStreamCharset} property value).
- * <li>{@link File} containing system encoded text (or charset defined by
- * {@link ParserContext#PARSER_fileCharset} property value).
- * </ul>
- * <br>
- * Stream-based parsers can handle the following input class types:
- * <ul>
- * <li><jk>null</jk>
- * <li>{@link InputStream}
- * <li><code><jk>byte</jk>[]</code>
- * <li>{@link File}
- * </ul>
- * @param type The object type to create.
- * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType},
- * {@link GenericArrayType}
- * @param args The type arguments of the class if it's a collection or map.
- * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType},
- * {@link GenericArrayType}
- * <br>Ignored if the main type is not a map or collection.
+ * @param input
+ * The input.
+ * <br>Character-based parsers can handle the following input class types:
+ * <ul>
+ * <li><jk>null</jk>
+ * <li>{@link Reader}
+ * <li>{@link CharSequence}
+ * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by
+ * {@link ParserContext#PARSER_inputStreamCharset} property value).
+ * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by
+ * {@link ParserContext#PARSER_inputStreamCharset} property value).
+ * <li>{@link File} containing system encoded text (or charset defined by
+ * {@link ParserContext#PARSER_fileCharset} property value).
+ * </ul>
+ * <br>Stream-based parsers can handle the following input class types:
+ * <ul>
+ * <li><jk>null</jk>
+ * <li>{@link InputStream}
+ * <li><code><jk>byte</jk>[]</code>
+ * <li>{@link File}
+ * </ul>
+ * @param type
+ * The object type to create.
+ * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType},
+ * {@link GenericArrayType}
+ * @param args
+ * The type arguments of the class if it's a collection or map.
+ * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType},
+ * {@link GenericArrayType}
+ * <br>Ignored if the main type is not a map or collection.
* @return The parsed object.
- * @throws ParseException If the input contains a syntax error or is malformed, or is not valid for the specified
- * type.
+ * @throws ParseException
+ * If the input contains a syntax error or is malformed, or is not valid for the specified type.
* @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
*/
@SuppressWarnings("unchecked")
@@ -305,6 +321,7 @@ public abstract class Parser extends CoreObject {
/**
* Same as {@link #parse(Object, Type, Type...)} except optimized for a non-parameterized class.
+ *
* <p>
* This is the preferred parse method for simple types since you don't need to cast the results.
*
@@ -329,12 +346,13 @@ public abstract class Parser extends CoreObject {
* </p>
*
* @param <T> The class type of the object being created.
- * @param input The input.
- * See {@link #parse(Object, Type, Type...)} for details.
+ * @param input
+ * The input.
+ * See {@link #parse(Object, Type, Type...)} for details.
* @param type The object type to create.
* @return The parsed object.
- * @throws ParseException If the input contains a syntax error or is malformed, or is not valid for the specified
- * type.
+ * @throws ParseException
+ * If the input contains a syntax error or is malformed, or is not valid for the specified type.
*/
public final <T> T parse(Object input, Class<T> type) throws ParseException {
ParserSession session = createSession(input);
@@ -344,16 +362,18 @@ public abstract class Parser extends CoreObject {
/**
* Same as {@link #parse(Object, Type, Type...)} except the type has already been converted into a {@link ClassMeta}
* object.
+ *
* <p>
* This is mostly an internal method used by the framework.
*
* @param <T> The class type of the object being created.
- * @param input The input.
- * See {@link #parse(Object, Type, Type...)} for details.
+ * @param input
+ * The input.
+ * See {@link #parse(Object, Type, Type...)} for details.
* @param type The object type to create.
* @return The parsed object.
- * @throws ParseException If the input contains a syntax error or is malformed, or is not valid for the specified
- * type.
+ * @throws ParseException
+ * If the input contains a syntax error or is malformed, or is not valid for the specified type.
*/
public final <T> T parse(Object input, ClassMeta<T> type) throws ParseException {
return parseSession(createSession(input), type);
@@ -361,20 +381,26 @@ public abstract class Parser extends CoreObject {
/**
* Create the session object that will be passed in to the parse method.
+ *
* <p>
* It's up to implementers to decide what the session object looks like, although typically it's going to be a
* subclass of {@link ParserSession}.
*
- * @param input The input. See {@link #parse(Object, ClassMeta)} for supported input types.
+ * @param input
+ * The input.
+ * See {@link #parse(Object, ClassMeta)} for supported input types.
* @param op Optional additional properties.
- * @param javaMethod Java method that invoked this parser.
- * 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.
+ * @param javaMethod
+ * Java method that invoked this parser.
+ * 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.
* @param outer The outer object for instantiating top-level non-static inner classes.
- * @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>).
* @return The new session.
*/
@@ -385,6 +411,7 @@ public abstract class Parser extends CoreObject {
/**
* Create a basic session object without overriding properties or specifying <code>javaMethod</code>.
+ *
* <p>
* Equivalent to calling <code>createSession(<jk>null</jk>, <jk>null</jk>)</code>.
*
@@ -402,8 +429,10 @@ public abstract class Parser extends CoreObject {
/**
* Parses the contents of the specified reader and loads the results into the specified map.
+ *
* <p>
* Reader must contain something that serializes to a map (such as text containing a JSON object).
+ *
* <p>
* Used in the following locations:
* <ul class='spaced-list'>
@@ -437,11 +466,14 @@ public abstract class Parser extends CoreObject {
/**
* Implementation method.
+ *
+ * <p>
* Default implementation throws an {@link UnsupportedOperationException}.
*
- * @param session The runtime session object returned by
- * {@link #createSession(Object, ObjectMap, Method, Object, Locale, TimeZone, MediaType)}.
- * If <jk>null</jk>, one will be created using {@link #createSession(Object)}.
+ * @param session
+ * The runtime session object returned by
+ * {@link #createSession(Object, ObjectMap, Method, Object, Locale, TimeZone, MediaType)}.
+ * If <jk>null</jk>, one will be created using {@link #createSession(Object)}.
* @param m The map being loaded.
* @param keyType The class type of the keys, or <jk>null</jk> to default to <code>String.<jk>class</jk></code>.
* @param valueType The class type of the values, or <jk>null</jk> to default to whatever is being parsed.
@@ -454,6 +486,7 @@ public abstract class Parser extends CoreObject {
/**
* Parses the contents of the specified reader and loads the results into the specified collection.
+ *
* <p>
* Used in the following locations:
* <ul class='spaced-list'>
@@ -467,8 +500,8 @@ public abstract class Parser extends CoreObject {
* @param c The collection being loaded.
* @param elementType The class type of the elements, or <jk>null</jk> to default to whatever is being parsed.
* @return The same collection that was passed in to allow this method to be chained.
- * @throws ParseException If the input contains a syntax error or is malformed, or is not valid for the specified
- * type.
+ * @throws ParseException
+ * If the input contains a syntax error or is malformed, or is not valid for the specified type.
* @throws UnsupportedOperationException If not implemented.
*/
public final <E> Collection<E> parseIntoCollection(Object input, Collection<E> c, Type elementType)
@@ -487,11 +520,14 @@ public abstract class Parser extends CoreObject {
/**
* Implementation method.
+ *
+ * <p>
* Default implementation throws an {@link UnsupportedOperationException}.
*
- * @param session The runtime session object returned by {@link #createSession(Object, ObjectMap, Method, Object,
- * Locale, TimeZone, MediaType)}.
- * If <jk>null</jk>, one will be created using {@link #createSession(Object)}.
+ * @param session
+ * The runtime session object returned by {@link #createSession(Object, ObjectMap, Method, Object,
+ * Locale, TimeZone, MediaType)}.
+ * If <jk>null</jk>, one will be created using {@link #createSession(Object)}.
* @param c The collection being loaded.
* @param elementType The class type of the elements, or <jk>null</jk> to default to whatever is being parsed.
* @return The same collection that was passed in to allow this method to be chained.
@@ -504,9 +540,11 @@ public abstract class Parser extends CoreObject {
/**
* Parses the specified array input with each entry in the object defined by the {@code argTypes}
* argument.
+ *
* <p>
* Used for converting arrays (e.g. <js>"[arg1,arg2,...]"</js>) into an {@code Object[]} that can be passed
* to the {@code Method.invoke(target, args)} method.
+ *
* <p>
* Used in the following locations:
* <ul class='spaced-list'>
@@ -517,8 +555,8 @@ public abstract class Parser extends CoreObject {
* @param input The input. Subclasses can support different input types.
* @param argTypes Specifies the type of objects to create for each entry in the array.
* @return An array of parsed objects.
- * @throws ParseException If the input contains a syntax error or is malformed, or is not valid for the specified
- * type.
+ * @throws ParseException
+ * If the input contains a syntax error or is malformed, or is not valid for the specified type.
*/
public final Object[] parseArgs(Object input, Type[] argTypes) throws ParseException {
if (argTypes == null || argTypes.length == 0)
@@ -544,8 +582,9 @@ public abstract class Parser extends CoreObject {
* Converts the specified string to the specified type.
*
* @param session The session object.
- * @param outer The outer object if we're converting to an inner object that needs to be created within the context
- * of an outer object.
+ * @param outer
+ * The outer object if we're converting to an inner object that needs to be created within the context
+ * of an outer object.
* @param s The string to convert.
* @param type The class type to convert the string to.
* @return The string converted as an object of the specified type.
@@ -618,6 +657,7 @@ public abstract class Parser extends CoreObject {
/**
* Returns the media types handled based on the value of the {@link Consumes} annotation on the parser class.
+ *
* <p>
* This method can be overridden by subclasses to determine the media types programmatically.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/ParserBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserBuilder.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserBuilder.java
index 0f61126..d0369c6 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserBuilder.java
@@ -53,13 +53,14 @@ public class ParserBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Trim parsed strings.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.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 added to
* the POJO.
@@ -79,18 +80,20 @@ public class ParserBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Strict mode.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.strict"</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>, strict mode for the parser is enabled.
+ *
* <p>
* Strict mode can mean different things for different parsers.
- * <p>
+ *
* <table class='styled'>
* <tr><th>Parser class</th><th>Strict behavior</th></tr>
* <tr>
@@ -140,15 +143,17 @@ public class ParserBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Input stream charset.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.inputStreamCharset"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"UTF-8"</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The character set to use for converting <code>InputStreams</code> and byte arrays to readers.
+ *
* <p>
* Used when passing in input streams and byte arrays to {@link Parser#parse(Object, Class)}.
*
@@ -167,17 +172,20 @@ public class ParserBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> File charset.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.fileCharset"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"default"</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The character set to use for reading <code>Files</code> from the file system.
+ *
* <p>
* Used when passing in files to {@link Parser#parse(Object, Class)}.
+ *
* <p>
* <js>"default"</js> can be used to indicate the JVM default file system charset.
*
@@ -196,13 +204,14 @@ public class ParserBuilder extends CoreObjectBuilder {
/**
* <b>Configuration property:</b> Parser listener.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.listener"</js>
* <li><b>Data type:</b> <code>Class<? extends ParserListener></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 parsing.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/ParserContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserContext.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserContext.java
index 47d2384..e8fd4b7 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserContext.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserContext.java
@@ -22,13 +22,14 @@ public class ParserContext extends BeanContext {
/**
* <b>Configuration property:</b> Trim parsed strings.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.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 added to
* the POJO.
@@ -37,7 +38,7 @@ public class ParserContext extends BeanContext {
/**
* <b>Configuration property:</b> Strict mode.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.strict"</js>
* <li><b>Data type:</b> <code>Boolean</code>
@@ -46,10 +47,10 @@ public class ParserContext extends BeanContext {
* </ul>
* <p>
* If <jk>true</jk>, strict mode for the parser is enabled.
+ *
* <p>
* Strict mode can mean different things for different parsers.
- * However, all reader-based parsers will
- * <p>
+ *
* <table class='styled'>
* <tr><th>Parser class</th><th>Strict behavior</th></tr>
* <tr>
@@ -79,15 +80,17 @@ public class ParserContext extends BeanContext {
/**
* <b>Configuration property:</b> Input stream charset.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.inputStreamCharset"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"UTF-8"</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The character set to use for converting <code>InputStreams</code> and byte arrays to readers.
+ *
* <p>
* Used when passing in input streams and byte arrays to {@link Parser#parse(Object, Class)}.
*/
@@ -95,17 +98,20 @@ public class ParserContext extends BeanContext {
/**
* <b>Configuration property:</b> File charset.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.fileCharset"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"default"</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The character set to use for reading <code>Files</code> from the file system.
+ *
* <p>
* Used when passing in files to {@link Parser#parse(Object, Class)}.
+ *
* <p>
* <js>"default"</js> can be used to indicate the JVM default file system charset.
*/
@@ -113,13 +119,14 @@ public class ParserContext extends BeanContext {
/**
* <b>Configuration property:</b> Parser listener.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"Parser.listener"</js>
* <li><b>Data type:</b> <code>Class<? extends ParserListener></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 parsing.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroup.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroup.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroup.java
index f429b6f..1a1a258 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroup.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroup.java
@@ -22,7 +22,7 @@ import org.apache.juneau.http.*;
* Represents a group of {@link Parser Parsers} 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>
+ *
* Parsers are matched against <code>Content-Type</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 parsers to be overridden through subsequent calls.
+ *
* <p>
* For example, calling <code>g.append(P1.<jk>class</jk>,P2.<jk>class</jk>).append(P3.<jk>class</jk>,P4.<jk>class</jk>)</code>
* will result in the order <code>P3, P4, P1, P2</code>.
@@ -81,11 +83,13 @@ public final class ParserGroup {
/**
* Constructor.
*
- * @param propertyStore The modifiable properties that were used to initialize the parsers.
- * A snapshot of these will be made so that we can clone and modify this group.
- * @param parsers The parsers 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 parsers.
+ * A snapshot of these will be made so that we can clone and modify this group.
+ * @param parsers
+ * The parsers 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 ParserGroup(PropertyStore propertyStore, Parser[] parsers) {
this.propertyStore = PropertyStore.create(propertyStore);
@@ -161,6 +165,7 @@ public final class ParserGroup {
/**
* Returns the media types that all parsers in this group can handle
+ *
* <p>
* Entries are ordered in the same order as the parsers in the group.
*
@@ -172,6 +177,8 @@ public final class ParserGroup {
/**
* Returns a copy of the property store that was used to create the parsers 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/parser/ParserGroupBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroupBuilder.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroupBuilder.java
index 27335a6..8bed46a 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroupBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserGroupBuilder.java
@@ -40,6 +40,7 @@ public class ParserGroupBuilder {
/**
* Create an empty parser 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 ParserGroupBuilder {
/**
* Creates a new {@link ParserGroup} object using a snapshot of the settings defined in this builder.
+ *
* <p>
* This method can be called multiple times to produce multiple parser groups.
*
@@ -870,9 +872,11 @@ public class ParserGroupBuilder {
/**
* Specifies the classloader to use when resolving classes from strings for all parsers 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.
+ * 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/parser/ParserListener.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserListener.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserListener.java
index a870043..75d39bb 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserListener.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserListener.java
@@ -23,21 +23,23 @@ public class ParserListener {
/**
* Gets called when an unknown bean property is detected in a document.
+ *
* <p>
* This method only gets called if {@link BeanContext#BEAN_ignoreUnknownBeanProperties} setting is <jk>true</jk>.
* Otherwise, the parser will throw a {@link ParseException}.
*
* @param <T> The class type of the bean.
- * @param session The parser session.
- * Note that if {@link BeanContext#BEAN_debug} is enabled on the parser, you can get the input as a string through
- * {@link ParserSession#getInputAsString()}.
+ * @param session
+ * The parser session.
+ * Note that if {@link BeanContext#BEAN_debug} is enabled on the parser, you can get the input as a string through
+ * {@link ParserSession#getInputAsString()}.
* @param propertyName The property name encountered in the document.
* @param beanClass The bean class.
* @param bean The bean.
- * @param line The line number where the unknown property was found (-1 if parser doesn't support line/column
- * indicators).
- * @param col The column number where the unknown property was found (-1 if parser doesn't support line/column
- * indicators).
+ * @param line
+ * The line number where the unknown property was found (-1 if parser doesn't support line/column indicators).
+ * @param col
+ * The column number where the unknown property was found (-1 if parser doesn't support line/column indicators).
*/
public <T> void onUnknownBeanProperty(ParserSession session, String propertyName, Class<T> beanClass, T bean, int line, int col) {
onError(session, null,
@@ -50,8 +52,8 @@ public class ParserListener {
* Called when an error occurs during parsing but is ignored.
*
* @param session The parsers session.
- * Note that if {@link BeanContext#BEAN_debug} is enabled on the parser, you can get the input as a string through
- * {@link ParserSession#getInputAsString()}.
+ * Note that if {@link BeanContext#BEAN_debug} is enabled on the parser, you can get the input as a string through
+ * {@link ParserSession#getInputAsString()}.
* @param t The throwable that was thrown by the getter method.
* @param msg The error message.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/ParserReader.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserReader.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserReader.java
index c15e65f..daa1593 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserReader.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserReader.java
@@ -18,11 +18,14 @@ import org.apache.juneau.internal.*;
/**
* Similar to a {@link java.io.PushbackReader} with a pushback buffer of 1 character.
+ *
* <p>
* Code is optimized to work with a 1 character buffer.
+ *
* <p>
- * Additionally keeps track of current line and column number, and provides the ability to set
- * mark points and capture characters from the previous mark point.
+ * Additionally keeps track of current line and column number, and provides the ability to set mark points and capture
+ * characters from the previous mark point.
+ *
* <p>
* <b>Warning:</b> Not thread safe.
*/
@@ -87,6 +90,8 @@ public class ParserReader extends Reader {
/**
* Reads a single character.
+ *
+ * <p>
* Note that this method does NOT process extended unicode characters (i.e. characters above 0x10000), but rather
* returns them as two <jk>char</jk>s.
* Use {@link #readCodePoint()} to ensure proper handling of extended unicode.
@@ -207,16 +212,15 @@ public class ParserReader extends Reader {
}
/**
- * Start buffering the calls to read() so that the text can be gathered from the mark
- * point on calling {@code getFromMarked()}.
+ * Start buffering the calls to read() so that the text can be gathered from the mark point on calling {@code getFromMarked()}.
*/
public final void mark() {
iMark = iCurrent;
}
-
/**
* Peeks the next character in the stream.
+ *
* <p>
* This is equivalent to doing a {@code read()} followed by an {@code unread()}.
*
@@ -232,6 +236,7 @@ public class ParserReader extends Reader {
/**
* Same as {@link #peek()} but skips over any whitespace characters.
+ *
* <p>
* This is equivalent to doing a {@code read()} followed by an {@code unread()}.
*
@@ -292,8 +297,7 @@ public class ParserReader extends Reader {
}
/**
- * Returns the contents of the reusable character buffer as a string, and
- * resets the buffer for next usage.
+ * Returns the contents of the reusable character buffer as a string, and resets the buffer for next usage.
*
* @return The contents of the reusable character buffer as a string.
*/
@@ -302,11 +306,10 @@ public class ParserReader extends Reader {
}
/**
- * Same as {@link #getMarked()} except allows you to specify offsets
- * into the buffer.
+ * Same as {@link #getMarked()} except allows you to specify offsets into the buffer.
+ *
* <p>
- * For example, to return the marked string, but trim the first and last characters,
- * call the following:
+ * For example, to return the marked string, but trim the first and last characters, call the following:
* <p class='bcode'>
* getFromMarked(1, -1);
* </p>
@@ -337,6 +340,8 @@ public class ParserReader extends Reader {
/**
* Trims off the last character in the marking buffer.
+ *
+ * <p>
* Useful for removing escape characters from sequences.
*
* @return This object (for method chaining).
@@ -361,6 +366,8 @@ public class ParserReader extends Reader {
/**
* Replaces the last character in the marking buffer with the specified character.
+ *
+ * <p>
* <code>offset</code> must be at least <code>1</code> for normal characters, and <code>2</code> for extended
* unicode characters in order for the replacement to fit into the buffer.
*
@@ -402,6 +409,8 @@ public class ParserReader extends Reader {
/**
* Subclasses can override this method to provide additional filtering.
+ *
+ * <p>
* Default implementation simply calls the same method on the underlying reader.
*/
@Override /* Reader */
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/ParserSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ParserSession.java b/juneau-core/src/main/java/org/apache/juneau/parser/ParserSession.java
index 40d6114..9265799 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ParserSession.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ParserSession.java
@@ -27,6 +27,7 @@ import org.apache.juneau.http.*;
/**
* Session object that lives for the duration of a single use of {@link Parser}.
+ *
* <p>
* This class is NOT thread safe. It is meant to be discarded after one-time use.
*/
@@ -48,37 +49,41 @@ public class ParserSession 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 input The input.
- * <br>For character-based parsers, this can be any of the following types:
- * <ul>
- * <li><jk>null</jk>
- * <li>{@link Reader}
- * <li>{@link CharSequence}
- * <li>{@link InputStream} containing UTF-8 encoded text (or whatever the encoding specified by
- * {@link ParserContext#PARSER_inputStreamCharset}).
- * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or whatever the encoding specified by
- * {@link ParserContext#PARSER_inputStreamCharset}).
- * <li>{@link File} containing system encoded text (or whatever the encoding specified by
- * {@link ParserContext#PARSER_fileCharset}).
- * </ul>
- * <br>For byte-based parsers, this can be any of the following types:
- * <ul>
- * <li><jk>null</jk>
- * <li>{@link InputStream}
- * <li><code><jk>byte</jk>[]</code>
- * <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 input
+ * The input.
+ * <br>For character-based parsers, this can be any of the following types:
+ * <ul>
+ * <li><jk>null</jk>
+ * <li>{@link Reader}
+ * <li>{@link CharSequence}
+ * <li>{@link InputStream} containing UTF-8 encoded text (or whatever the encoding specified by
+ * {@link ParserContext#PARSER_inputStreamCharset}).
+ * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or whatever the encoding specified by
+ * {@link ParserContext#PARSER_inputStreamCharset}).
+ * <li>{@link File} containing system encoded text (or whatever the encoding specified by
+ * {@link ParserContext#PARSER_fileCharset}).
+ * </ul>
+ * <br>For byte-based parsers, this can be any of the following types:
+ * <ul>
+ * <li><jk>null</jk>
+ * <li>{@link InputStream}
+ * <li><code><jk>byte</jk>[]</code>
+ * <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 parser, usually the method in a REST servlet.
* @param outer The outer object for instantiating top-level non-static inner classes.
- * @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>).
*/
public ParserSession(ParserContext ctx, ObjectMap op, Object input, Method javaMethod, Object outer, Locale locale,
@@ -106,6 +111,8 @@ public class ParserSession extends BeanSession {
/**
* Wraps the specified input object inside an input stream.
+ *
+ * <p>
* Subclasses can override this method to implement their own input streams.
*
* @return The input object wrapped in an input stream, or <jk>null</jk> if the object is null.
@@ -150,6 +157,8 @@ public class ParserSession extends BeanSession {
/**
* Wraps the specified input object inside a reader.
+ *
+ * <p>
* Subclasses can override this method to implement their own readers.
*
* @return The input object wrapped in a Reader, or <jk>null</jk> if the object is null.
@@ -248,6 +257,7 @@ public class ParserSession extends BeanSession {
/**
* Returns the Java method that invoked this parser.
+ *
* <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.
@@ -260,6 +270,8 @@ public class ParserSession extends BeanSession {
/**
* Returns the outer object used for instantiating top-level non-static member classes.
+ *
+ * <p>
* When using the REST API, this is the servlet object.
*
* @return The outer object.
@@ -336,8 +348,8 @@ public class ParserSession extends BeanSession {
* @param m The map to convert to a bean.
* @param pMeta The current bean property being parsed.
* @param eType The current expected type being parsed.
- * @return The converted bean, or the same map if the <js>"_type"</js> entry wasn't found or didn't resolve to a
- * bean.
+ * @return
+ * The converted bean, or the same map if the <js>"_type"</js> entry wasn't found or didn't resolve to a bean.
*/
public final Object cast(ObjectMap m, BeanPropertyMeta pMeta, ClassMeta<?> eType) {
@@ -407,8 +419,9 @@ public class ParserSession extends BeanSession {
* @param beanMap The bean that doesn't have the expected property.
* @param line The line number where the property was found. <code>-1</code> if line numbers are not available.
* @param col The column number where the property was found. <code>-1</code> if column numbers are not available.
- * @throws ParseException Automatically thrown if {@link BeanContext#BEAN_ignoreUnknownBeanProperties} setting
- * on this parser is <jk>false</jk>
+ * @throws ParseException
+ * Automatically thrown if {@link BeanContext#BEAN_ignoreUnknownBeanProperties} setting on this parser is
+ * <jk>false</jk>
* @param <T> The class type of the bean map that doesn't have the expected property.
*/
public <T> void onUnknownProperty(String propertyName, BeanMap<T> beanMap, int line, int col) throws ParseException {
@@ -425,6 +438,7 @@ public class ParserSession extends BeanSession {
/**
* Returns the input to this parser as a plain string.
+ *
* <p>
* This method only returns a value if {@link BeanContext#BEAN_debug} is enabled.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/PartParser.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/PartParser.java b/juneau-core/src/main/java/org/apache/juneau/parser/PartParser.java
index d50d62c..76844a4 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/PartParser.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/PartParser.java
@@ -16,13 +16,14 @@ import org.apache.juneau.*;
import org.apache.juneau.urlencoding.*;
/**
- * Interface used to convert HTTP headers, query parameters, form-data parameters, and URI
- * path variables to POJOs
+ * Interface used to convert HTTP headers, query parameters, form-data parameters, and URI path variables to POJOs
+ *
* <p>
- * By default, the {@link UrlEncodingParser} class implements this interface so that it can be used to parse
- * these HTTP parts.
+ * By default, the {@link UrlEncodingParser} class implements this interface so that it can be used to parse these HTTP
+ * parts.
* However, the interface is provided to allow custom parsing of these objects by providing your own implementation
* class.
+ *
* <p>
* Implementations must include a no-arg constructor.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/parser/ReaderParser.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/ReaderParser.java b/juneau-core/src/main/java/org/apache/juneau/parser/ReaderParser.java
index 39aa2b3..9d9c710 100644
--- a/juneau-core/src/main/java/org/apache/juneau/parser/ReaderParser.java
+++ b/juneau-core/src/main/java/org/apache/juneau/parser/ReaderParser.java
@@ -19,7 +19,7 @@ import org.apache.juneau.annotation.*;
* Subclass of {@link Parser} for characters-based parsers.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* This class is typically the parent class of all character-based parsers.
* It has 1 abstract method to implement...
* <ul>
@@ -27,8 +27,9 @@ import org.apache.juneau.annotation.*;
* </ul>
*
* <h6 class='topic'>@Consumes annotation</h6>
- * <p>
+ *
* The media types that this parser can handle is specified through the {@link Consumes @Consumes} annotation.
+ *
* <p>
* However, the media types can also be specified programmatically by overriding the {@link #getMediaTypes()} method.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextParser.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextParser.java b/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextParser.java
index c0cc95c..c25c2a0 100644
--- a/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextParser.java
+++ b/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextParser.java
@@ -20,25 +20,27 @@ import org.apache.juneau.parser.*;
import org.apache.juneau.transform.*;
/**
- * Parsers HTTP plain text request bodies into <a class="doclink"
- * href="../../../../overview-summary.html#Core.PojoCategories">Group 5</a> POJOs.
+ * Parsers HTTP plain text request bodies into <a class="doclink" href="../../../../overview-summary.html#Core.PojoCategories">Group 5</a>
+ * POJOs.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/plain</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/plain</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Essentially just converts plain text to POJOs via static <code>fromString()</code> or <code>valueOf()</code>, or
* through constructors that take a single string argument.
+ *
* <p>
* Also parses objects using a transform if the object class has an {@link PojoSwap PojoSwap<?,String>} transform
* defined on it.
*
* <h5 class='section'>Configurable properties:</h5>
- * <p>
+ *
* This class has the following properties associated with it:
* <ul>
* <li>{@link ParserContext}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextSerializer.java b/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextSerializer.java
index 4f9dd12..2dd95b6 100644
--- a/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/plaintext/PlainTextSerializer.java
@@ -21,20 +21,22 @@ import org.apache.juneau.transform.*;
* Serializes POJOs to plain text using just the <code>toString()</code> method on the serialized object.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/plain</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/plain</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Essentially converts POJOs to plain text using the <code>toString()</code> method.
+ *
* <p>
* Also serializes objects using a transform if the object class has an {@link PojoSwap PojoSwap<?,String>}
* transform defined on it.
*
* <h5 class='section'>Configurable properties:</h5>
- * <p>
+ *
* This class has the following properties associated with it:
* <ul>
* <li>{@link SerializerContext}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/Body.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/Body.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/Body.java
index 5dd7b25..1fd6673 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/Body.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/Body.java
@@ -21,8 +21,7 @@ import java.lang.annotation.*;
import org.apache.juneau.serializer.*;
/**
- * Annotation applied to Java method arguments of interface proxies to denote that they are the HTTP body of the
- * request.
+ * Annotation applied to Java method arguments of interface proxies to denote that they are the HTTP body of the request.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode'>
@@ -33,6 +32,7 @@ import org.apache.juneau.serializer.*;
* String myProxyMethod(<ja>@Body</ja> MyPojo pojo);
* }
* </p>
+ *
* <p>
* The argument can be any of the following types:
* <ul class='spaced-list'>
@@ -48,6 +48,7 @@ import org.apache.juneau.serializer.*;
* <li>
* <code>NameValuePairs</code> - Converted to a URL-encoded FORM post.
* </ul>
+ *
* <p>
* The annotation can also be applied to a bean property field or getter when the argument is annotated with
* {@link RequestBean @RequestBean}:
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/FormData.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/FormData.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/FormData.java
index 7f7f6e3..4a5fbb4 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/FormData.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/FormData.java
@@ -62,6 +62,7 @@ import org.apache.juneau.urlencoding.*;
*
* }
* </p>
+ *
* <p>
* The annotation can also be applied to a bean property field or getter when the argument is annotated with
* {@link RequestBean @RequestBean}:
@@ -113,12 +114,11 @@ import org.apache.juneau.urlencoding.*;
* Reader getReader();
* }
* </p>
+ *
* <p>
* The {@link #name()} and {@link #value()} elements are synonyms for specifying the parameter name.
* Only one should be used.
- * <br>
- * The following annotations are fully equivalent:
- * <p>
+ * <br>The following annotations are fully equivalent:
* <p class='bcode'>
* <ja>@FormData</ja>(name=<js>"foo"</js>)
*
@@ -141,11 +141,14 @@ public @interface FormData {
/**
* The form post parameter name.
+ *
* <p>
* Note that {@link #name()} and {@link #value()} are synonyms.
+ *
* <p>
* The value should be either <js>"*"</js> to represent multiple name/value pairs, or a label that defines the
* form data parameter name.
+ *
* <p>
* A blank value (the default) has the following behavior:
* <ul class='spaced-list'>
@@ -192,6 +195,7 @@ public @interface FormData {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
@@ -199,6 +203,7 @@ public @interface FormData {
/**
* Skips this value if it's an empty string or empty collection/array.
+ *
* <p>
* Note that <jk>null</jk> values are already ignored.
*/
@@ -206,9 +211,11 @@ public @interface FormData {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/FormDataIfNE.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/FormDataIfNE.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/FormDataIfNE.java
index 36849d2..91a1171 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/FormDataIfNE.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/FormDataIfNE.java
@@ -53,9 +53,11 @@ public @interface FormDataIfNE {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/Header.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/Header.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/Header.java
index e7c4f18..751cc0f 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/Header.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/Header.java
@@ -51,6 +51,7 @@ import org.apache.juneau.urlencoding.*;
* String myProxyMethod4(<ja>@Header</ja> MyBean myBean);
* }
* </p>
+ *
* <p>
* The annotation can also be applied to a bean property field or getter when the argument is annotated with
* {@link RequestBean @RequestBean}:
@@ -97,11 +98,11 @@ import org.apache.juneau.urlencoding.*;
* MyBean getBean();
* }
* </p>
+ *
* <p>
* The {@link #name()} and {@link #value()} elements are synonyms for specifying the header name.
* Only one should be used.
* <br>The following annotations are fully equivalent:
- * <p>
* <p class='bcode'>
* <ja>@Header</ja>(name=<js>"Foo"</js>)
*
@@ -124,11 +125,14 @@ public @interface Header {
/**
* The HTTP header name.
+ *
* <p>
* A blank value (the default) indicates to reuse the bean property name when used on a request bean property.
+ *
* <p>
* The value should be either <js>"*"</js> to represent multiple name/value pairs, or a label that defines the
* header name.
+ *
* <p>
* A blank value (the default) has the following behavior:
* <ul class='spaced-list'>
@@ -176,6 +180,7 @@ public @interface Header {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
@@ -183,6 +188,7 @@ public @interface Header {
/**
* Skips this value if it's an empty string or empty collection/array.
+ *
* <p>
* Note that <jk>null</jk> values are already ignored.
*/
@@ -190,9 +196,11 @@ public @interface Header {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/HeaderIfNE.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/HeaderIfNE.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/HeaderIfNE.java
index b039ff0..7e34ba3 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/HeaderIfNE.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/HeaderIfNE.java
@@ -53,9 +53,11 @@ public @interface HeaderIfNE {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/Path.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/Path.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/Path.java
index bb8c08c..cc86b04 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/Path.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/Path.java
@@ -49,6 +49,7 @@ import org.apache.juneau.urlencoding.*;
* String myProxyMethod4(<ja>@Path</ja> MyBean myBean);
* }
* </p>
+ *
* <p>
* The annotation can also be applied to a bean property field or getter when the argument is annotated with
* {@link RequestBean @RequestBean}:
@@ -95,11 +96,11 @@ import org.apache.juneau.urlencoding.*;
* MyBean getMyBean();
* }
* </p>
+ *
* <p>
* The {@link #name()} and {@link #value()} elements are synonyms for specifying the path variable name.
* Only one should be used.
* <br>The following annotations are fully equivalent:
- * <p>
* <p class='bcode'>
* <ja>@Path</ja>(name=<js>"foo"</js>)
*
@@ -122,11 +123,14 @@ public @interface Path {
/**
* The path parameter name.
+ *
* <p>
* Note that {@link #name()} and {@link #value()} are synonyms.
+ *
* <p>
* The value should be either <js>"*"</js> to represent multiple name/value pairs, or a label that defines the
* path variable name.
+ *
* <p>
* A blank value (the default) has the following behavior:
* <ul class='spaced-list'>
@@ -171,6 +175,7 @@ public @interface Path {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
@@ -178,9 +183,11 @@ public @interface Path {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/Query.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/Query.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/Query.java
index a43f4e5..88b7db5 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/Query.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/Query.java
@@ -61,6 +61,7 @@ import org.apache.juneau.urlencoding.*;
* String myProxyMethod6(<ja>@Query</ja> Reader reader);
* }
* </p>
+ *
* <p>
* The annotation can also be applied to a bean property field or getter when the argument is annotated with
* {@link RequestBean @RequestBean}:
@@ -112,6 +113,7 @@ import org.apache.juneau.urlencoding.*;
* Reader getReader();
* }
* </p>
+ *
* <p>
* The {@link #name()} and {@link #value()} elements are synonyms for specifying the parameter name.
* Only one should be used.
@@ -138,11 +140,14 @@ public @interface Query {
/**
* The query parameter name.
+ *
* <p>
* Note that {@link #name()} and {@link #value()} are synonyms.
+ *
* <p>
* The value should be either <js>"*"</js> to represent multiple name/value pairs, or a label that defines the
* query parameter name.
+ *
* <p>
* A blank value (the default) has the following behavior:
* <ul class='spaced-list'>
@@ -189,6 +194,7 @@ public @interface Query {
/**
* A synonym for {@link #name()}.
+ *
* <p>
* Allows you to use shortened notation if you're only specifying the name.
*/
@@ -196,6 +202,7 @@ public @interface Query {
/**
* Skips this value if it's an empty string or empty collection/array.
+ *
* <p>
* Note that <jk>null</jk> values are already ignored.
*/
@@ -203,9 +210,11 @@ public @interface Query {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/QueryIfNE.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/QueryIfNE.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/QueryIfNE.java
index be70654..14dcf06 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/QueryIfNE.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/QueryIfNE.java
@@ -53,9 +53,11 @@ public @interface QueryIfNE {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the {@link RequestBean} annotation,
* then on the client which by default is {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethod.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethod.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethod.java
index fd9f8e2..906f992 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethod.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethod.java
@@ -20,6 +20,7 @@ import java.lang.annotation.*;
/**
* Annotation applied to Java methods on interface proxy classes.
+ *
* <p>
* The return type on the Java method can be any of the following:
* <ul>
@@ -49,6 +50,7 @@ public @interface RemoteMethod {
/**
* The path to the REST service for this Java method relative to the parent proxy interface URL.
+ *
* <p>
* The default value is the Java method name (e.g. <js>"http://localhost/root-url/org.foo.MyInterface/myMethod"</js>)
* if {@link Remoteable#methodPaths() @Remoteable.methodPaths()} is <js>"NAME"</js>, or the Java method signature
@@ -59,12 +61,14 @@ public @interface RemoteMethod {
/**
* Defines the HTTP method to use for REST calls.
+ *
* <p>
* Possible values:
* <ul>
* <li><js>"POST"</js> (default) - Parameters are serialized using the serializer registered with the RestClient.
* <li><js>"GET"</js> - Parameters are serialized using the UrlEncodingSerializer registered with the RestClient.
* </ul>
+ *
* <p>
* The default value is <js>"POST"</js>.
*/
@@ -72,6 +76,7 @@ public @interface RemoteMethod {
/**
* The value the remoteable method returns.
+ *
* <p>
* Possible values:
* <ul>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethodArg.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethodArg.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethodArg.java
index 394c6ba..ee8447f 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethodArg.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteMethodArg.java
@@ -49,9 +49,9 @@ public class RemoteMethodArg {
* @param name2 The argument name pulled from value().
* @param index The zero-based index of the argument on the Java method.
* @param skipIfNE The value is skipped if it's null/empty.
- * @param serializer The class to use for serializing headers, query parameters, form-data parameters, and
- * path variables.
- * If {@link UrlEncodingSerializer}, then the url-encoding serializer defined on the client will be used.
+ * @param serializer
+ * The class to use for serializing headers, query parameters, form-data parameters, and path variables.
+ * If {@link UrlEncodingSerializer}, then the url-encoding serializer defined on the client will be used.
*/
protected RemoteMethodArg(String name, String name2, int index, boolean skipIfNE, Class<? extends PartSerializer> serializer) {
this.name = name.isEmpty() ? name2 : name;
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/Remoteable.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/Remoteable.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/Remoteable.java
index 73e8b8c..4cb1964 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/Remoteable.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/Remoteable.java
@@ -36,9 +36,11 @@ public @interface Remoteable {
/**
* The absolute or relative path of the REST service.
+ *
* <p>
* When a relative path is specified, it's relative to the root-url defined on the <code>RestClient</code> used
* to instantiate the interface.
+ *
* <p>
* When no path is specified, the path is assumed to be the class name (e.g.
* <js>"http://localhost/root-url/org.foo.MyInterface"</js>)
@@ -47,6 +49,7 @@ public @interface Remoteable {
/**
* Identifies which methods on the interface should be exposed through the proxy.
+ *
* <p>
* The options are:
* <ul>
@@ -61,6 +64,7 @@ public @interface Remoteable {
/**
* Defines the methodology to use for the path names of the methods when not explicitly defined via
* {@link RemoteMethod#path() @RemoteMethod.path()}.
+ *
* <p>
* The options are:
* <ul>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMeta.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMeta.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMeta.java
index 5931ff8..82a17d8 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMeta.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMeta.java
@@ -21,9 +21,10 @@ import java.util.*;
/**
* Contains the meta-data about a remoteable interface.
+ *
* <p>
- * Captures the information in {@link Remoteable @Remoteable} and {@link RemoteMethod @RemoteMethod}
- * annotations for caching and reuse.
+ * Captures the information in {@link Remoteable @Remoteable} and {@link RemoteMethod @RemoteMethod} annotations for
+ * caching and reuse.
*
* <h6 class='topic'>Additional Information</h6>
* <ul class='doctree'>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMethodMeta.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMethodMeta.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMethodMeta.java
index 0495438..3568dd5 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMethodMeta.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/RemoteableMethodMeta.java
@@ -21,6 +21,7 @@ import java.util.*;
/**
* Contains the meta-data about a Java method on a remoteable interface.
+ *
* <p>
* Captures the information in {@link RemoteMethod @RemoteMethod} annotations for caching and reuse.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/remoteable/RequestBean.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/remoteable/RequestBean.java b/juneau-core/src/main/java/org/apache/juneau/remoteable/RequestBean.java
index 605f8b1..c0d0b13 100644
--- a/juneau-core/src/main/java/org/apache/juneau/remoteable/RequestBean.java
+++ b/juneau-core/src/main/java/org/apache/juneau/remoteable/RequestBean.java
@@ -97,9 +97,11 @@ public @interface RequestBean {
/**
* Specifies the {@link PartSerializer} class used for serializing values to strings.
+ *
* <p>
* The default value defaults to the using the part serializer defined on the client which by default is
* {@link UrlEncodingSerializer}.
+ *
* <p>
* This annotation is provided to allow values to be custom serialized.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java b/juneau-core/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
index c181a02..9b86b70 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/OutputStreamSerializer.java
@@ -23,7 +23,7 @@ import org.apache.juneau.annotation.*;
* Subclass of {@link Serializer} for byte-based serializers.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* This class is typically the parent class of all byte-based serializers.
* It has 1 abstract method to implement...
* <ul>
@@ -31,8 +31,9 @@ import org.apache.juneau.annotation.*;
* </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.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/PartSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/PartSerializer.java b/juneau-core/src/main/java/org/apache/juneau/serializer/PartSerializer.java
index 9b5f21b..940d6b0 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/PartSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/PartSerializer.java
@@ -19,6 +19,7 @@ import org.apache.juneau.urlencoding.*;
/**
* Interface used to convert POJOs to simple strings in HTTP headers, query parameters, form-data parameters, and URI
* path variables.
+ *
* <p>
* By default, the {@link UrlEncodingSerializer} class implements this interface so that it can be used to serialize
* these HTTP parts.
@@ -35,6 +36,7 @@ import org.apache.juneau.urlencoding.*;
* <li>{@link RequestBean#serializer()}
* <li><code>RestClientBuilder.partSerializer(Class)</code>
* </ul>
+ *
* <p>
* Implementations must include a no-arg constructor.
*/
@@ -43,6 +45,7 @@ public interface PartSerializer {
/**
* Converts the specified value to a string that can be used as an HTTP header value, query parameter value,
* form-data parameter, or URI path variable.
+ *
* <p>
* Returned values should NOT be URL-encoded. This will happen automatically.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/serializer/Serializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/serializer/Serializer.java b/juneau-core/src/main/java/org/apache/juneau/serializer/Serializer.java
index 70bbd4f..ac46f35 100644
--- a/juneau-core/src/main/java/org/apache/juneau/serializer/Serializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/serializer/Serializer.java
@@ -28,14 +28,16 @@ import org.apache.juneau.soap.*;
* Parent class for all Juneau serializers.
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Base serializer class that serves as the parent class for all serializers.
+ *
* <p>
* Subclasses should extend directly from {@link OutputStreamSerializer} or {@link WriterSerializer}.
*
* <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.
@@ -83,11 +85,14 @@ public abstract class Serializer extends CoreObject {
/**
* Serializes a POJO to the specified output stream or writer.
+ *
* <p>
* This method should NOT close the context object.
- * @param session The serializer session object return by {@link #createSession(Object, ObjectMap, Method, Locale,
- * TimeZone, MediaType, UriContext)}.
- * If <jk>null</jk>, session is created using {@link #createSession(Object)}.
+ *
+ * @param session
+ * The serializer session object return by {@link #createSession(Object, ObjectMap, Method, Locale, TimeZone,
+ * MediaType, UriContext)}.
+ * If <jk>null</jk>, session is created using {@link #createSession(Object)}.
* @param o The object to serialize.
* @throws Exception If thrown from underlying stream, or if the input contains a syntax error or is malformed.
*/
@@ -95,13 +100,13 @@ public abstract class Serializer extends CoreObject {
/**
* Shortcut method for serializing objects directly to either a <code>String</code> or <code><jk>byte</jk>[]</code>
- * depending on the serializer type.
- * <p>
+ * depending on the serializer type.
*
* @param o The object to serialize.
- * @return The serialized object.
- * <br>Character-based serializers will return a <code>String</code>
- * <br>Stream-based serializers will return a <code><jk>byte</jk>[]</code>
+ * @return
+ * The serialized object.
+ * <br>Character-based serializers will return a <code>String</code>
+ * <br>Stream-based serializers will return a <code><jk>byte</jk>[]</code>
* @throws SerializeException If a problem occurred trying to convert the output.
*/
public abstract Object serialize(Object o) throws SerializeException;
@@ -113,9 +118,10 @@ public abstract class Serializer extends CoreObject {
/**
* Serialize the specified object using the specified session.
*
- * @param session The serializer session object return by {@link #createSession(Object, ObjectMap, Method, Locale,
- * TimeZone, MediaType, UriContext)}.
- * If <jk>null</jk>, session is created using {@link #createSession(Object)}.
+ * @param session
+ * The serializer session object return by {@link #createSession(Object, ObjectMap, Method, Locale, TimeZone,
+ * MediaType, UriContext)}.
+ * If <jk>null</jk>, session is created using {@link #createSession(Object)}.
* @param o The object to serialize.
* @throws SerializeException If a problem occurred trying to convert the output.
*/
@@ -136,22 +142,24 @@ public abstract class Serializer extends CoreObject {
/**
* Serializes a POJO to the specified output stream or writer.
+ *
* <p>
* Equivalent to calling <code>serializer.serialize(o, out, <jk>null</jk>);</code>
*
* @param o The object to serialize.
- * @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 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>
* @throws SerializeException If a problem occurred trying to convert the output.
*/
public final void serialize(Object o, Object output) throws SerializeException {
@@ -161,32 +169,38 @@ public abstract class Serializer extends CoreObject {
/**
* Create the session object that will be passed in to the serialize method.
+ *
* <p>
* It's up to implementers to decide what the session object looks like, although typically it's going to be a
* subclass of {@link SerializerSession}.
*
- * @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 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 Optional additional properties.
- * @param javaMethod Java method that invoked this serializer.
- * 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.
- * @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 javaMethod
+ * Java method that invoked this serializer.
+ * 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.
+ * @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.
+ * @param uriContext
+ * The URI context.
* Identifies the current request URI used for resolution of URIs to absolute or root-relative form.
* @return The new session.
*/
@@ -197,21 +211,23 @@ public abstract class Serializer extends CoreObject {
/**
* Create a basic session object without overriding properties or specifying <code>javaMethod</code>.
+ *
* <p>
* Equivalent to calling <code>createSession(<jk>null</jk>, <jk>null</jk>)</code>.
*
- * @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 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>
* @return The new session.
*/
protected SerializerSession createSession(Object output) {
@@ -220,8 +236,10 @@ public abstract class Serializer extends CoreObject {
/**
* Converts the contents of the specified object array to a list.
+ *
* <p>
* Works on both object and primitive arrays.
+ *
* <p>
* In the case of multi-dimensional arrays, the outgoing list will contain elements of type n-1 dimension.
* i.e. if {@code type} is <code><jk>int</jk>[][]</code> then {@code list} will have entries of type
@@ -245,6 +263,7 @@ public abstract class Serializer extends CoreObject {
/**
* Returns the media types handled based on the value of the {@link Produces} annotation on the serializer class.
+ *
* <p>
* This method can be overridden by subclasses to determine the media types programmatically.
*
@@ -265,17 +284,20 @@ public abstract class Serializer extends CoreObject {
/**
* Optional method that specifies HTTP request headers for this serializer.
+ *
* <p>
* For example, {@link SoapXmlSerializer} needs to set a <code>SOAPAction</code> header.
+ *
* <p>
* This method is typically meaningless if the serializer is being used stand-alone (i.e. outside of a REST server
* or client).
*
- * @param properties Optional run-time properties (the same that are passed to
- * {@link WriterSerializer#doSerialize(SerializerSession, Object)}.
- * Can be <jk>null</jk>.
- * @return The HTTP headers to set on HTTP requests.
- * Can be <jk>null</jk>.
+ * @param properties
+ * Optional run-time properties (the same that are passed to {@link WriterSerializer#doSerialize(SerializerSession, Object)}.
+ * Can be <jk>null</jk>.
+ * @return
+ * The HTTP headers to set on HTTP requests.
+ * Can be <jk>null</jk>.
*/
public ObjectMap getResponseHeaders(ObjectMap properties) {
return ObjectMap.EMPTY_MAP;
@@ -284,11 +306,13 @@ public abstract class Serializer extends CoreObject {
/**
* Optional method that returns the response <code>Content-Type</code> for this serializer if it is different from
* the matched media type.
+ *
* <p>
* This method is specified to override the content type for this serializer.
* For example, the {@link org.apache.juneau.json.JsonSerializer.Simple} class returns that it handles media type
* <js>"text/json+simple"</js>, but returns <js>"text/json"</js> as the actual content type.
* This allows clients to request specific 'flavors' of content using specialized <code>Accept</code> header values.
+ *
* <p>
* This method is typically meaningless if the serializer is being used stand-alone (i.e. outside of a REST server
* or client).