You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by el...@apache.org on 2020/05/29 11:50:21 UTC
[maven-shared-utils] branch master updated: [MSHARED-860] deprecate
constants that are now available in Java 7+ (#42)
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-shared-utils.git
The following commit(s) were added to refs/heads/master by this push:
new 660fd80 [MSHARED-860] deprecate constants that are now available in Java 7+ (#42)
660fd80 is described below
commit 660fd805ad8da2b9063502e944968fd7166fdc63
Author: Elliotte Rusty Harold <el...@users.noreply.github.com>
AuthorDate: Fri May 29 07:50:11 2020 -0400
[MSHARED-860] deprecate constants that are now available in Java 7+ (#42)
* deprecate constants that are now available in Java 7+
* update URLs
* fix some api doc
---
.../apache/maven/shared/utils/ReaderFactory.java | 81 ++++++++++++----------
.../apache/maven/shared/utils/WriterFactory.java | 78 ++++++++++++---------
2 files changed, 93 insertions(+), 66 deletions(-)
diff --git a/src/main/java/org/apache/maven/shared/utils/ReaderFactory.java b/src/main/java/org/apache/maven/shared/utils/ReaderFactory.java
index 5103219..4ec103a 100644
--- a/src/main/java/org/apache/maven/shared/utils/ReaderFactory.java
+++ b/src/main/java/org/apache/maven/shared/utils/ReaderFactory.java
@@ -40,7 +40,7 @@ import javax.annotation.Nonnull;
*
* @author <a href="mailto:hboutemy@apache.org">Hervé Boutemy</a>
* @see java.nio.charset.Charset
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported encodings</a>
*/
public class ReaderFactory
{
@@ -48,16 +48,18 @@ public class ReaderFactory
* ISO Latin Alphabet #1, also known as ISO-LATIN-1.
* Every implementation of the Java platform is required to support this character encoding.
*
- * @see java.nio.charset.Charset
+ * @deprecated use {@code java.nio.charset.StandardCharset.ISO_8859_1}
*/
+ @Deprecated
public static final String ISO_8859_1 = "ISO-8859-1";
/**
* Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
* Every implementation of the Java platform is required to support this character encoding.
*
- * @see java.nio.charset.Charset
+ * @deprecated use {@code java.nio.charset.StandardCharset.US_ASCII}
*/
+ @Deprecated
public static final String US_ASCII = "US-ASCII";
/**
@@ -65,32 +67,36 @@ public class ReaderFactory
* order accepted on input, big-endian used on output).
* Every implementation of the Java platform is required to support this character encoding.
*
- * @see java.nio.charset.Charset
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16}
*/
+ @Deprecated
public static final String UTF_16 = "UTF-16";
/**
* Sixteen-bit Unicode Transformation Format, big-endian byte order.
* Every implementation of the Java platform is required to support this character encoding.
*
- * @see java.nio.charset.Charset
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16BE}
*/
+ @Deprecated
public static final String UTF_16BE = "UTF-16BE";
/**
* Sixteen-bit Unicode Transformation Format, little-endian byte order.
* Every implementation of the Java platform is required to support this character encoding.
*
- * @see java.nio.charset.Charset
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16LE}
*/
+ @Deprecated
public static final String UTF_16LE = "UTF-16LE";
/**
* Eight-bit Unicode Transformation Format.
* Every implementation of the Java platform is required to support this character encoding.
*
- * @see java.nio.charset.Charset
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_8}
*/
+ @Deprecated
public static final String UTF_8 = "UTF-8";
/**
@@ -101,9 +107,9 @@ public class ReaderFactory
/**
* Create a new Reader with XML encoding detection rules.
*
- * @param in not null input stream.
- * @return an XML reader instance for the input stream.
- * @throws IOException if any.
+ * @param in not null input stream
+ * @return an XML reader instance for the input stream
+ * @throws IOException if any
* @see XmlStreamReader
*/
public static Reader newXmlReader( @Nonnull InputStream in )
@@ -115,9 +121,9 @@ public class ReaderFactory
/**
* Create a new Reader with XML encoding detection rules.
*
- * @param file not null file.
- * @return an XML reader instance for the input file.
- * @throws IOException if any.
+ * @param file not null file
+ * @return an XML reader instance for the input file
+ * @throws IOException if any
* @see XmlStreamReader
*/
public static Reader newXmlReader( @Nonnull File file )
@@ -129,9 +135,9 @@ public class ReaderFactory
/**
* Create a new Reader with XML encoding detection rules.
*
- * @param url not null url.
- * @return an XML reader instance for the input url.
- * @throws IOException if any.
+ * @param url not null url
+ * @return an XML reader instance for the input URL
+ * @throws IOException if any
* @see XmlStreamReader
*/
public static Reader newXmlReader( @Nonnull URL url )
@@ -141,13 +147,15 @@ public class ReaderFactory
}
/**
- * Create a new Reader with default plaform encoding.
+ * Create a new Reader with default platform encoding.
*
* @param file not null file.
- * @return a reader instance for the input file using the default platform charset.
- * @throws FileNotFoundException if any.
+ * @return a reader instance for the input file using the default platform character set
+ * @throws FileNotFoundException if any
* @see java.nio.charset.Charset#defaultCharset()
+ * @deprecated always specify an encoding. Do not depend on the default platform character set.
*/
+ @Deprecated
public static Reader newPlatformReader( @Nonnull File file )
throws FileNotFoundException
{
@@ -157,11 +165,12 @@ public class ReaderFactory
/**
* Create a new Reader with specified encoding.
*
- * @param in not null input stream.
- * @param encoding not null supported encoding.
- * @return a reader instance for the input stream using the given encoding.
- * @throws UnsupportedEncodingException if any.
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @param in not null input stream
+ * @param encoding not null supported encoding
+ * @return a reader instance for the input stream using the given encoding
+ * @throws UnsupportedEncodingException if any
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
+ * encodings</a>
*/
public static Reader newReader( @Nonnull InputStream in, @Nonnull String encoding )
throws UnsupportedEncodingException
@@ -172,12 +181,13 @@ public class ReaderFactory
/**
* Create a new Reader with specified encoding.
*
- * @param file not null file.
- * @param encoding not null supported encoding.
- * @return a reader instance for the input file using the given encoding.
- * @throws FileNotFoundException if any.
- * @throws UnsupportedEncodingException if any.
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @param file not null file
+ * @param encoding not null supported encoding
+ * @return a reader instance for the input file using the given encoding
+ * @throws FileNotFoundException if any
+ * @throws UnsupportedEncodingException if any
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
+ * encodings</a>
*/
public static Reader newReader( @Nonnull File file, @Nonnull String encoding )
throws FileNotFoundException, UnsupportedEncodingException
@@ -188,11 +198,12 @@ public class ReaderFactory
/**
* Create a new Reader with specified encoding.
*
- * @param url not null url.
- * @param encoding not null supported encoding.
- * @return a reader instance for the input url using the given encoding.
- * @throws IOException if any.
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @param url not null URL
+ * @param encoding not null supported encoding
+ * @return a reader instance for the input URL using the given encoding
+ * @throws IOException if any
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
+ * encodings</a>
*/
public static Reader newReader( @Nonnull URL url, @Nonnull String encoding )
throws IOException
diff --git a/src/main/java/org/apache/maven/shared/utils/WriterFactory.java b/src/main/java/org/apache/maven/shared/utils/WriterFactory.java
index fb2f213..e81ccee 100644
--- a/src/main/java/org/apache/maven/shared/utils/WriterFactory.java
+++ b/src/main/java/org/apache/maven/shared/utils/WriterFactory.java
@@ -39,51 +39,63 @@ import javax.annotation.Nonnull;
*
* @author Hervé Boutemy
* @see java.nio.charset.Charset
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported encodings</a>
*/
public class WriterFactory
{
/**
* ISO Latin Alphabet #1, also known as ISO-LATIN-1.
* Every implementation of the Java platform is required to support this character encoding.
- * @see java.nio.charset.Charset
+ *
+ * @deprecated use {@code java.nio.charset.StandardCharset.ISO_8859_1}
*/
+ @Deprecated
public static final String ISO_8859_1 = "ISO-8859-1";
/**
* Seven-bit ASCII, also known as ISO646-US, also known as the Basic Latin block of the Unicode character set.
* Every implementation of the Java platform is required to support this character encoding.
- * @see java.nio.charset.Charset
+ *
+ * @deprecated use {@code java.nio.charset.StandardCharset.US_ASCII}
*/
+ @Deprecated
public static final String US_ASCII = "US-ASCII";
/**
* Sixteen-bit Unicode Transformation Format, byte order specified by a mandatory initial byte-order mark (either
* order accepted on input, big-endian used on output).
* Every implementation of the Java platform is required to support this character encoding.
- * @see java.nio.charset.Charset
+ *
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16}
*/
+ @Deprecated
public static final String UTF_16 = "UTF-16";
/**
* Sixteen-bit Unicode Transformation Format, big-endian byte order.
* Every implementation of the Java platform is required to support this character encoding.
- * @see java.nio.charset.Charset
+ *
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16BE}
*/
+ @Deprecated
public static final String UTF_16BE = "UTF-16BE";
/**
* Sixteen-bit Unicode Transformation Format, little-endian byte order.
* Every implementation of the Java platform is required to support this character encoding.
- * @see java.nio.charset.Charset
+ *
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_16LE}
*/
+ @Deprecated
public static final String UTF_16LE = "UTF-16LE";
/**
* Eight-bit Unicode Transformation Format.
* Every implementation of the Java platform is required to support this character encoding.
- * @see java.nio.charset.Charset
+ *
+ * @deprecated use {@code java.nio.charset.StandardCharset.UTF_8}
*/
+ @Deprecated
public static final String UTF_8 = "UTF-8";
/**
@@ -94,9 +106,9 @@ public class WriterFactory
/**
* Create a new Writer with XML encoding detection rules.
*
- * @param out not null output stream.
- * @return an XML writer instance for the output stream.
- * @throws IOException if any.
+ * @param out not null output stream
+ * @return an XML writer instance for the output stream
+ * @throws IOException if any
* @see XmlStreamWriter
*/
public static XmlStreamWriter newXmlWriter( @Nonnull OutputStream out )
@@ -108,9 +120,9 @@ public class WriterFactory
/**
* Create a new Writer with XML encoding detection rules.
*
- * @param file not null file.
- * @return an XML writer instance for the output file.
- * @throws IOException if any.
+ * @param file not null file
+ * @return an XML writer instance for the output file
+ * @throws IOException if any
* @see XmlStreamWriter
*/
public static XmlStreamWriter newXmlWriter( @Nonnull File file )
@@ -122,10 +134,11 @@ public class WriterFactory
/**
* Create a new Writer with default platform encoding.
*
- * @param out not null output stream.
- * @return a writer instance for the output stream using the default platform charset.
- * @see java.nio.charset.Charset#defaultCharset()
+ * @param out not null output stream
+ * @return a writer instance for the output stream using the default platform charset
+ * @deprecated always specify an encoding. Do not depend on the default platform character set.
*/
+ @Deprecated
public static Writer newPlatformWriter( @Nonnull OutputStream out )
{
return new OutputStreamWriter( out );
@@ -134,11 +147,12 @@ public class WriterFactory
/**
* Create a new Writer with default platform encoding.
*
- * @param file not null file.
- * @return a writer instance for the output file using the default platform charset.
- * @throws IOException if any.
- * @see java.nio.charset.Charset#defaultCharset()
+ * @param file not null file
+ * @return a writer instance for the output file using the default platform charset
+ * @throws IOException if any
+ * @deprecated always specify an encoding. Do not depend on the default platform character set.
*/
+ @Deprecated
public static Writer newPlatformWriter( @Nonnull File file )
throws IOException
{
@@ -148,11 +162,12 @@ public class WriterFactory
/**
* Create a new Writer with specified encoding.
*
- * @param out not null output stream.
- * @param encoding not null supported encoding.
- * @return a writer instance for the output stream using the given encoding.
- * @throws UnsupportedEncodingException if any.
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @param out not null output stream
+ * @param encoding not null supported encoding
+ * @return a writer instance for the output stream using the given encoding
+ * @throws UnsupportedEncodingException if any
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
+ * encodings</a>
*/
public static Writer newWriter( @Nonnull OutputStream out, @Nonnull String encoding )
throws UnsupportedEncodingException
@@ -163,12 +178,13 @@ public class WriterFactory
/**
* Create a new Writer with specified encoding.
*
- * @param file not null file.
- * @param encoding not null supported encoding.
- * @return a writer instance for the output file using the given encoding.
- * @throws UnsupportedEncodingException if any.
- * @throws FileNotFoundException if any.
- * @see <a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">Supported encodings</a>
+ * @param file not null file
+ * @param encoding not null supported encoding
+ * @return a writer instance for the output file using the given encoding
+ * @throws UnsupportedEncodingException if any
+ * @throws FileNotFoundException if any
+ * @see <a href="https://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html">Supported
+ * encodings</a>
*/
public static Writer newWriter( @Nonnull File file, @Nonnull String encoding )
throws UnsupportedEncodingException, FileNotFoundException