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