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:22 UTC
[05/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/utils/PojoRest.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/PojoRest.java b/juneau-core/src/main/java/org/apache/juneau/utils/PojoRest.java
index d4c4f94..8183a52 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/PojoRest.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/PojoRest.java
@@ -24,6 +24,8 @@ import org.apache.juneau.parser.*;
/**
* Provides the ability to perform standard REST operations (GET, PUT, POST, DELETE) against nodes in a POJO model.
+ *
+ * <p>
* Nodes in the POJO model are addressed using URLs.
*
* <p>
@@ -139,6 +141,7 @@ public final class PojoRest {
/**
* Create a new instance of a REST interface over the specified object.
+ *
* <p>
* Uses {@link BeanContext#DEFAULT} for working with Java beans.
*
@@ -150,6 +153,7 @@ public final class PojoRest {
/**
* Create a new instance of a REST interface over the specified object.
+ *
* <p>
* The parser is used as the bean context.
*
@@ -197,8 +201,9 @@ public final class PojoRest {
/**
* Retrieves the element addressed by the URL.
*
- * @param url The URL of the element to retrieve.
- * If null or blank, returns the root.
+ * @param url
+ * The URL of the element to retrieve.
+ * If null or blank, returns the root.
* @param defVal The default value if the map doesn't contain the specified mapping.
* @return The addressed element, or null if that element does not exist in the tree.
*/
@@ -209,14 +214,15 @@ public final class PojoRest {
/**
* Retrieves the element addressed by the URL as the specified object type.
+ *
* <p>
* Will convert object to the specified type per {@link BeanSession#convertToType(Object, ClassMeta)}.
*
* @param type The specified object type.
- * @param url The URL of the element to retrieve.
- * If null or blank, returns the root.
+ * @param url
+ * The URL of the element to retrieve.
+ * If null or blank, returns the root.
* @param <T> The specified object type.
- *
* @return The addressed element, or null if that element does not exist in the tree.
*/
public <T> T get(Class<T> type, String url) {
@@ -225,12 +231,14 @@ public final class PojoRest {
/**
* Retrieves the element addressed by the URL as the specified object type.
+ *
* <p>
* Will convert object to the specified type per {@link BeanSession#convertToType(Object, ClassMeta)}.
*
* @param type The specified object type.
- * @param url The URL of the element to retrieve.
- * If null or blank, returns the root.
+ * @param url
+ * The URL of the element to retrieve.
+ * If null or blank, returns the root.
* @param def The default value if addressed item does not exist.
* @param <T> The specified object type.
* @return The addressed element, or null if that element does not exist in the tree.
@@ -244,6 +252,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link String}.
+ *
* <p>
* Shortcut for <code>get(String.<jk>class</jk>, key)</code>.
*
@@ -256,6 +265,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link String}.
+ *
* <p>
* Shortcut for <code>get(String.<jk>class</jk>, key, defVal)</code>.
*
@@ -269,6 +279,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to an {@link Integer}.
+ *
* <p>
* Shortcut for <code>get(Integer.<jk>class</jk>, key)</code>.
*
@@ -282,6 +293,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to an {@link Integer}.
+ *
* <p>
* Shortcut for <code>get(Integer.<jk>class</jk>, key, defVal)</code>.
*
@@ -296,6 +308,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Long}.
+ *
* <p>
* Shortcut for <code>get(Long.<jk>class</jk>, key)</code>.
*
@@ -309,6 +322,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Long}.
+ *
* <p>
* Shortcut for <code>get(Long.<jk>class</jk>, key, defVal)</code>.
*
@@ -323,6 +337,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Boolean}.
+ *
* <p>
* Shortcut for <code>get(Boolean.<jk>class</jk>, key)</code>.
*
@@ -336,6 +351,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Boolean}.
+ *
* <p>
* Shortcut for <code>get(Boolean.<jk>class</jk>, key, defVal)</code>.
*
@@ -350,6 +366,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Map}.
+ *
* <p>
* Shortcut for <code>get(Map.<jk>class</jk>, key)</code>.
*
@@ -363,6 +380,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Map}.
+ *
* <p>
* Shortcut for <code>get(Map.<jk>class</jk>, key, defVal)</code>.
*
@@ -377,6 +395,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link List}.
+ *
* <p>
* Shortcut for <code>get(List.<jk>class</jk>, key)</code>.
*
@@ -390,6 +409,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link List}.
+ *
* <p>
* Shortcut for <code>get(List.<jk>class</jk>, key, defVal)</code>.
*
@@ -404,6 +424,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link Map}.
+ *
* <p>
* Shortcut for <code>get(ObjectMap.<jk>class</jk>, key)</code>.
*
@@ -417,6 +438,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link ObjectMap}.
+ *
* <p>
* Shortcut for <code>get(ObjectMap.<jk>class</jk>, key, defVal)</code>.
*
@@ -431,6 +453,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link ObjectList}.
+ *
* <p>
* Shortcut for <code>get(ObjectList.<jk>class</jk>, key)</code>.
*
@@ -444,6 +467,7 @@ public final class PojoRest {
/**
* Returns the specified entry value converted to a {@link ObjectList}.
+ *
* <p>
* Shortcut for <code>get(ObjectList.<jk>class</jk>, key, defVal)</code>.
*
@@ -460,37 +484,41 @@ public final class PojoRest {
* Executes the specified method with the specified parameters on the specified object.
*
* @param url The URL of the element to retrieve.
- * @param method The method signature.
- * <p>
- * Can be any of the following formats:
- * <ul class='spaced-list'>
- * <li>
- * Method name only. e.g. <js>"myMethod"</js>.
- * <li>
- * Method name with class names. e.g. <js>"myMethod(String,int)"</js>.
- * <li>
- * Method name with fully-qualified class names. e.g. <js>"myMethod(java.util.String,int)"</js>.
- * </ul>
- * <p>
- * As a rule, use the simplest format needed to uniquely resolve a method.
- * @param args The arguments to pass as parameters to the method.
- * These will automatically be converted to the appropriate object type if possible.
- * This must be an array, like a JSON array.
+ * @param method
+ * The method signature.
+ * <p>
+ * Can be any of the following formats:
+ * <ul class='spaced-list'>
+ * <li>
+ * Method name only. e.g. <js>"myMethod"</js>.
+ * <li>
+ * Method name with class names. e.g. <js>"myMethod(String,int)"</js>.
+ * <li>
+ * Method name with fully-qualified class names. e.g. <js>"myMethod(java.util.String,int)"</js>.
+ * </ul>
+ * <p>
+ * As a rule, use the simplest format needed to uniquely resolve a method.
+ * @param args
+ * The arguments to pass as parameters to the method.
+ * These will automatically be converted to the appropriate object type if possible.
+ * This must be an array, like a JSON array.
* @return The returned object from the method call.
- * @throws IllegalAccessException If the <code>Constructor</code> object enforces Java language access control and
- * the underlying constructor is inaccessible.
- * @throws IllegalArgumentException If one of the following occurs:
- * <ul class='spaced-list'>
- * <li>
- * The number of actual and formal parameters differ.
- * <li>
- * An unwrapping conversion for primitive arguments fails.
- * <li>
- * A parameter value cannot be converted to the corresponding formal parameter type by a method invocation
- * conversion.
- * <li>
- * The constructor pertains to an enum type.
- * </ul>
+ * @throws IllegalAccessException
+ * If the <code>Constructor</code> object enforces Java language access control and the underlying constructor is
+ * inaccessible.
+ * @throws IllegalArgumentException
+ * If one of the following occurs:
+ * <ul class='spaced-list'>
+ * <li>
+ * The number of actual and formal parameters differ.
+ * <li>
+ * An unwrapping conversion for primitive arguments fails.
+ * <li>
+ * A parameter value cannot be converted to the corresponding formal parameter type by a method invocation
+ * conversion.
+ * <li>
+ * The constructor pertains to an enum type.
+ * </ul>
* @throws InvocationTargetException If the underlying constructor throws an exception.
* @throws ParseException If the input contains a syntax error or is malformed.
* @throws NoSuchMethodException
@@ -530,11 +558,13 @@ public final class PojoRest {
/**
* Sets/replaces the element addressed by the URL.
+ *
* <p>
* This method expands the POJO model as necessary to create the new element.
*
- * @param url The URL of the element to create.
- * If <jk>null</jk> or blank, the root itself is replaced with the specified value.
+ * @param url
+ * The URL of the element to create.
+ * If <jk>null</jk> or blank, the root itself is replaced with the specified value.
* @param val The value being set. Value can be of any type.
* @return The previously addressed element, or <jk>null</jk> the element did not previously exist.
*/
@@ -544,10 +574,13 @@ public final class PojoRest {
/**
* Adds a value to a list element in a POJO model.
+ *
* <p>
* The URL is the address of the list being added to.
+ *
* <p>
* If the list does not already exist, it will be created.
+ *
* <p>
* This method expands the POJO model as necessary to create the new element.
*
@@ -561,8 +594,9 @@ public final class PojoRest {
* </ul>
* </ul>
*
- * @param url The URL of the element being added to.
- * If <jk>null</jk> or blank, the root itself (assuming it's one of the types specified above) is added to.
+ * @param url
+ * The URL of the element being added to.
+ * If <jk>null</jk> or blank, the root itself (assuming it's one of the types specified above) is added to.
* @param val The value being added.
* @return The URL of the element that was added.
*/
@@ -572,11 +606,13 @@ public final class PojoRest {
/**
* Remove an element from a POJO model.
+ *
* <p>
* If the element does not exist, no action is taken.
*
- * @param url The URL of the element being deleted.
- * If <jk>null</jk> or blank, the root itself is deleted.
+ * @param url
+ * The URL of the element being deleted.
+ * If <jk>null</jk> or blank, the root itself is deleted.
* @return The removed element, or null if that element does not exist.
*/
public Object delete(String url) {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/utils/PojoRestException.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/PojoRestException.java b/juneau-core/src/main/java/org/apache/juneau/utils/PojoRestException.java
index 7de95ff..77ec174 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/PojoRestException.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/PojoRestException.java
@@ -19,8 +19,10 @@ import org.apache.juneau.*;
/**
* Generic exception thrown from the {@link PojoRest} class.
+ *
* <p>
* Typically, this is a user-error, such as trying to address a non-existent node in the tree.
+ *
* <p>
* The status code is an HTTP-equivalent code. It will be one of the following:
* <ul class='spaced-list'>
@@ -55,6 +57,7 @@ public final class PojoRestException extends FormattedRuntimeException {
/**
* The HTTP-equivalent status code.
+ *
* <p>
* See above for details.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/utils/ProcBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/ProcBuilder.java b/juneau-core/src/main/java/org/apache/juneau/utils/ProcBuilder.java
index 6cdf495..c8c41ed 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/ProcBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/ProcBuilder.java
@@ -25,6 +25,7 @@ import org.apache.juneau.utils.IOPipe.*;
/**
* Utility class for running operating system processes.
+ *
* <p>
* Similar to {@link java.lang.ProcessBuilder} but with additional features.
*/
@@ -41,6 +42,8 @@ public class ProcBuilder {
/**
* Creates a process builder with the specified arguments.
+ *
+ * <p>
* Equivalent to calling <code>ProcessBuilder.create().command(args);</code>
*
* @param args The command-line arguments.
@@ -61,6 +64,8 @@ public class ProcBuilder {
/**
* Command arguments.
+ *
+ * <p>
* Arguments can be collections or arrays and will be automatically expanded.
*
* @param args The command-line arguments.
@@ -72,6 +77,8 @@ public class ProcBuilder {
/**
* Command arguments if the specified matcher matches.
+ *
+ * <p>
* Can be used for specifying OS-specific commands.
*
* <h5 class='section'>Example:</h5>
@@ -96,6 +103,8 @@ public class ProcBuilder {
/**
* Append to the command arguments.
+ *
+ * <p>
* Arguments can be collections or arrays and will be automatically expanded.
*
* @param args The command-line arguments.
@@ -107,6 +116,8 @@ public class ProcBuilder {
/**
* Append to the command arguments if the specified matcher matches.
+ *
+ * <p>
* Arguments can be collections or arrays and will be automatically expanded.
*
* @param m The matcher.
@@ -131,6 +142,8 @@ public class ProcBuilder {
/**
* Use by-lines mode.
+ *
+ * <p>
* Flushes output after every line of input.
*
* @return This object (for method chaining).
@@ -142,6 +155,8 @@ public class ProcBuilder {
/**
* Pipe output to the specified writer.
+ *
+ * <p>
* The method can be called multiple times to write to multiple writers.
*
* @param w The writer to pipe to.
@@ -165,6 +180,8 @@ public class ProcBuilder {
/**
* Pipe output to the specified writer, including the command and return code.
+ *
+ * <p>
* The method can be called multiple times to write to multiple writers.
*
* @param w The writer to pipe to.
@@ -179,6 +196,8 @@ public class ProcBuilder {
/**
* Pipe output to the specified writer, including the command and return code.
+ *
+ * <p>
* The method can be called multiple times to write to multiple writers.
* Don't close the writer afterwards.
*
@@ -262,6 +281,8 @@ public class ProcBuilder {
/**
* Sets the maximum allowed return code on the process call.
+ *
+ * <p>
* If the return code exceeds this value, an IOException is returned on the {@link #run()} command.
* The default value is '0'.
*
@@ -327,6 +348,8 @@ public class ProcBuilder {
/**
* Destroys the underlying process.
+ *
+ * <p>
* This method is only needed if the {@link #getScanner()} method was used.
*/
private void close() {
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/utils/SearchArgs.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/SearchArgs.java b/juneau-core/src/main/java/org/apache/juneau/utils/SearchArgs.java
index 3fd9100..a252c97 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/SearchArgs.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/SearchArgs.java
@@ -60,20 +60,25 @@ public class SearchArgs {
/**
* Adds search terms to this builder.
+ *
* <p>
* The search terms are a comma-delimited list of key/value pairs of column-names and search tokens.
+ *
* <p>
* For example:
* <p class='bcode'>
* builder.search(<js>"column1=foo*, column2=bar baz"</js>);
* </p>
+ *
* <p>
* It's up to implementers to decide the syntax and meaning of the search terms.
+ *
* <p>
* Whitespace is trimmed from column names and search tokens.
*
- * @param searchTerms The search terms string.
- * Can be <jk>null</jk>.
+ * @param searchTerms
+ * The search terms string.
+ * Can be <jk>null</jk>.
* @return This object (for method chaining).
*/
public Builder search(String searchTerms) {
@@ -91,6 +96,7 @@ public class SearchArgs {
/**
* Adds a search term to this builder.
+ *
* <p>
* It's up to implementers to decide the syntax and meaning of the search term.
*
@@ -105,20 +111,25 @@ public class SearchArgs {
/**
* Specifies the list of columns to view.
+ *
* <p>
* The columns argument is a simple comma-delimited list of column names.
+ *
* <p>
* For example:
* <p class='bcode'>
* builder.view(<js>"column1, column2"</js>);
* </p>
+ *
* <p>
* Whitespace is trimmed from column names.
+ *
* <p>
* Empty view columns imply view all columns.
*
- * @param columns The columns being viewed.
- * Can be <jk>null</jk>.
+ * @param columns
+ * The columns being viewed.
+ * Can be <jk>null</jk>.
* @return This object (for method chaining).
*/
public Builder view(String columns) {
@@ -129,6 +140,7 @@ public class SearchArgs {
/**
* Specifies the list of columns to view.
+ *
* <p>
* Empty view columns imply view all columns.
*
@@ -161,8 +173,9 @@ public class SearchArgs {
* <p>
* Whitespace is trimmed from column names.
*
- * @param sortArgs The columns to sort by.
- * Can be <jk>null</jk>.
+ * @param sortArgs
+ * The columns to sort by.
+ * Can be <jk>null</jk>.
* @return This object (for method chaining).
*/
public Builder sort(String sortArgs) {
@@ -181,8 +194,9 @@ public class SearchArgs {
* <p>
* Note that the order of the sort is important.
*
- * @param sortArgs The columns to sort by.
- * Can be <jk>null</jk>.
+ * @param sortArgs
+ * The columns to sort by.
+ * Can be <jk>null</jk>.
* @return This object (for method chaining).
*/
public Builder sort(Collection<String> sortArgs) {
@@ -211,8 +225,9 @@ public class SearchArgs {
/**
* Specifies the number of rows to return.
*
- * @param limit The number of rows to return.
- * If <code><=0</code>, all rows should be returned.
+ * @param limit
+ * The number of rows to return.
+ * If <code><=0</code>, all rows should be returned.
* @return This object (for method chaining).
*/
public Builder limit(int limit) {
@@ -222,6 +237,7 @@ public class SearchArgs {
/**
* Specifies whether case-insensitive search should be used.
+ *
* <p>
* The default is <jk>false</jk>.
*
@@ -235,6 +251,7 @@ public class SearchArgs {
/**
* Construct the {@link SearchArgs} object.
+ *
* <p>
* This method can be called multiple times to construct new objects.
*
@@ -247,8 +264,10 @@ public class SearchArgs {
/**
* The query search terms.
+ *
* <p>
* The search terms are key/value pairs consisting of column-names and search tokens.
+ *
* <p>
* It's up to implementers to decide the syntax and meaning of the search term.
*
@@ -260,6 +279,7 @@ public class SearchArgs {
/**
* The view columns.
+ *
* <p>
* The view columns are the list of columns that should be displayed.
* An empty list implies all columns should be displayed.
@@ -272,9 +292,10 @@ public class SearchArgs {
/**
* The sort columns.
+ *
* <p>
* The sort columns are key/value pairs consisting of column-names and direction flags
- * (<jk>false</jk> = ascending, <jk>true</jk> = descending).
+ * (<jk>false</jk> = ascending, <jk>true</jk> = descending).
*
* @return An unmodifiable ordered map of sort columns and directions.
*/
@@ -285,8 +306,9 @@ public class SearchArgs {
/**
* The first-row position.
*
- * @return The zero-indexed row number of the first row to display.
- * Default is <code>0</code>
+ * @return
+ * The zero-indexed row number of the first row to display.
+ * Default is <code>0</code>
*/
public int getPosition() {
return position;
@@ -295,8 +317,9 @@ public class SearchArgs {
/**
* The number of rows to return.
*
- * @return The number of rows to return in the result.
- * Default is <code>0</code> which means return all rows.
+ * @return
+ * The number of rows to return in the result.
+ * Default is <code>0</code> which means return all rows.
*/
public int getLimit() {
return limit;
@@ -304,11 +327,13 @@ public class SearchArgs {
/**
* The ignore-case flag.
+ *
* <p>
* Used in conjunction with {@link #getSearch()} to specify whether case-insensitive searches should be performed.
*
- * @return The number of rows to return in the result.
- * Default is <jk>false</jk>.
+ * @return
+ * The number of rows to return in the result.
+ * Default is <jk>false</jk>.
*/
public boolean isIgnoreCase() {
return ignoreCase;
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/utils/StringMessage.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/StringMessage.java b/juneau-core/src/main/java/org/apache/juneau/utils/StringMessage.java
index 1a553d1..329d58a 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/StringMessage.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/StringMessage.java
@@ -22,6 +22,7 @@ import org.apache.juneau.http.*;
/**
* An encapsulated MessageFormat-style string and arguments.
+ *
* <p>
* Useful for delayed serialization of arguments for logging.
* Message string will not be constructed until the <code>toString()</code> method is called.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/utils/StringObject.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/StringObject.java b/juneau-core/src/main/java/org/apache/juneau/utils/StringObject.java
index 7198b26..0cf0b28 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/StringObject.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/StringObject.java
@@ -21,8 +21,10 @@ import org.apache.juneau.serializer.*;
/**
* A serializer/object pair used for delayed object serialization.
+ *
* <p>
* Useful in certain conditions such as logging when you don't want to needlessly serialize objects.
+ *
* <p>
* Instances of this method are created by the {@link WriterSerializer#toStringObject(Object)} method.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/utils/ZipFileList.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/utils/ZipFileList.java b/juneau-core/src/main/java/org/apache/juneau/utils/ZipFileList.java
index 9d6d6f9..5637136 100644
--- a/juneau-core/src/main/java/org/apache/juneau/utils/ZipFileList.java
+++ b/juneau-core/src/main/java/org/apache/juneau/utils/ZipFileList.java
@@ -19,6 +19,7 @@ import java.util.zip.*;
/**
* Utility class for representing the contents of a zip file as a list of entries whose contents don't resolve until
* serialization time.
+ *
* <p>
* Generally associated with <code>RestServlets</code> using the <code>responseHandlers</code> annotation so that
* REST methods can easily create ZIP file responses by simply returning instances of this class.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/Namespace.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/Namespace.java b/juneau-core/src/main/java/org/apache/juneau/xml/Namespace.java
index dc775e6..a3a85dc 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/Namespace.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/Namespace.java
@@ -16,9 +16,10 @@ import org.apache.juneau.annotation.*;
/**
* Represents a simple namespace mapping between a simple name and URI.
+ *
* <p>
- * In general, the simple name will be used as the XML prefix mapping unless there are conflicts or prefix
- * re-mappings in the serializer.
+ * In general, the simple name will be used as the XML prefix mapping unless there are conflicts or prefix re-mappings
+ * in the serializer.
*/
@Bean(sort=true)
public final class Namespace implements Comparable<Namespace> {
@@ -27,6 +28,7 @@ public final class Namespace implements Comparable<Namespace> {
/**
* Constructor.
+ *
* <p>
* Use this constructor when the long name and short name are the same value.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/NamespaceFactory.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/NamespaceFactory.java b/juneau-core/src/main/java/org/apache/juneau/xml/NamespaceFactory.java
index 396cbb3..214eff5 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/NamespaceFactory.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/NamespaceFactory.java
@@ -21,6 +21,7 @@ import org.apache.juneau.parser.*;
/**
* Factory class for getting unique instances of {@link Namespace} objects.
+ *
* <p>
* For performance reasons, {@link Namespace} objects are stored in {@link IdentityList IdentityLists}.
* For this to work property, namespaces with the same name and URI must only be represented by a single
@@ -52,6 +53,7 @@ public final class NamespaceFactory {
/**
* Converts the specified object into a {@link Namespace} object.
+ *
* <p>
* Can be any of following types:
* <ul>
@@ -84,6 +86,7 @@ public final class NamespaceFactory {
/**
* Converts the specified object into an array of {@link Namespace} object.
+ *
* <p>
* Can be any of following types:
* <ul>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanMeta.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanMeta.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanMeta.java
index ad489fa..b99f5c5 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanMeta.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanMeta.java
@@ -229,6 +229,7 @@ public class XmlBeanMeta extends BeanMetaExtended {
/**
* Returns the format of the inner XML content of this bean.
+ *
* <p>
* Can be one of the following:
* <ul>
@@ -250,9 +251,10 @@ public class XmlBeanMeta extends BeanMetaExtended {
/**
* Returns bean property meta with the specified name.
- * This is identical to calling {@link BeanMeta#getPropertyMeta(String)} except it first retrieves
- * the bean property meta based on the child name (e.g. a property whose name is "people", but whose child name is
- * "person").
+ *
+ * <p>
+ * This is identical to calling {@link BeanMeta#getPropertyMeta(String)} except it first retrieves the bean property
+ * meta based on the child name (e.g. a property whose name is "people", but whose child name is "person").
*
* @param fieldName The bean property name.
* @return The property metadata.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanPropertyMeta.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanPropertyMeta.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanPropertyMeta.java
index ad34afb..5eb1d4a 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanPropertyMeta.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlBeanPropertyMeta.java
@@ -48,6 +48,7 @@ public class XmlBeanPropertyMeta extends BeanPropertyMetaExtended {
/**
* Returns the XML namespace associated with this bean property.
+ *
* <p>
* Namespace is determined in the following order:
* <ol>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlClassMeta.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlClassMeta.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlClassMeta.java
index 395bc80..d1c42a5 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlClassMeta.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlClassMeta.java
@@ -56,8 +56,8 @@ public class XmlClassMeta extends ClassMetaExtended {
/**
* Returns the {@link Xml} annotation defined on the class.
*
- * @return The value of the {@link Xml} annotation defined on the class, or <jk>null</jk> if annotation is not
- * specified.
+ * @return
+ * The value of the {@link Xml} annotation defined on the class, or <jk>null</jk> if annotation is not specified.
*/
protected Xml getAnnotation() {
return xml;
@@ -83,6 +83,7 @@ public class XmlClassMeta extends ClassMetaExtended {
/**
* Returns the XML namespace associated with this class.
+ *
* <p>
* Namespace is determined in the following order:
* <ol>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlDocSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlDocSerializer.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlDocSerializer.java
index b26f025..36b7376 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlDocSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlDocSerializer.java
@@ -22,13 +22,14 @@ import org.apache.juneau.serializer.*;
* Serializes POJOs to HTTP responses as XML.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/xml</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/xml</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Same as {@link XmlSerializer}, except prepends <code><xt><?xml</xt> <xa>version</xa>=<xs>'1.0'</xs>
* <xa>encoding</xa>=<xs>'UTF-8'</xs><xt>?></xt></code> to the response to make it a valid XML document.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlParser.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParser.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParser.java
index c4f4d35..3d57a16 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParser.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParser.java
@@ -33,15 +33,15 @@ import org.apache.juneau.xml.annotation.*;
* Parses text generated by the {@link XmlSerializer} class back into a POJO model.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Content-Type</code> types: <code>text/xml</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* See the {@link XmlSerializer} class for a description of Juneau-generated XML.
*
* <h5 class='section'>Configurable properties:</h5>
- * <p>
+ *
* This class has the following properties associated with it:
* <ul>
* <li>{@link XmlParserContext}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserBuilder.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserBuilder.java
index d6b287d..b27de19 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserBuilder.java
@@ -56,16 +56,18 @@ public class XmlParserBuilder extends ParserBuilder {
/**
* <b>Configuration property:</b> Enable validation.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParserBuilder.validating"</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>, XML document will be validated.
* See {@link XMLInputFactory#IS_VALIDATING} for more info.
+ *
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
@@ -85,13 +87,14 @@ public class XmlParserBuilder extends ParserBuilder {
/**
* <b>Configuration property:</b> XML reporter.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParserBuilder.reporter"</js>
* <li><b>Data type:</b> {@link XMLReporter}
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Associates an {@link XMLReporter} with this parser.
*
@@ -99,6 +102,7 @@ public class XmlParserBuilder extends ParserBuilder {
* <ul>
* <li>Reporters are not copied to new parsers during a clone.
* </ul>
+ *
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
@@ -118,15 +122,17 @@ public class XmlParserBuilder extends ParserBuilder {
/**
* <b>Configuration property:</b> XML resolver.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParserBuilder.resolver"</js>
* <li><b>Data type:</b> {@link XMLResolver}
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Associates an {@link XMLResolver} with this parser.
+ *
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
@@ -146,15 +152,17 @@ public class XmlParserBuilder extends ParserBuilder {
/**
* <b>Configuration property:</b> XML event allocator.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParserBuilder.eventAllocator"</js>
* <li><b>Data type:</b> {@link XMLEventAllocator}
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Associates an {@link XMLEventAllocator} with this parser.
+ *
* <p>
* If <jk>true</jk>, string values will be trimmed of whitespace using {@link String#trim()} before being added to
* the POJO.
@@ -174,16 +182,17 @@ public class XmlParserBuilder extends ParserBuilder {
/**
* <b>Configuration property:</b> Preserve root element during generalized parsing.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParserBuilder.preserveRootElement"</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>, when parsing into a generic {@link ObjectMap}, the map will
- * contain a single entry whose key is the root element name.
+ * If <jk>true</jk>, when parsing into a generic {@link ObjectMap}, the map will contain a single entry whose key is
+ * the root element name.
*
* Example:
* <table class='styled'>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserContext.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserContext.java
index fdeea43..bc8496e 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserContext.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserContext.java
@@ -20,9 +20,11 @@ import org.apache.juneau.parser.*;
/**
* Configurable properties on the {@link XmlParser} class.
+ *
* <p>
* Context properties are set by calling {@link PropertyStore#setProperty(String, Object)} on the property store
* passed into the constructor.
+ *
* <p>
* See {@link PropertyStore} for more information about context properties.
*
@@ -43,13 +45,14 @@ public class XmlParserContext extends ParserContext {
/**
* <b>Configuration property:</b> Enable validation.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParser.validating"</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>, XML document will be validated.
* See {@link XMLInputFactory#IS_VALIDATING} for more info.
@@ -58,13 +61,14 @@ public class XmlParserContext extends ParserContext {
/**
* <b>Configuration property:</b> XML reporter.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParser.reporter"</js>
* <li><b>Data type:</b> {@link XMLReporter}
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Associates an {@link XMLReporter} with this parser.
*
@@ -77,13 +81,14 @@ public class XmlParserContext extends ParserContext {
/**
* <b>Configuration property:</b> XML resolver.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParser.resolver"</js>
* <li><b>Data type:</b> {@link XMLResolver}
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Associates an {@link XMLResolver} with this parser.
*/
@@ -91,13 +96,14 @@ public class XmlParserContext extends ParserContext {
/**
* <b>Configuration property:</b> XML event allocator.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParser.eventAllocator"</js>
* <li><b>Data type:</b> {@link XMLEventAllocator}
* <li><b>Default:</b> <jk>null</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Associates an {@link XMLEventAllocator} with this parser.
*/
@@ -105,16 +111,18 @@ public class XmlParserContext extends ParserContext {
/**
* <b>Configuration property:</b> Preserve root element during generalized parsing.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlParser.preserveRootElement"</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>, when parsing into a generic {@link ObjectMap}, the map will contain a single entry whose key
* is the root element name.
+ *
* <p>
* Example:
* <table class='styled'>
@@ -141,6 +149,7 @@ public class XmlParserContext extends ParserContext {
/**
* Constructor.
+ *
* <p>
* Typically only called from {@link PropertyStore#getContext(Class)}.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserSession.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserSession.java
index c903421..5d3f2d9 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserSession.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlParserSession.java
@@ -30,6 +30,7 @@ import org.apache.juneau.xml.annotation.*;
/**
* Session object that lives for the duration of a single use of {@link XmlParser}.
+ *
* <p>
* This class is NOT thread safe. It is meant to be discarded after one-time use.
*/
@@ -47,24 +48,30 @@ public class XmlParserSession extends ParserSession {
/**
* 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. 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.
- * <li>{@link File} containing system encoded text.
- * </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.
+ * 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.
+ * <li>{@link File} containing system encoded text.
+ * </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 XmlParserSession(XmlParserContext ctx, ObjectMap op, Object input, Method javaMethod, Object outer,
@@ -128,6 +135,7 @@ public class XmlParserSession extends ParserSession {
/**
* Decodes and trims the specified string.
+ *
* <p>
* Any <js>'_x####_'</js> sequences in the string will be decoded.
*
@@ -146,6 +154,7 @@ public class XmlParserSession extends ParserSession {
/**
* Returns the name of the current XML element.
+ *
* <p>
* Any <js>'_x####_'</js> sequences in the string will be decoded.
*
@@ -159,6 +168,7 @@ public class XmlParserSession extends ParserSession {
/**
* Returns the name of the specified attribute on the current XML element.
+ *
* <p>
* Any <js>'_x####_'</js> sequences in the string will be decoded.
*
@@ -173,6 +183,7 @@ public class XmlParserSession extends ParserSession {
/**
* Returns the value of the specified attribute on the current XML element.
+ *
* <p>
* Any <js>'_x####_'</js> sequences in the string will be decoded.
*
@@ -187,8 +198,10 @@ public class XmlParserSession extends ParserSession {
/**
* Returns the text content of the current XML element.
+ *
* <p>
* Any <js>'_x####_'</js> sequences in the string will be decoded.
+ *
* <p>
* Leading and trailing whitespace (unencoded) will be trimmed from the result.
*
@@ -203,14 +216,17 @@ public class XmlParserSession extends ParserSession {
/**
* Returns the content of the current CHARACTERS node.
+ *
* <p>
* Any <js>'_x####_'</js> sequences in the string will be decoded.
+ *
* <p>
* Leading and trailing whitespace (unencoded) will be trimmed from the result.
*
* @param r The reader to read the element text from.
- * @param trim If <jk>true</jk>, trim the contents of the text node BEFORE decoding escape sequences.
- * Typically <jk>true</jk> for {@link XmlFormat#MIXED_PWS} and {@link XmlFormat#TEXT_PWS}.
+ * @param trim
+ * If <jk>true</jk>, trim the contents of the text node BEFORE decoding escape sequences.
+ * Typically <jk>true</jk> for {@link XmlFormat#MIXED_PWS} and {@link XmlFormat#TEXT_PWS}.
* @return The decoded text. <jk>null</jk> if the text consists of the sequence <js>'_x0000_'</js>.
* @throws XMLStreamException
*/
@@ -236,6 +252,7 @@ public class XmlParserSession extends ParserSession {
/**
* Takes the element being read from the XML stream reader and reconstructs it as XML.
+ *
* <p>
* Used when reconstructing bean properties of type {@link XmlFormat#XMLTEXT}.
*
@@ -258,6 +275,8 @@ public class XmlParserSession extends ParserSession {
/**
* Parses the current element as text.
+ *
+ * <p>
* Note that this is different than {@link #getText(XMLStreamReader)} since it assumes that we're pointing to a
* whitespace element.
*
@@ -291,6 +310,7 @@ public class XmlParserSession extends ParserSession {
/**
* Returns <jk>true</jk> if the current element is a whitespace element.
+ *
* <p>
* For the XML parser, this always returns <jk>false</jk>.
* However, the HTML parser defines various whitespace elements such as <js>"br"</js> and <js>"sp"</js>.
@@ -304,6 +324,7 @@ public class XmlParserSession extends ParserSession {
/**
* Parses the current whitespace element.
+ *
* <p>
* For the XML parser, this always returns <jk>null</jk> since there is no concept of a whitespace element.
* However, the HTML parser defines various whitespace elements such as <js>"br"</js> and <js>"sp"</js>.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaDocSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaDocSerializer.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaDocSerializer.java
index edab0e4..6667123 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaDocSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaDocSerializer.java
@@ -19,13 +19,14 @@ import org.apache.juneau.serializer.*;
* Serializes POJO metadata to HTTP responses as XML.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/xml+schema</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/xml</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Same as {@link XmlSchemaSerializer}, except prepends <code><xt><?xml</xt> <xa>version</xa>=<xs>'1.0'</xs>
* <xa>encoding</xa>=<xs>'UTF-8'</xs><xt>?></xt></code> to the response to make it a valid XML document.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaSerializer.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaSerializer.java
index ab93ce9..b34c836 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSchemaSerializer.java
@@ -37,17 +37,18 @@ import org.w3c.dom.ls.*;
* Serializes POJO metadata to HTTP responses as XML.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/xml+schema</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/xml</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* Produces the XML-schema representation of the XML produced by the {@link XmlSerializer} class with the same properties.
*
* <h5 class='section'>Configurable properties:</h5>
- * <p>
+ *
* This class has the following properties associated with it:
* <ul>
* <li>{@link XmlSerializerContext}
@@ -97,9 +98,10 @@ public class XmlSchemaSerializer extends XmlSerializer {
/**
* Returns an XML-Schema validator based on the output returned by {@link #doSerialize(SerializerSession, Object)};
*
- * @param session The serializer session object return by {@link #createSession(Object, ObjectMap, Method, Locale,
- * TimeZone, MediaType, UriContext)}.
- * Can be <jk>null</jk>.
+ * @param session
+ * The serializer session object return by {@link #createSession(Object, ObjectMap, Method, Locale, TimeZone,
+ * MediaType, UriContext)}.
+ * Can be <jk>null</jk>.
* @param o The object to serialize.
* @return The new validator.
* @throws Exception If a problem was detected in the XML-Schema output produced by this serializer.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializer.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializer.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializer.java
index 8d75f98..702107d 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializer.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializer.java
@@ -33,14 +33,16 @@ import org.apache.juneau.xml.annotation.*;
* Serializes POJO models to XML.
*
* <h5 class='section'>Media types:</h5>
- * <p>
+ *
* Handles <code>Accept</code> types: <code>text/xml</code>
+ *
* <p>
* Produces <code>Content-Type</code> types: <code>text/xml</code>
*
* <h5 class='section'>Description:</h5>
- * <p>
+ *
* See the {@link JsonSerializer} class for details on how Java models map to JSON.
+ *
* <p>
* For example, the following JSON...
* <p class='bcode'>
@@ -81,6 +83,7 @@ import org.apache.juneau.xml.annotation.*;
* <xt><height></xt>62.4<xt></height></xt>
* <xt><fico_x0020_score></xt> &gt; 640<xt></fico_x0020_score></xt>
* <xt></object></xt>
+ *
* <p>
* An additional "add-json-properties" mode is also provided to prevent loss of JSON data types...
* <p class='bcode'>
@@ -100,16 +103,19 @@ import org.apache.juneau.xml.annotation.*;
* <xt><height</xt> <xa>_type</xa>=<xs>'number'</xs><xt>></xt>62.4<xt></height></xt>
* <xt><fico_x0020_score</xt> <xa>_type</xa>=<xs>'string'</xs><xt>></xt> &gt; 640<xt></fico_x0020_score></xt>
* <xt></object></xt>
+ * </p>
+ *
* <p>
* This serializer provides several serialization options.
* Typically, one of the predefined <jsf>DEFAULT</jsf> serializers will be sufficient.
* However, custom serializers can be constructed to fine-tune behavior.
+ *
* <p>
* If an attribute name contains any non-valid XML element characters, they will be escaped using standard
* {@code _x####_} notation.
*
* <h5 class='section'>Configurable properties:</h5>
- * <p>
+ *
* This class has the following properties associated with it:
* <ul>
* <li>{@link XmlSerializerContext}
@@ -117,7 +123,7 @@ import org.apache.juneau.xml.annotation.*;
* </ul>
*
* <h6 class='topic'>Behavior-specific subclasses</h6>
- * <p>
+ *
* The following direct subclasses are provided for convenience:
* <ul>
* <li>{@link Sq} - Default serializer, single quotes.
@@ -353,8 +359,8 @@ public class XmlSerializer extends WriterSerializer {
* @param addNamespaceUris Flag indicating that namespace URIs need to be added.
* @param format The format to serialize the output to.
* @param isMixed We're serializing mixed content, so don't use whitespace.
- * @param preserveWhitespace <jk>true</jk> if we're serializing {@link XmlFormat#MIXED_PWS} or
- * {@link XmlFormat#TEXT_PWS}.
+ * @param preserveWhitespace
+ * <jk>true</jk> if we're serializing {@link XmlFormat#MIXED_PWS} or {@link XmlFormat#TEXT_PWS}.
* @param pMeta The bean property metadata if this is a bean property being serialized.
* @return The same writer passed in so that calls to the writer can be chained.
* @throws Exception If a problem occurred trying to convert the output.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
index af35156..0a5cf30 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerBuilder.java
@@ -53,13 +53,14 @@ public class XmlSerializerBuilder extends SerializerBuilder {
/**
* <b>Configuration property:</b> Enable support for XML namespaces.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.enableNamespaces"</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 not enabled, XML output will not contain any namespaces regardless of any other settings.
*
@@ -88,21 +89,25 @@ public class XmlSerializerBuilder extends SerializerBuilder {
/**
* <b>Configuration property:</b> Auto-detect namespace usage.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.autoDetectNamespaces"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Detect namespace usage before serialization.
+ *
* <p>
* Used in conjunction with {@link XmlSerializerContext#XML_addNamespaceUrisToRoot} to reduce the list of namespace
* URLs appended to the root element to only those that will be used in the resulting document.
+ *
* <p>
* If enabled, then the data structure will first be crawled looking for namespaces that will be encountered before
* the root element is serialized.
+ *
* <p>
* This setting is ignored if {@link XmlSerializerContext#XML_enableNamespaces} is not enabled.
*
@@ -129,15 +134,17 @@ public class XmlSerializerBuilder extends SerializerBuilder {
/**
* <b>Configuration property:</b> Add namespace URLs to the root element.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.addNamespaceUrisToRoot"</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>
* Use this setting to add {@code xmlns:x} attributes to the root element for the default and all mapped namespaces.
+ *
* <p>
* This setting is ignored if {@link XmlSerializerContext#XML_enableNamespaces} is not enabled.
*
@@ -157,13 +164,14 @@ public class XmlSerializerBuilder extends SerializerBuilder {
/**
* <b>Configuration property:</b> Default namespace.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.defaultNamespace"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"{juneau:'http://www.apache.org/2013/Juneau'}"</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Specifies the default namespace URI for this document.
*
@@ -183,13 +191,14 @@ public class XmlSerializerBuilder extends SerializerBuilder {
/**
* <b>Configuration property:</b> XMLSchema namespace.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.xsNamespace"</js>
* <li><b>Data type:</b> {@link Namespace}
* <li><b>Default:</b> <code>{name:<js>'xs'</js>,uri:<js>'http://www.w3.org/2001/XMLSchema'</js>}</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Specifies the namespace for the <code>XMLSchema</code> namespace, used by the schema generated by the
* {@link XmlSchemaSerializer} class.
@@ -210,13 +219,14 @@ public class XmlSerializerBuilder extends SerializerBuilder {
/**
* <b>Configuration property:</b> Default namespaces.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.namespaces"</js>
* <li><b>Data type:</b> <code>Set<{@link Namespace}></code>
* <li><b>Default:</b> empty set
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The default list of namespaces associated with this serializer.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerContext.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerContext.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerContext.java
index 450ad36..afdad46 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerContext.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerContext.java
@@ -17,9 +17,11 @@ import org.apache.juneau.serializer.*;
/**
* Configurable properties on the {@link XmlSerializer} class.
+ *
* <p>
* Context properties are set by calling {@link PropertyStore#setProperty(String, Object)} on the property store
* passed into the constructor.
+ *
* <p>
* See {@link PropertyStore} for more information about context properties.
*
@@ -40,13 +42,14 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> Enable support for XML namespaces.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.enableNamespaces"</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 not enabled, XML output will not contain any namespaces regardless of any other settings.
*/
@@ -54,21 +57,25 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> Auto-detect namespace usage.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.autoDetectNamespaces"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>true</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Detect namespace usage before serialization.
+ *
* <p>
* Used in conjunction with {@link #XML_addNamespaceUrisToRoot} to reduce the list of namespace URLs appended to the
* root element to only those that will be used in the resulting document.
+ *
* <p>
* If enabled, then the data structure will first be crawled looking for namespaces that will be encountered before
* the root element is serialized.
+ *
* <p>
* This setting is ignored if {@link #XML_enableNamespaces} is not enabled.
*
@@ -83,15 +90,17 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> Add namespace URLs to the root element.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.addNamespaceUrisToRoot"</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>
* Use this setting to add {@code xmlns:x} attributes to the root element for the default and all mapped namespaces.
+ *
* <p>
* This setting is ignored if {@link #XML_enableNamespaces} is not enabled.
*/
@@ -99,13 +108,14 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> Default namespace.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.defaultNamespace"</js>
* <li><b>Data type:</b> <code>String</code>
* <li><b>Default:</b> <js>"{juneau:'http://www.apache.org/2013/Juneau'}"</js>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Specifies the default namespace URI for this document.
*/
@@ -113,13 +123,14 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> XMLSchema namespace.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.xsNamespace"</js>
* <li><b>Data type:</b> {@link Namespace}
* <li><b>Default:</b> <code>{name:<js>'xs'</js>,uri:<js>'http://www.w3.org/2001/XMLSchema'</js>}</code>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* Specifies the namespace for the <code>XMLSchema</code> namespace, used by the schema generated by the
* {@link XmlSchemaSerializer} class.
@@ -128,13 +139,14 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> Default namespaces.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.namespaces"</js>
* <li><b>Data type:</b> <code>Set<{@link Namespace}></code>
* <li><b>Default:</b> empty set
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* The default list of namespaces associated with this serializer.
*/
@@ -142,19 +154,21 @@ public class XmlSerializerContext extends SerializerContext {
/**
* <b>Configuration property:</b> Add <js>"_type"</js> properties when needed.
- * <p>
+ *
* <ul>
* <li><b>Name:</b> <js>"XmlSerializer.addBeanTypeProperties"</js>
* <li><b>Data type:</b> <code>Boolean</code>
* <li><b>Default:</b> <jk>false</jk>
* <li><b>Session-overridable:</b> <jk>true</jk>
* </ul>
+ *
* <p>
* If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred
* through reflection.
* This is used to recreate the correct objects during parsing if the object types cannot be inferred.
* For example, when serializing a {@code Map<String,Object>} field, where the bean class cannot be determined from
* the value type.
+ *
* <p>
* When present, this value overrides the {@link SerializerContext#SERIALIZER_addBeanTypeProperties} setting and is
* provided to customize the behavior of specific serializers in a {@link SerializerGroup}.
@@ -177,6 +191,7 @@ public class XmlSerializerContext extends SerializerContext {
/**
* Constructor.
+ *
* <p>
* Typically only called from {@link PropertyStore#getContext(Class)}.
*
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerSession.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerSession.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerSession.java
index 76588c4..3033b17 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerSession.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlSerializerSession.java
@@ -28,6 +28,7 @@ import org.apache.juneau.serializer.*;
/**
* Session object that lives for the duration of a single use of {@link XmlSerializer}.
+ *
* <p>
* This class is NOT thread safe. It is meant to be discarded after one-time use.
*/
@@ -50,19 +51,24 @@ public class XmlSerializerSession extends SerializerSession {
/**
* 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 ctx
+ * The context creating this session object.
+ * The context contains all the configuration settings for this object.
* @param output The output object. See {@link JsonSerializerSession#getWriter()} for valid class types.
- * @param op The override properties.
- * These override any context properties defined in the context.
+ * @param op
+ * The override properties.
+ * These override any context properties defined in the context.
* @param javaMethod The java method that called this serializer, usually the method in a REST servlet.
- * @param locale The session locale.
- * If <jk>null</jk>, then the locale defined on the context is used.
- * @param timeZone The session timezone.
- * If <jk>null</jk>, then the timezone defined on the context is used.
+ * @param locale
+ * The session locale.
+ * If <jk>null</jk>, then the locale defined on the context is used.
+ * @param timeZone
+ * The session timezone.
+ * If <jk>null</jk>, then the timezone defined on the context is used.
* @param mediaType The session media type (e.g. <js>"application/json"</js>).
- * @param uriContext The URI context.
- * Identifies the current request URI used for resolution of URIs to absolute or root-relative form.
+ * @param uriContext
+ * The URI context.
+ * Identifies the current request URI used for resolution of URIs to absolute or root-relative form.
*/
public XmlSerializerSession(XmlSerializerContext ctx, ObjectMap op, Object output, Method javaMethod, Locale locale,
TimeZone timeZone, MediaType mediaType, UriContext uriContext) {
@@ -186,6 +192,7 @@ public class XmlSerializerSession extends SerializerSession {
/**
* Returns <jk>true</jk> if we're serializing HTML.
+ *
* <p>
* The difference in behavior is how empty non-void elements are handled.
* The XML serializer will produce a collapsed tag, whereas the HTML serializer will produce a start and end tag.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlUtils.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlUtils.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlUtils.java
index 2b1160e..0331315 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlUtils.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlUtils.java
@@ -175,9 +175,9 @@ public final class XmlUtils {
* @param o The object being encoded.
* @param trim Trim the text before serializing it.
* @param preserveWhitespace
- * Specifies whether we're in preserve-whitespace mode.
- * (e.g. {@link XmlFormat#MIXED_PWS} or {@link XmlFormat#TEXT_PWS}.
- * If <jk>true</jk>, leading and trailing whitespace characters will be encoded.
+ * Specifies whether we're in preserve-whitespace mode.
+ * (e.g. {@link XmlFormat#MIXED_PWS} or {@link XmlFormat#TEXT_PWS}.
+ * If <jk>true</jk>, leading and trailing whitespace characters will be encoded.
* @return The same writer passed in.
* @throws IOException Thrown from the writer.
*/
@@ -309,8 +309,9 @@ public final class XmlUtils {
*
* @param w The writer to send the output to.
* @param o The object being encoded.
- * @param trim Trim the text before serializing it.
- * If <jk>true</jk>, leading and trailing whitespace characters will be encoded.
+ * @param trim
+ * Trim the text before serializing it.
+ * If <jk>true</jk>, leading and trailing whitespace characters will be encoded.
* @return The same writer passed in.
* @throws IOException Thrown from the writer.
*/
@@ -478,6 +479,8 @@ public final class XmlUtils {
/**
* Find the namespace given a list of <ja>@Xml</ja> and <ja>@XmlSchema</ja> annotations.
+ *
+ * <p>
* The annotations should be a child-to-parent ordering of annotations found on a class or method.
*
* @param xmls The list of <ja>@Xml</ja> annotations.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/XmlWriter.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/XmlWriter.java b/juneau-core/src/main/java/org/apache/juneau/xml/XmlWriter.java
index 93d6248..509b6a2 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/XmlWriter.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/XmlWriter.java
@@ -135,6 +135,8 @@ public class XmlWriter extends SerializerWriter {
/**
* Closes a tag.
+ *
+ * <p>
* Shortcut for <code>append(<js>'>'</js>);</code>
*
* @return This object (for method chaining).
@@ -147,6 +149,8 @@ public class XmlWriter extends SerializerWriter {
/**
* Closes an empty tag.
+ *
+ * <p>
* Shortcut for <code>append(<js>'/'</js>).append(<js>'>'</js>);</code>
*
* @return This object (for method chaining).
@@ -534,8 +538,8 @@ public class XmlWriter extends SerializerWriter {
* Serializes and encodes the specified object as valid XML text.
*
* @param o The object being serialized.
- * @param preserveWhitespace If <jk>true</jk>, then we're serializing {@link XmlFormat#MIXED_PWS} or
- * {@link XmlFormat#TEXT_PWS} content.
+ * @param preserveWhitespace
+ * If <jk>true</jk>, then we're serializing {@link XmlFormat#MIXED_PWS} or {@link XmlFormat#TEXT_PWS} content.
* @return This object (for method chaining).
* @throws IOException
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
index 596151d..3d6fa02 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/Xml.java
@@ -19,8 +19,10 @@ import java.lang.annotation.*;
/**
* Annotation for specifying various XML options for the XML and RDF/XML serializers.
+ *
* <p>
* Can be applied to Java packages, types, fields, and methods.
+ *
* <p>
* Can be used for the following:
* <ul>
@@ -37,6 +39,7 @@ public @interface Xml {
/**
* Sets the name of the XML child elements for bean properties of type collection and array.
+ *
* <p>
* Applies only to collection and array bean properties.
*
@@ -47,9 +50,9 @@ public @interface Xml {
* <jk>public</jk> String[] <jf>children</jf> = {<js>"foo"</js>,<js>"bar"</js>};
* }
* </p>
+ *
* <p>
* Without the <ja>@Xml</ja> annotation, serializing this bean as XML would have produced the following...
- * </p>
* <p class='bcode'>
* <xt><object></xt>
* <xt><children></xt>
@@ -58,9 +61,9 @@ public @interface Xml {
* <xt></children></xt>
* <xt></object></xt>
* </p>
+ *
* <p>
* With the annotations, serializing this bean as XML produces the following...
- * </p>
* <p class='bcode'>
* <xt><object></xt>
* <xt><children></xt>
@@ -74,6 +77,7 @@ public @interface Xml {
/**
* Sets the XML prefix of this property or class.
+ *
* <ul class='spaced-list'>
* <li>
* When applied to a {@link ElementType#TYPE}, namespace is applied to all properties in the class, and all
@@ -82,6 +86,7 @@ public @interface Xml {
* When applied to bean properties on {@link ElementType#METHOD} and {@link ElementType#FIELD}, applies
* to the bean property.
* </ul>
+ *
* <p>
* Must either be matched to a {@link #namespace()} annotation on the same object, parent object, or a
* {@link XmlNs} with the same name through the {@link XmlSchema#xmlNs()} annotation on the package.
@@ -90,6 +95,7 @@ public @interface Xml {
/**
* Sets the namespace URI of this property or class.
+ *
* <p>
* Must be matched with a {@link #prefix()} annotation on this object, a parent object, or a {@link XmlNs} with the
* same name through the {@link XmlSchema#xmlNs()} annotation on the package.
@@ -120,9 +126,9 @@ public @interface Xml {
* <jk>public</jk> String[] <jf>children</jf> = <js>"foo"</js>,<js>"bar"</js>};
* }
* </p>
+ *
* <p>
* Without the <ja>@Xml</ja> annotations, serializing this bean as XML would have produced the following...
- * </p>
* <p class='bcode'>
* <xt><object</xt> <xa>href</xa>=<js>'http://foo'</js><xt>></xt>
* <xt><f1></xt>123<xt></f1></xt>
@@ -132,9 +138,9 @@ public @interface Xml {
* <xt></children></xt>
* <xt></object></xt>
* </p>
+ *
* <p>
* With the annotations, serializing this bean as XML produces the following...
- * </p>
* <p class='bcode'>
* <xt><object</xt> <xa>f1</xa>=<js>'123'</js><xt>></xt>
* <xt><href></xt>http://foo<xt></href></xt>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlFormat.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlFormat.java b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlFormat.java
index 690f0ac..f536b7c 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlFormat.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlFormat.java
@@ -19,8 +19,10 @@ public enum XmlFormat {
/**
* Normal formatting (default).
+ *
* <p>
* On a bean class, implies {@link #ELEMENTS} meaning bean properties will be serialized as child elements by default.
+ *
* <p>
* On a bean property, implies {@link #ELEMENT} meaning the bean property will be serialized as a child element.
*/
@@ -28,8 +30,10 @@ public enum XmlFormat {
/**
* Render a bean property as an attribute instead of an element.
+ *
* <p>
* Only applicable for bean properties, not bean classes.
+ *
* <p>
* Can only be applied to properties (methods/fields) of class types that can be convertible to <code>Strings</code>.
*/
@@ -37,8 +41,10 @@ public enum XmlFormat {
/**
* Render property as attributes instead of an element.
+ *
* <p>
* On a bean class, implies bean properties will be serialized as attributes instead of child elements by default.
+ *
* <p>
* On bean properties, implies that the bean property value itself should be serialized as attributes on the bean
* element.
@@ -49,8 +55,10 @@ public enum XmlFormat {
/**
* Render property as an element instead of an attribute.
+ *
* <p>
* Only applicable for bean properties, not bean classes.
+ *
* <p>
* Used to override the behavior of the {@link #ATTRS} format applied to the bean class.
*/
@@ -58,11 +66,14 @@ public enum XmlFormat {
/**
* Render property value directly as the contents of the element.
+ *
* <p>
* On a bean class, implies that bean properties will be serialized as child elements.
* Note that this is equivalent to {@link #DEFAULT}.
+ *
* <p>
* Only applicable for objects of type array/Collection.
+ *
* <p>
* On a bean property, implies that the bean property value itself should be serialized as child elements of the
* bean element.
@@ -71,10 +82,13 @@ public enum XmlFormat {
/**
* Same as {@link #ELEMENTS} except primitive types (e.g. string/boolean/number/null) are not wrapped in elements.
+ *
* <p>
* Only applicable for bean properties, not bean classes.
+ *
* <p>
* Only applicable for objects of type array/Collection.
+ *
* <p>
* Use of this format may cause data type loss during parsing if the types cannot be inferred through reflection.
*/
@@ -82,6 +96,7 @@ public enum XmlFormat {
/**
* Same as {@link XmlFormat#MIXED}, but whitespace in text nodes are not trimmed during parsing.
+ *
* <p>
* An example use is HTML5 <xt><pre></xt> where whitespace should not be discarded.
*/
@@ -89,10 +104,13 @@ public enum XmlFormat {
/**
* Render property value as the text content of the element.
+ *
* <p>
* Similar to {@link #MIXED} but value must be a single value, not a collection.
+ *
* <p>
* Only applicable for bean properties, not bean classes.
+ *
* <p>
* Use of this format may cause data type loss during parsing if the type cannot be inferred through reflection.
*/
@@ -104,12 +122,14 @@ public enum XmlFormat {
TEXT_PWS,
/**
- * Same as {@link #TEXT} except the content is expected to be fully-formed XML that will
- * get serialized as-is.
+ * Same as {@link #TEXT} except the content is expected to be fully-formed XML that will get serialized as-is.
+ *
* <p>
* During parsing, this XML text will be re-serialized and set on the property.
+ *
* <p>
* Only applicable for bean properties, not bean classes.
+ *
* <p>
* Use of this format may cause data type loss during parsing if the type cannot be inferred through reflection.
*/
@@ -117,6 +137,7 @@ public enum XmlFormat {
/**
* Prevents collections and arrays from being enclosed in <xt><array></xt> elements.
+ *
* <p>
* Can only be applied to properties (methods/fields) of type collection or array, or collection classes.
*/
@@ -124,15 +145,17 @@ public enum XmlFormat {
/**
* Identifies a void element.
+ *
* <p>
* Only applicable for bean classes.
+ *
* <p>
* Identifies an element that never contains content.
+ *
* <p>
- * The main difference in behavior is how non-void empty elements are handled
- * in the HTML serializer.
- * Void elements are serialized as collapsed nodes (e.g. <js>"<br/>"</js>)
- * whereas non-void empty elements are serialized with an end tag (e.g. "<p></p>").
+ * The main difference in behavior is how non-void empty elements are handled in the HTML serializer.
+ * Void elements are serialized as collapsed nodes (e.g. <js>"<br/>"</js>) whereas non-void empty elements are
+ * serialized with an end tag (e.g. "<p></p>").
*/
VOID;
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlNs.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlNs.java b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlNs.java
index d42412c..e7f565c 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlNs.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlNs.java
@@ -18,6 +18,7 @@ import java.lang.annotation.*;
/**
* Namespace name/URL mapping pair.
+ *
* <p>
* Used to identify a namespace/URI pair on a {@link XmlSchema#xmlNs()} annotation.
*/
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f400b0c0/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
----------------------------------------------------------------------
diff --git a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
index 04a9def..d5f707c 100644
--- a/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
+++ b/juneau-core/src/main/java/org/apache/juneau/xml/annotation/XmlSchema.java
@@ -28,6 +28,7 @@ public @interface XmlSchema {
/**
* Sets the default XML prefix for all classes in this and child packages.
+ *
* <p>
* Must either be matched with a {@link #namespace()} annotation, or an {@link #xmlNs()} mapping with the same
* {@link XmlNs#prefix} value.
@@ -36,6 +37,7 @@ public @interface XmlSchema {
/**
* Sets the default XML namespace URL for all classes in this and child packages.
+ *
* <p>
* Must either be matched with a {@link #prefix()} annotation, or an {@link #xmlNs()} mapping with the same
* {@link XmlNs#namespaceURI} value.
@@ -44,9 +46,11 @@ public @interface XmlSchema {
/**
* Lists all namespace mappings to be used on all classes within this package.
+ *
* <p>
* The purpose of this annotation is to allow namespace mappings to be defined in a single location and referred
* to by name through just the {@link Xml#prefix()} annotation.
+ *
* <p>
* Inherited by child packages.
*
@@ -66,6 +70,7 @@ public @interface XmlSchema {
* <jk>package</jk> org.apache.juneau.examples.addressbook;
* <jk>import</jk> org.apache.juneau.xml.annotation.*;
* </p>
+ *
* <p>
* Class in package using defined namespaces...
* <p class='bcode'>