This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-io.git
The following commit(s) were added to refs/heads/master by this push:
new 42574b3b Javadoc
42574b3b is described below
commit 42574b3b442e42d898ea8304f42e66b24e0559f8
Author: Gary Gregory <gardgreg...@gmail.com>
AuthorDate: Tue Jun 21 07:47:51 2022 -0400
Javadoc
---
.../apache/commons/io/input/XmlStreamReader.java | 91 ++++++++++++++++------
1 file changed, 68 insertions(+), 23 deletions(-)
diff --git a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
index 5a490bfe..d1e39f49 100644
--- a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
+++ b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
@@ -71,6 +71,7 @@ import org.apache.commons.io.IOUtils;
* @since 2.0
*/
public class XmlStreamReader extends Reader {
+
private static final String UTF_8 = "UTF-8";
private static final String US_ASCII = "US-ASCII";
@@ -135,7 +136,7 @@ public class XmlStreamReader extends Reader {
"Invalid encoding, CT-MIME [{0}] CT-Enc [{1}] BOM [{2}] XML guess
[{3}] XML prolog [{4}], Invalid MIME";
/**
- * Returns charset parameter value, NULL if not present, NULL if
+ * Gets the charset parameter value, NULL if not present, NULL if
* httpContentType is NULL.
*
* @param httpContentType the HTTP content type
@@ -156,7 +157,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Returns MIME type or NULL if httpContentType is NULL.
+ * Gets the MIME type or NULL if httpContentType is NULL.
*
* @param httpContentType the HTTP content type
* @return The mime content type
@@ -176,7 +177,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Returns the encoding declared in the <?xml encoding=...?>, NULL if none.
+ * Gets the encoding declared in the <?xml encoding=...?>, NULL if none.
*
* @param inputStream InputStream to create the reader from.
* @param guessedEnc guessed encoding
@@ -230,7 +231,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Indicates if the MIME type belongs to the APPLICATION XML family.
+ * Tests if the MIME type belongs to the APPLICATION XML family.
*
* @param mime The mime type
* @return true if the mime type belongs to the APPLICATION XML family,
@@ -241,11 +242,11 @@ public class XmlStreamReader extends Reader {
(mime.equals("application/xml") ||
mime.equals("application/xml-dtd") ||
mime.equals("application/xml-external-parsed-entity") ||
- mime.startsWith("application/") && mime.endsWith("+xml"));
+ mime.startsWith("application/") && mime.endsWith("+xml"));
}
/**
- * Indicates if the MIME type belongs to the TEXT XML family.
+ * Tests if the MIME type belongs to the TEXT XML family.
*
* @param mime The mime type
* @return true if the mime type belongs to the TEXT XML family,
@@ -255,7 +256,7 @@ public class XmlStreamReader extends Reader {
return mime != null &&
(mime.equals("text/xml") ||
mime.equals("text/xml-external-parsed-entity") ||
- mime.startsWith("text/") && mime.endsWith("+xml"));
+ mime.startsWith("text/") && mime.endsWith("+xml"));
}
private final Reader reader;
@@ -265,13 +266,15 @@ public class XmlStreamReader extends Reader {
private final String defaultEncoding;
/**
- * Creates a Reader for a File.
+ * Constructs a Reader for a File.
* <p>
* It looks for the UTF-8 BOM first, if none sniffs the XML prolog charset,
* if this is also missing defaults to UTF-8.
+ * </p>
* <p>
* It does a lenient charset encoding detection, check the constructor with
* the lenient parameter for details.
+ * </p>
*
* @param file File to create a Reader from.
* @throws IOException thrown if there is a problem reading the file.
@@ -281,12 +284,14 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader for a raw InputStream.
+ * Constructs a Reader for a raw InputStream.
* <p>
* It follows the same logic used for files.
+ * </p>
* <p>
* It does a lenient charset encoding detection, check the constructor with
* the lenient parameter for details.
+ * </p>
*
* @param inputStream InputStream to create a Reader from.
* @throws IOException thrown if there is a problem reading the stream.
@@ -296,24 +301,31 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader for a raw InputStream.
+ * Constructs a Reader for a raw InputStream.
* <p>
* It follows the same logic used for files.
+ * </p>
* <p>
* If lenient detection is indicated and the detection above fails as per
* specifications it then attempts the following:
+ * </p>
* <p>
* If the content type was 'text/html' it replaces it with 'text/xml' and
* tries the detection again.
+ * </p>
* <p>
* Else if the XML prolog had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else if the content type had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else 'UTF-8' is used.
+ * </p>
* <p>
* If lenient detection is indicated an XmlStreamReaderException is never
* thrown.
+ * </p>
*
* @param inputStream InputStream to create a Reader from.
* @param lenient indicates if the charset encoding detection should be
@@ -327,24 +339,31 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader for a raw InputStream.
+ * Constructs a Reader for a raw InputStream.
* <p>
* It follows the same logic used for files.
+ * </p>
* <p>
* If lenient detection is indicated and the detection above fails as per
* specifications it then attempts the following:
+ * </p>
* <p>
* If the content type was 'text/html' it replaces it with 'text/xml' and
* tries the detection again.
+ * </p>
* <p>
* Else if the XML prolog had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else if the content type had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else 'UTF-8' is used.
+ * </p>
* <p>
* If lenient detection is indicated an XmlStreamReaderException is never
* thrown.
+ * </p>
*
* @param inputStream InputStream to create a Reader from.
* @param lenient indicates if the charset encoding detection should be
@@ -366,16 +385,18 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader using an InputStream and the associated content-type
+ * Constructs a Reader using an InputStream and the associated content-type
* header.
* <p>
* First it checks if the stream has BOM. If there is not BOM checks the
* content-type encoding. If there is not content-type encoding checks the
* XML prolog encoding. If there is not XML prolog encoding uses the
default
* encoding mandated by the content-type MIME type.
+ * </p>
* <p>
* It does a lenient charset encoding detection, check the constructor with
* the lenient parameter for details.
+ * </p>
*
* @param inputStream InputStream to create the reader from.
* @param httpContentType content-type header to use for the resolution of
@@ -388,28 +409,35 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader using an InputStream and the associated content-type
+ * Constructs a Reader using an InputStream and the associated content-type
* header. This constructor is lenient regarding the encoding detection.
* <p>
* First it checks if the stream has BOM. If there is not BOM checks the
* content-type encoding. If there is not content-type encoding checks the
* XML prolog encoding. If there is not XML prolog encoding uses the
default
* encoding mandated by the content-type MIME type.
+ * </p>
* <p>
* If lenient detection is indicated and the detection above fails as per
* specifications it then attempts the following:
+ * </p>
* <p>
* If the content type was 'text/html' it replaces it with 'text/xml' and
* tries the detection again.
+ * </p>
* <p>
* Else if the XML prolog had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else if the content type had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else 'UTF-8' is used.
+ * </p>
* <p>
* If lenient detection is indicated an XmlStreamReaderException is never
* thrown.
+ * </p>
*
* @param inputStream InputStream to create the reader from.
* @param httpContentType content-type header to use for the resolution of
@@ -427,28 +455,35 @@ public class XmlStreamReader extends Reader {
/**
- * Creates a Reader using an InputStream and the associated content-type
+ * Constructs a Reader using an InputStream and the associated content-type
* header. This constructor is lenient regarding the encoding detection.
* <p>
* First it checks if the stream has BOM. If there is not BOM checks the
* content-type encoding. If there is not content-type encoding checks the
* XML prolog encoding. If there is not XML prolog encoding uses the
default
* encoding mandated by the content-type MIME type.
+ * </p>
* <p>
* If lenient detection is indicated and the detection above fails as per
* specifications it then attempts the following:
+ * </p>
* <p>
* If the content type was 'text/html' it replaces it with 'text/xml' and
* tries the detection again.
+ * </p>
* <p>
* Else if the XML prolog had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else if the content type had a charset encoding that encoding is used.
+ * </p>
* <p>
* Else 'UTF-8' is used.
+ * </p>
* <p>
* If lenient detection is indicated an XmlStreamReaderException is never
* thrown.
+ * </p>
*
* @param inputStream InputStream to create the reader from.
* @param httpContentType content-type header to use for the resolution of
@@ -472,13 +507,15 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader for a File.
+ * Constructs a Reader for a File.
* <p>
* It looks for the UTF-8 BOM first, if none sniffs the XML prolog charset,
* if this is also missing defaults to UTF-8.
+ * </p>
* <p>
* It does a lenient charset encoding detection, check the constructor with
* the lenient parameter for details.
+ * </p>
*
* @param file File to create a Reader from.
* @throws IOException thrown if there is a problem reading the file.
@@ -490,17 +527,20 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader using the InputStream of a URL.
+ * Constructs a Reader using the InputStream of a URL.
* <p>
* If the URL is not of type HTTP and there is not 'content-type' header in
* the fetched data it uses the same logic used for Files.
+ * </p>
* <p>
* If the URL is a HTTP Url or there is a 'content-type' header in the
* fetched data it uses the same logic used for an InputStream with
* content-type.
+ * </p>
* <p>
* It does a lenient charset encoding detection, check the constructor with
* the lenient parameter for details.
+ * </p>
*
* @param url URL to create a Reader from.
* @throws IOException thrown if there is a problem reading the stream of
@@ -512,18 +552,21 @@ public class XmlStreamReader extends Reader {
}
/**
- * Creates a Reader using the InputStream of a URLConnection.
+ * Constructs a Reader using the InputStream of a URLConnection.
* <p>
* If the URLConnection is not of type HttpURLConnection and there is not
* 'content-type' header in the fetched data it uses the same logic used
for
* files.
+ * </p>
* <p>
* If the URLConnection is a HTTP Url or there is a 'content-type' header
in
* the fetched data it uses the same logic used for an InputStream with
* content-type.
+ * </p>
* <p>
* It does a lenient charset encoding detection, check the constructor with
* the lenient parameter for details.
+ * </p>
*
* @param urlConnection URLConnection to create a Reader from.
* @param defaultEncoding The default encoding
@@ -548,7 +591,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Calculate the HTTP encoding.
+ * Calculates the HTTP encoding.
*
* @param httpContentType The HTTP content type
* @param bomEnc BOM encoding
@@ -706,7 +749,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Do lenient detection.
+ * Does lenient detection.
*
* @param httpContentType content-type header to use for the resolution of
* the charset encoding.
@@ -762,10 +805,11 @@ public class XmlStreamReader extends Reader {
}
/**
- * Returns the default encoding to use if none is set in HTTP content-type,
+ * Gets the default encoding to use if none is set in HTTP content-type,
* XML prolog and the rules based on content-type are not adequate.
* <p>
* If it is NULL the content-type based rules are used.
+ * </p>
*
* @return the default encoding to use.
*/
@@ -774,7 +818,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Returns the charset encoding of the XmlStreamReader.
+ * Gets the charset encoding of the XmlStreamReader.
*
* @return charset encoding.
*/
@@ -783,7 +827,7 @@ public class XmlStreamReader extends Reader {
}
/**
- * Process a HTTP stream.
+ * Processes a HTTP stream.
*
* @param bom BOMInputStream to detect byte order marks
* @param pis BOMInputStream to guess XML encoding
@@ -809,7 +853,8 @@ public class XmlStreamReader extends Reader {
}
/**
- * Invokes the underlying reader's {@code read(char[], int, int)} method.
+ * Reads the underlying reader's {@code read(char[], int, int)} method.
+ *
* @param buf the buffer to read the characters into
* @param offset The start offset
* @param len The number of bytes to read
