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/28 11:35:57 UTC
[maven-shared-utils] branch 840 created (now 9c76ca7)
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a change to branch 840
in repository https://gitbox.apache.org/repos/asf/maven-shared-utils.git.
at 9c76ca7 deprecate close methods since we require Java 7+
This branch includes the following new commits:
new 9c76ca7 deprecate close methods since we require Java 7+
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[maven-shared-utils] 01/01: deprecate close methods since we
require Java 7+
Posted by el...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch 840
in repository https://gitbox.apache.org/repos/asf/maven-shared-utils.git
commit 9c76ca7bea3c9a5f367472ec275ee8391e84c49e
Author: Elliotte Rusty Harold <el...@ibiblio.org>
AuthorDate: Thu May 28 07:35:37 2020 -0400
deprecate close methods since we require Java 7+
---
.../org/apache/maven/shared/utils/io/IOUtil.java | 55 ++++++++++++----------
1 file changed, 30 insertions(+), 25 deletions(-)
diff --git a/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java b/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java
index c0e421d..b0cb118 100644
--- a/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java
+++ b/src/main/java/org/apache/maven/shared/utils/io/IOUtil.java
@@ -43,41 +43,36 @@ import java.nio.channels.Channel;
* copying between sources (<code>InputStream</code>, <code>Reader</code>, <code>String</code> and
* <code>byte[]</code>) and destinations (<code>OutputStream</code>, <code>Writer</code>,
* <code>String</code> and <code>byte[]</code>).
- * </p>
- * <p/>
+ *
* <p>Unless otherwise noted, these <code>copy</code> methods do <em>not</em> flush or close the
* streams. Often, doing so would require making non-portable assumptions about the streams' origin
* and further use. This means that both streams' <code>close()</code> methods must be called after
* copying. if one omits this step, then the stream resources (sockets, file descriptors) are
* released when the associated Stream is garbage-collected. It is not a good idea to rely on this
- * mechanism. For a good overview of the distinction between "memory management" and "resource
- * management", see <a href="http://www.unixreview.com/articles/1998/9804/9804ja/ja.htm">this
- * UnixReview article</a></p>
- * <p/>
+ * mechanism.</p>
+ *
* <p>For each <code>copy</code> method, a variant is provided that allows the caller to specify the
* buffer size (the default is 4k). As the buffer size can have a fairly large impact on speed, this
* may be worth tweaking. Often "large buffer -> faster" does not hold, even for large data
* transfers.</p>
- * <p/>
* <p>For byte-to-char methods, a <code>copy</code> variant allows the encoding to be selected
* (otherwise the platform default is used).</p>
- * <p/>
* <p>The <code>copy</code> methods use an internal buffer when copying. It is therefore advisable
* <em>not</em> to deliberately wrap the stream arguments to the <code>copy</code> methods in
* <code>Buffered*</code> streams. For example, don't do the
* following:</p>
- * <p/>
+ * <p>
* <code>copy( new BufferedInputStream( in ), new BufferedOutputStream( out ) );</code>
- * <p/>
+ * </p>
* <p>The rationale is as follows:</p>
- * <p/>
+ *
* <p>Imagine that an InputStream's read() is a very expensive operation, which would usually suggest
* wrapping in a BufferedInputStream. The BufferedInputStream works by issuing infrequent
* {@link java.io.InputStream#read(byte[] b, int off, int len)} requests on the underlying InputStream, to
* fill an internal buffer, from which further <code>read</code> requests can inexpensively get
* their data (until the buffer runs out).</p>
* <p>However, the <code>copy</code> methods do the same thing, keeping an internal buffer,
- * populated by {@link InputStream#read(byte[] b, int off, int len)} requests. Having two buffers
+ * populated by {@link InputStream#read(byte[] b, int offset, int len)} requests. Having two buffers
* (or three if the destination stream is also buffered) is pointless, and the unnecessary buffer
* management hurts performance slightly (about 3%, according to some simple experiments).</p>
*
@@ -133,9 +128,9 @@ public final class IOUtil
/**
* Copy bytes from an <code>InputStream</code> to an <code>OutputStream</code>.
- * @param input The input size.
- * @param output The resulting output.
- * @throws IOException in case of an error.
+ * @param input the input size
+ * @param output the resulting output
+ * @throws IOException in case of an error
*/
public static void copy( @Nonnull final InputStream input, @Nonnull final OutputStream output )
throws IOException
@@ -146,10 +141,10 @@ public final class IOUtil
/**
* Copy bytes from an <code>InputStream</code> to an <code>OutputStream</code>.
*
- * @param input The input size.
- * @param output The resulting output.
- * @param bufferSize Size of internal buffer to use.
- * @throws IOException in case of an error.
+ * @param input the input size
+ * @param output the resulting output
+ * @param bufferSize size of internal buffer to use
+ * @throws IOException in case of an error
*/
public static void copy( @Nonnull final InputStream input, @Nonnull final OutputStream output,
final int bufferSize )
@@ -759,8 +754,8 @@ public final class IOUtil
/**
* Closes a {@code Channel} suppressing any {@code IOException}.
* <p>
- * <b>Note:</b><br/>The usecase justifying this method is a shortcoming of the Java language up to but not including
- * Java 7. For any code targetting Java 7 or later use of this method is highly discouraged and the
+ * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
+ * Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
* {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
* {@code IOException}s get suppressed incorrectly.
* <strong>You must close all resources in use inside the {@code try} block to not suppress exceptions in the
@@ -844,7 +839,9 @@ public final class IOUtil
* </p>
*
* @param channel The channel to close or {@code null}.
+ * @deprecated use try-with-resources
*/
+ @Deprecated
public static void close( @Nullable Channel channel )
{
try
@@ -863,7 +860,7 @@ public final class IOUtil
/**
* Closes an {@code InputStream} suppressing any {@code IOException}.
* <p>
- * <b>Note:</b><br/>The usecase justifying this method is a shortcoming of the Java language up to but not including
+ * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
* Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
* {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
* {@code IOException}s get suppressed incorrectly.
@@ -948,7 +945,9 @@ public final class IOUtil
* </p>
*
* @param inputStream The stream to close or {@code null}.
+ * @deprecated use try-with-resources
*/
+ @Deprecated
public static void close( @Nullable InputStream inputStream )
{
try
@@ -967,7 +966,7 @@ public final class IOUtil
/**
* Closes an {@code OutputStream} suppressing any {@code IOException}.
* <p>
- * <b>Note:</b><br/>The usecase justifying this method is a shortcoming of the Java language up to but not including
+ * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
* Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
* {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
* {@code IOException}s get suppressed incorrectly.
@@ -1052,7 +1051,9 @@ public final class IOUtil
* </p>
*
* @param outputStream The stream to close or {@code null}.
+ * @deprecated use try-with-resources
*/
+ @Deprecated
public static void close( @Nullable OutputStream outputStream )
{
try
@@ -1071,7 +1072,7 @@ public final class IOUtil
/**
* Closes a {@code Reader} suppressing any {@code IOException}.
* <p>
- * <b>Note:</b><br/>The usecase justifying this method is a shortcoming of the Java language up to but not including
+ * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
* Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
* {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
* {@code IOException}s get suppressed incorrectly.
@@ -1156,7 +1157,9 @@ public final class IOUtil
* </p>
*
* @param reader The reader to close or {@code null}.
+ * @deprecated use try-with-resources
*/
+ @Deprecated
public static void close( @Nullable Reader reader )
{
try
@@ -1175,7 +1178,7 @@ public final class IOUtil
/**
* Closes a {@code Writer} suppressing any {@code IOException}.
* <p>
- * <b>Note:</b><br/>The usecase justifying this method is a shortcoming of the Java language up to but not including
+ * <b>Note:</b> The use case justifying this method is a shortcoming of the Java language up to but not including
* Java 7. For any code targeting Java 7 or later use of this method is highly discouraged and the
* {@code try-with-resources} statement should be used instead. Care must be taken to not use this method in a way
* {@code IOException}s get suppressed incorrectly.
@@ -1260,7 +1263,9 @@ public final class IOUtil
* </p>
*
* @param writer The writer to close or {@code null}.
+ * @deprecated use try-with-resources
*/
+ @Deprecated
public static void close( @Nullable Writer writer )
{
try