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
commit dba4132fdf77e66006f407a82b4ad6705bbe8a20
Author: Gary Gregory <garydgreg...@gmail.com>
AuthorDate: Wed May 3 19:47:49 2023 -0400
Use builder and Javadoc
---
src/main/java/org/apache/commons/io/IOUtils.java | 2 +-
.../apache/commons/io/build/AbstractOrigin.java | 8 +++-
.../apache/commons/io/input/BOMInputStream.java | 5 +++
.../io/input/BufferedFileChannelInputStream.java | 38 ++++++++--------
.../io/input/MemoryMappedFileInputStream.java | 23 +++-------
.../input/MessageDigestCalculatingInputStream.java | 5 +++
.../io/input/RandomAccessFileInputStream.java | 5 +++
.../commons/io/input/ReadAheadInputStream.java | 5 +++
.../apache/commons/io/input/ReaderInputStream.java | 5 +++
.../commons/io/input/ReversedLinesFileReader.java | 5 +++
.../java/org/apache/commons/io/input/Tailer.java | 5 +++
.../commons/io/input/UncheckedBufferedReader.java | 5 +++
.../commons/io/input/UncheckedFilterReader.java | 5 +++
.../input/UnsynchronizedBufferedInputStream.java | 7 ++-
.../input/UnsynchronizedByteArrayInputStream.java | 26 ++++++-----
.../io/input/UnsynchronizedFilterInputStream.java | 9 ++--
.../apache/commons/io/input/XmlStreamReader.java | 5 +++
.../commons/io/output/FileWriterWithEncoding.java | 5 +++
.../commons/io/output/LockableFileWriter.java | 5 +++
.../io/output/UncheckedFilterOutputStream.java | 9 +++-
.../commons/io/output/UncheckedFilterWriter.java | 49 +++++++++++++++++----
.../UnsynchronizedByteArrayOutputStream.java | 50 +++++++++++++++++++++-
.../commons/io/output/WriterOutputStream.java | 7 ++-
.../apache/commons/io/output/XmlStreamWriter.java | 5 +++
.../io/input/MemoryMappedFileInputStreamTest.java | 34 +++++++++------
.../input/UnsynchronizedFilterInputStreamTest.java | 2 +-
.../io/output/UncheckedFilterWriterTest.java | 6 +--
27 files changed, 256 insertions(+), 79 deletions(-)
diff --git a/src/main/java/org/apache/commons/io/IOUtils.java
b/src/main/java/org/apache/commons/io/IOUtils.java
index cada6f7f..194dceaa 100644
--- a/src/main/java/org/apache/commons/io/IOUtils.java
+++ b/src/main/java/org/apache/commons/io/IOUtils.java
@@ -2555,7 +2555,7 @@ public class IOUtils {
*/
public static byte[] toByteArray(final InputStream inputStream) throws
IOException {
// We use a ThresholdingOutputStream to avoid reading AND writing more
than Integer.MAX_VALUE.
- try (UnsynchronizedByteArrayOutputStream ubaOutput = new
UnsynchronizedByteArrayOutputStream();
+ try (UnsynchronizedByteArrayOutputStream ubaOutput =
UnsynchronizedByteArrayOutputStream.builder().get();
ThresholdingOutputStream thresholdOutput = new
ThresholdingOutputStream(Integer.MAX_VALUE, os -> {
throw new IllegalArgumentException(String.format("Cannot read
more than %,d into a byte array", Integer.MAX_VALUE));
}, os -> ubaOutput)) {
diff --git a/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
b/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
index 82cafc0e..eadbb246 100644
--- a/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
+++ b/src/main/java/org/apache/commons/io/build/AbstractOrigin.java
@@ -70,7 +70,7 @@ public abstract class AbstractOrigin<T, B extends
AbstractOrigin<T, B>> extends
/**
* A {@link File} origin.
* <p>
- * Starting from this origin, you can get a byte array, a file, an input
stream, an output stream, a path, a reader, and a writer.
+ * Starting from this origin, you can get a byte array, a file, an input
stream, an output stream, a path, a reader, and a writer.
* </p>
*/
public static class FileOrigin extends AbstractOrigin<File, FileOrigin> {
@@ -150,7 +150,7 @@ public abstract class AbstractOrigin<T, B extends
AbstractOrigin<T, B>> extends
/**
* A {@link Path} origin.
* <p>
- * Starting from this origin, you can get a byte array, a file, an input
stream, an output stream, a path, a reader, and a writer.
+ * Starting from this origin, you can get a byte array, a file, an input
stream, an output stream, a path, a reader, and a writer.
* </p>
*/
public static class PathOrigin extends AbstractOrigin<Path, PathOrigin> {
@@ -280,6 +280,7 @@ public abstract class AbstractOrigin<T, B extends
AbstractOrigin<T, B>> extends
*
* @return this origin as a byte array, if possible.
* @throws IOException if an I/O error occurs.
+ * @throws UnsupportedOperationException if the origin cannot be converted
to a Path.
*/
public byte[] getByteArray() throws IOException {
return Files.readAllBytes(getPath());
@@ -301,6 +302,7 @@ public abstract class AbstractOrigin<T, B extends
AbstractOrigin<T, B>> extends
* @param options options specifying how the file is opened
* @return this origin as an InputStream, if possible.
* @throws IOException if an I/O error occurs.
+ * @throws UnsupportedOperationException if the origin cannot be converted
to a Path.
*/
public InputStream getInputStream(final OpenOption... options) throws
IOException {
return Files.newInputStream(getPath(), options);
@@ -312,6 +314,7 @@ public abstract class AbstractOrigin<T, B extends
AbstractOrigin<T, B>> extends
* @param options options specifying how the file is opened
* @return this origin as an OutputStream, if possible.
* @throws IOException if an I/O error occurs.
+ * @throws UnsupportedOperationException if the origin cannot be converted
to a Path.
*/
public OutputStream getOutputStream(final OpenOption... options) throws
IOException {
return Files.newOutputStream(getPath(), options);
@@ -345,6 +348,7 @@ public abstract class AbstractOrigin<T, B extends
AbstractOrigin<T, B>> extends
* @param options options specifying how the file is opened
* @return a new Writer on the origin.
* @throws IOException if an I/O error occurs opening or creating the file.
+ * @throws UnsupportedOperationException if the origin cannot be converted
to a Path.
*/
public Writer getWriter(final Charset charset, final OpenOption...
options) throws IOException {
return Files.newBufferedWriter(getPath(), charset, options);
diff --git a/src/main/java/org/apache/commons/io/input/BOMInputStream.java
b/src/main/java/org/apache/commons/io/input/BOMInputStream.java
index b96bc72b..36b4e005 100644
--- a/src/main/java/org/apache/commons/io/input/BOMInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/BOMInputStream.java
@@ -117,6 +117,11 @@ public class BOMInputStream extends ProxyInputStream {
private ByteOrderMark[] byteOrderMarks = DEFAULT;
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an InputStream.
+ */
@SuppressWarnings("resource")
@Override
public BOMInputStream get() throws IOException {
diff --git
a/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
b/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
index cfe13040..e514f985 100644
---
a/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
+++
b/src/main/java/org/apache/commons/io/input/BufferedFileChannelInputStream.java
@@ -28,13 +28,11 @@ import org.apache.commons.io.IOUtils;
import org.apache.commons.io.build.AbstractStreamBuilder;
/**
- * {@link InputStream} implementation which uses direct buffer to read a file
to avoid extra copy of data between Java
- * and native memory which happens when using {@link
java.io.BufferedInputStream}. Unfortunately, this is not something
- * already available in JDK, {@code sun.nio.ch.ChannelInputStream} supports
reading a file using NIO, but does not
- * support buffering.
+ * {@link InputStream} implementation which uses direct buffer to read a file
to avoid extra copy of data between Java and native memory which happens when
+ * using {@link java.io.BufferedInputStream}. Unfortunately, this is not
something already available in JDK, {@code sun.nio.ch.ChannelInputStream}
supports
+ * reading a file using NIO, but does not support buffering.
* <p>
- * This class was ported and adapted from Apache Spark commit
933dc6cb7b3de1d8ccaf73d124d6eb95b947ed19 where it was
- * called {@code NioBufferedFileInputStream}.
+ * This class was ported and adapted from Apache Spark commit
933dc6cb7b3de1d8ccaf73d124d6eb95b947ed19 where it was called {@code
NioBufferedFileInputStream}.
* </p>
*
* @since 2.9.0
@@ -46,6 +44,7 @@ public final class BufferedFileChannelInputStream extends
InputStream {
* <p>
* Using File IO:
* </p>
+ *
* <pre>{@code
* BufferedFileChannelInputStream s =
BufferedFileChannelInputStream.builder()
* .setFile(file)
@@ -55,6 +54,7 @@ public final class BufferedFileChannelInputStream extends
InputStream {
* <p>
* Using NIO Path:
* </p>
+ *
* <pre>{@code
* BufferedFileChannelInputStream s =
BufferedFileChannelInputStream.builder()
* .setPath(path)
@@ -66,6 +66,11 @@ public final class BufferedFileChannelInputStream extends
InputStream {
*/
public static class Builder extends
AbstractStreamBuilder<BufferedFileChannelInputStream, Builder> {
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Path.
+ */
@Override
public BufferedFileChannelInputStream get() throws IOException {
return new BufferedFileChannelInputStream(getOrigin().getPath(),
getBufferSize());
@@ -102,7 +107,7 @@ public final class BufferedFileChannelInputStream extends
InputStream {
/**
* Constructs a new instance for the given File and buffer size.
*
- * @param file The file to stream.
+ * @param file The file to stream.
* @param bufferSize buffer size.
* @throws IOException If an I/O error occurs
* @deprecated Use {@link #builder()}
@@ -127,7 +132,7 @@ public final class BufferedFileChannelInputStream extends
InputStream {
/**
* Constructs a new instance for the given Path and buffer size.
*
- * @param path The path to stream.
+ * @param path The path to stream.
* @param bufferSize buffer size.
* @throws IOException If an I/O error occurs
* @deprecated Use {@link #builder()}
@@ -146,11 +151,10 @@ public final class BufferedFileChannelInputStream extends
InputStream {
}
/**
- * Attempts to clean up a ByteBuffer if it is direct or memory-mapped.
This uses an *unsafe* Sun API that will cause
- * errors if one attempts to read from the disposed buffer. However,
neither the bytes allocated to direct buffers nor
- * file descriptors opened for memory-mapped buffers put pressure on the
garbage collector. Waiting for garbage
- * collection may lead to the depletion of off-heap memory or huge numbers
of open files. There's unfortunately no
- * standard API to manually dispose of these kinds of buffers.
+ * Attempts to clean up a ByteBuffer if it is direct or memory-mapped.
This uses an *unsafe* Sun API that will cause errors if one attempts to read
from the
+ * disposed buffer. However, neither the bytes allocated to direct buffers
nor file descriptors opened for memory-mapped buffers put pressure on the
garbage
+ * collector. Waiting for garbage collection may lead to the depletion of
off-heap memory or huge numbers of open files. There's unfortunately no standard
+ * API to manually dispose of these kinds of buffers.
*
* @param buffer the buffer to clean.
*/
@@ -161,10 +165,10 @@ public final class BufferedFileChannelInputStream extends
InputStream {
}
/**
- * In Java 8, the type of {@code sun.nio.ch.DirectBuffer.cleaner()} was
{@code sun.misc.Cleaner}, and it was possible to
- * access the method {@code sun.misc.Cleaner.clean()} to invoke it. The
type changed to {@code jdk.internal.ref.Cleaner}
- * in later JDKs, and the {@code clean()} method is not accessible even
with reflection. However {@code sun.misc.Unsafe}
- * added an {@code invokeCleaner()} method in JDK 9+ and this is still
accessible with reflection.
+ * In Java 8, the type of {@code sun.nio.ch.DirectBuffer.cleaner()} was
{@code sun.misc.Cleaner}, and it was possible to access the method
+ * {@code sun.misc.Cleaner.clean()} to invoke it. The type changed to
{@code jdk.internal.ref.Cleaner} in later JDKs, and the {@code clean()} method
is not
+ * accessible even with reflection. However {@code sun.misc.Unsafe} added
an {@code invokeCleaner()} method in JDK 9+ and this is still accessible with
+ * reflection.
*
* @param buffer the buffer to clean. must be a DirectBuffer.
*/
diff --git
a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
index ef1d4b7c..77bcda79 100644
--- a/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/MemoryMappedFileInputStream.java
@@ -54,7 +54,7 @@ import org.apache.commons.io.build.AbstractStreamBuilder;
*
* @since 2.12.0
*/
-public class MemoryMappedFileInputStream extends InputStream {
+public final class MemoryMappedFileInputStream extends InputStream {
/**
* Builds a new {@link MemoryMappedFileInputStream} instance.
@@ -77,6 +77,11 @@ public class MemoryMappedFileInputStream extends InputStream
{
setBufferSize(DEFAULT_BUFFER_SIZE);
}
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Path.
+ */
@Override
public MemoryMappedFileInputStream get() throws IOException {
return new MemoryMappedFileInputStream(getOrigin().getPath(),
getBufferSize());
@@ -111,28 +116,14 @@ public class MemoryMappedFileInputStream extends
InputStream {
*/
private long nextBufferPosition;
- /**
- * Constructs a new instance.
- *
- * @param file The path of the file to open.
- * @throws IOException If an I/O error occurs
- * @deprecated Use {@link #builder()}
- */
- @Deprecated
- public MemoryMappedFileInputStream(final Path file) throws IOException {
- this(file, DEFAULT_BUFFER_SIZE);
- }
-
/**
* Constructs a new instance.
*
* @param file The path of the file to open.
* @param bufferSize Size of the sliding buffer.
* @throws IOException If an I/O error occurs.
- * @deprecated Use {@link #builder()}
*/
- @Deprecated
- public MemoryMappedFileInputStream(final Path file, final int bufferSize)
throws IOException {
+ private MemoryMappedFileInputStream(final Path file, final int bufferSize)
throws IOException {
this.bufferSize = bufferSize;
this.channel = FileChannel.open(file, StandardOpenOption.READ);
}
diff --git
a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
index 4bf401c8..dea07395 100644
---
a/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
+++
b/src/main/java/org/apache/commons/io/input/MessageDigestCalculatingInputStream.java
@@ -67,6 +67,11 @@ public class MessageDigestCalculatingInputStream extends
ObservableInputStream {
}
}
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an InputStream.
+ */
@SuppressWarnings("resource")
@Override
public MessageDigestCalculatingInputStream get() throws IOException {
diff --git
a/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
b/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
index b2f3624f..02737b80 100644
--- a/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/RandomAccessFileInputStream.java
@@ -51,6 +51,11 @@ public class RandomAccessFileInputStream extends InputStream
{
private RandomAccessFile randomAccessFile;
private boolean closeOnClose;
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a File.
+ */
@SuppressWarnings("resource") // Caller closes depending on settings
@Override
public RandomAccessFileInputStream get() throws IOException {
diff --git
a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
index 4de83cc9..4f1d5a19 100644
--- a/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ReadAheadInputStream.java
@@ -62,6 +62,11 @@ public class ReadAheadInputStream extends InputStream {
private ExecutorService executorService;
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an InputStream.
+ */
@SuppressWarnings("resource")
@Override
public ReadAheadInputStream get() throws IOException {
diff --git a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
index 39d05ef0..e816acc6 100644
--- a/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/ReaderInputStream.java
@@ -96,6 +96,11 @@ public class ReaderInputStream extends InputStream {
private CharsetEncoder charsetEncoder =
super.getCharset().newEncoder();
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Reader.
+ */
@SuppressWarnings("resource")
@Override
public ReaderInputStream get() throws IOException {
diff --git
a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
index fe0eff0a..467450f0 100644
--- a/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
+++ b/src/main/java/org/apache/commons/io/input/ReversedLinesFileReader.java
@@ -68,6 +68,11 @@ public class ReversedLinesFileReader implements Closeable {
setBufferSize(DEFAULT_BLOCK_SIZE);
}
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Path.
+ */
@Override
public ReversedLinesFileReader get() throws IOException {
return new ReversedLinesFileReader(getOrigin().getPath(),
getBufferSize(), getCharset());
diff --git a/src/main/java/org/apache/commons/io/input/Tailer.java
b/src/main/java/org/apache/commons/io/input/Tailer.java
index d29cb2bc..d5050c70 100644
--- a/src/main/java/org/apache/commons/io/input/Tailer.java
+++ b/src/main/java/org/apache/commons/io/input/Tailer.java
@@ -205,6 +205,11 @@ public class Tailer implements Runnable, AutoCloseable {
return this;
}
+ /**
+ * Sets the origin.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Path.
+ */
@Override
protected Builder setOrigin(final AbstractOrigin<?, ?> origin) {
setTailable(new TailablePath(origin.getPath()));
diff --git
a/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
b/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
index 588cb328..78524736 100644
--- a/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
+++ b/src/main/java/org/apache/commons/io/input/UncheckedBufferedReader.java
@@ -61,6 +61,11 @@ public final class UncheckedBufferedReader extends
BufferedReader {
*/
public static class Builder extends
AbstractStreamBuilder<UncheckedBufferedReader, Builder> {
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Reader.
+ */
@Override
public UncheckedBufferedReader get() {
// This an unchecked class, so this method is as well.
diff --git
a/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
b/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
index ab219c2c..0dede00d 100644
--- a/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
+++ b/src/main/java/org/apache/commons/io/input/UncheckedFilterReader.java
@@ -57,6 +57,11 @@ public final class UncheckedFilterReader extends
FilterReader {
*/
public static class Builder extends
AbstractStreamBuilder<UncheckedFilterReader, Builder> {
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Reader.
+ */
@Override
public UncheckedFilterReader get() {
// This an unchecked class, so this method is as well.
diff --git
a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
index fc90c3f3..2c438500 100644
---
a/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
+++
b/src/main/java/org/apache/commons/io/input/UnsynchronizedBufferedInputStream.java
@@ -71,6 +71,11 @@ public final class UnsynchronizedBufferedInputStream extends
UnsynchronizedFilte
*/
public static class Builder extends
AbstractStreamBuilder<UnsynchronizedBufferedInputStream, Builder> {
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an InputStream.
+ */
@SuppressWarnings("resource") // Caller closes.
@Override
public UnsynchronizedBufferedInputStream get() throws IOException {
@@ -312,7 +317,7 @@ public final class UnsynchronizedBufferedInputStream
extends UnsynchronizedFilte
if (fillBuffer(localIn, localBuf) == IOUtils.EOF) {
return required == length ? IOUtils.EOF : length -
required;
}
- // localBuf may have been invalidated by fillbuf
+ // localBuf may have been invalidated by fillBuffer()
if (localBuf != buffer) {
localBuf = buffer;
if (localBuf == null) {
diff --git
a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
index 4d84c655..740e7290 100644
---
a/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
+++
b/src/main/java/org/apache/commons/io/input/UnsynchronizedByteArrayInputStream.java
@@ -26,9 +26,8 @@ import java.util.Objects;
import org.apache.commons.io.build.AbstractStreamBuilder;
/**
- * This is an alternative to {@link java.io.ByteArrayInputStream}
- * which removes the synchronization overhead for non-concurrent
- * access; as such this class is not thread-safe.
+ * This is an alternative to {@link java.io.ByteArrayInputStream} which
removes the synchronization overhead for non-concurrent access; as such this
class is
+ * not thread-safe.
*
* @see ByteArrayInputStream
* @since 2.7
@@ -41,6 +40,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
* <p>
* Using a Byte Array:
* </p>
+ *
* <pre>{@code
* UnsynchronizedByteArrayInputStream s =
UnsynchronizedByteArrayInputStream.builder()
* .setByteArray(byteArray)
@@ -51,6 +51,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
* <p>
* Using File IO:
* </p>
+ *
* <pre>{@code
* UnsynchronizedByteArrayInputStream s =
UnsynchronizedByteArrayInputStream.builder()
* .setFile(file)
@@ -61,6 +62,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
* <p>
* Using NIO Path:
* </p>
+ *
* <pre>{@code
* UnsynchronizedByteArrayInputStream s =
UnsynchronizedByteArrayInputStream.builder()
* .setPath(path)
@@ -74,18 +76,23 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
private int offset;
private int length;
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a byte array.
+ */
@Override
public UnsynchronizedByteArrayInputStream get() throws IOException {
return new
UnsynchronizedByteArrayInputStream(getOrigin().getByteArray(), offset, length);
}
@Override
- public Builder setByteArray(byte[] origin) {
+ public Builder setByteArray(final byte[] origin) {
length = Objects.requireNonNull(origin, "origin").length;
return super.setByteArray(origin);
}
- public Builder setLength(int length) {
+ public Builder setLength(final int length) {
if (length < 0) {
throw new IllegalArgumentException("length cannot be
negative");
}
@@ -93,7 +100,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
return this;
}
- public Builder setOffset(int offset) {
+ public Builder setOffset(final int offset) {
if (offset < 0) {
throw new IllegalArgumentException("offset cannot be
negative");
}
@@ -125,8 +132,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
/**
* End Of Data.
*
- * Similar to data.length,
- * i.e. the last readable offset + 1.
+ * Similar to data.length, i.e. the last readable offset + 1.
*/
private final int eod;
@@ -157,7 +163,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
/**
* Creates a new byte array input stream.
*
- * @param data the buffer
+ * @param data the buffer
* @param offset the offset into the buffer
*
* @throws IllegalArgumentException if the offset is less than zero
@@ -178,7 +184,7 @@ public class UnsynchronizedByteArrayInputStream extends
InputStream {
/**
* Creates a new byte array input stream.
*
- * @param data the buffer
+ * @param data the buffer
* @param offset the offset into the buffer
* @param length the length of the buffer
*
diff --git
a/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
b/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
index 918c1b19..3113c5a8 100644
---
a/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
+++
b/src/main/java/org/apache/commons/io/input/UnsynchronizedFilterInputStream.java
@@ -48,7 +48,6 @@ public class UnsynchronizedFilterInputStream extends
InputStream {
* <pre>{@code
* UnsynchronizedFilterInputStream s =
UnsynchronizedFilterInputStream.builder()
* .setFile(file)
- * .setBufferSize(8192)
* .get()}
* </pre>
* <p>
@@ -57,12 +56,16 @@ public class UnsynchronizedFilterInputStream extends
InputStream {
* <pre>{@code
* UnsynchronizedFilterInputStream s =
UnsynchronizedFilterInputStream.builder()
* .setPath(path)
- * .setBufferSize(8192)
* .get()}
* </pre>
*/
public static class Builder extends
AbstractStreamBuilder<UnsynchronizedFilterInputStream, Builder> {
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an InputStream.
+ */
@SuppressWarnings("resource") // Caller closes.
@Override
public UnsynchronizedFilterInputStream get() throws IOException {
@@ -90,7 +93,7 @@ public class UnsynchronizedFilterInputStream extends
InputStream {
*
* @param inputStream the non-null InputStream to filter reads on.
*/
- protected UnsynchronizedFilterInputStream(final InputStream inputStream) {
+ UnsynchronizedFilterInputStream(final InputStream inputStream) {
this.inputStream = inputStream;
}
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 e5924eac..7fa756d2 100644
--- a/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
+++ b/src/main/java/org/apache/commons/io/input/XmlStreamReader.java
@@ -116,6 +116,11 @@ public class XmlStreamReader extends Reader {
private boolean lenient = true;
private String httpContentType;
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an InputStream.
+ */
@SuppressWarnings("resource")
@Override
public XmlStreamReader get() throws IOException {
diff --git
a/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
b/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
index 429508d4..c2bb1750 100644
--- a/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
+++ b/src/main/java/org/apache/commons/io/output/FileWriterWithEncoding.java
@@ -77,6 +77,11 @@ public class FileWriterWithEncoding extends ProxyWriter {
private CharsetEncoder charsetEncoder =
super.getCharset().newEncoder();
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a File.
+ */
@SuppressWarnings("resource")
@Override
public FileWriterWithEncoding get() throws IOException {
diff --git a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
index c784f51d..4905cfd6 100644
--- a/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
+++ b/src/main/java/org/apache/commons/io/output/LockableFileWriter.java
@@ -72,6 +72,11 @@ public class LockableFileWriter extends Writer {
setBufferSize(AbstractByteArrayOutputStream.DEFAULT_SIZE);
}
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a File.
+ */
@Override
public LockableFileWriter get() throws IOException {
return new LockableFileWriter(getOrigin().getFile(), getCharset(),
append, lockDirectory.getFile().toString());
diff --git
a/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
b/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
index fe7223ac..840c3124 100644
---
a/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
+++
b/src/main/java/org/apache/commons/io/output/UncheckedFilterOutputStream.java
@@ -33,7 +33,7 @@ import org.apache.commons.io.function.Uncheck;
* @see UncheckedIOException
* @since 2.12.0
*/
-public class UncheckedFilterOutputStream extends FilterOutputStream {
+public final class UncheckedFilterOutputStream extends FilterOutputStream {
/**
* Builds a new {@link UncheckedFilterOutputStream} instance.
@@ -56,6 +56,11 @@ public class UncheckedFilterOutputStream extends
FilterOutputStream {
*/
public static class Builder extends
AbstractStreamBuilder<UncheckedFilterOutputStream, Builder> {
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an OutputStream.
+ */
@SuppressWarnings("resource")
@Override
public UncheckedFilterOutputStream get() throws IOException {
@@ -79,7 +84,7 @@ public class UncheckedFilterOutputStream extends
FilterOutputStream {
* @param outputStream the underlying output stream, or {@code null} if
this instance is to be created without an
* underlying stream.
*/
- public UncheckedFilterOutputStream(final OutputStream outputStream) {
+ private UncheckedFilterOutputStream(final OutputStream outputStream) {
super(outputStream);
}
diff --git
a/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
b/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
index e64a4ced..3fe885f0 100644
--- a/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
+++ b/src/main/java/org/apache/commons/io/output/UncheckedFilterWriter.java
@@ -22,6 +22,7 @@ import java.io.IOException;
import java.io.UncheckedIOException;
import java.io.Writer;
+import org.apache.commons.io.build.AbstractStreamBuilder;
import org.apache.commons.io.function.Uncheck;
/**
@@ -32,17 +33,49 @@ import org.apache.commons.io.function.Uncheck;
* @see UncheckedIOException
* @since 2.12.0
*/
-public class UncheckedFilterWriter extends FilterWriter {
+public final class UncheckedFilterWriter extends FilterWriter {
/**
- * Creates a new filtered writer.
+ * Builds a new {@link UncheckedFilterWriter} instance.
+ * <p>
+ * Using File IO:
+ * </p>
+ * <pre>{@code
+ * UncheckedFilterWriter s = UncheckedFilterWriter.builder()
+ * .setFile(file)
+ * .get()}
+ * </pre>
+ * <p>
+ * Using NIO Path:
+ * </p>
+ * <pre>{@code
+ * UncheckedFilterWriter s = UncheckedFilterWriter.builder()
+ * .setPath(path)
+ * .get()}
+ * </pre>
+ */
+ public static class Builder extends
AbstractStreamBuilder<UncheckedFilterWriter, Builder> {
+
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Writer.
+ */
+ @SuppressWarnings("resource")
+ @Override
+ public UncheckedFilterWriter get() throws IOException {
+ return new
UncheckedFilterWriter(getOrigin().getWriter(getCharset()));
+ }
+
+ }
+
+ /**
+ * Constructs a new {@link Builder}.
*
- * @param writer a Writer object providing the underlying stream.
- * @return a new UncheckedFilterReader.
- * @throws NullPointerException if {@code writer} is {@code null}.
+ * @return a new {@link Builder}.
*/
- public static UncheckedFilterWriter on(final Writer writer) {
- return new UncheckedFilterWriter(writer);
+ public static Builder builder() {
+ return new Builder();
}
/**
@@ -51,7 +84,7 @@ public class UncheckedFilterWriter extends FilterWriter {
* @param writer a Writer object providing the underlying stream.
* @throws NullPointerException if {@code writer} is {@code null}.
*/
- protected UncheckedFilterWriter(final Writer writer) {
+ private UncheckedFilterWriter(final Writer writer) {
super(writer);
}
diff --git
a/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
b/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
index 6f8ee73e..31f57244 100644
---
a/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
+++
b/src/main/java/org/apache/commons/io/output/UnsynchronizedByteArrayOutputStream.java
@@ -21,6 +21,7 @@ import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
+import org.apache.commons.io.build.AbstractStreamBuilder;
import org.apache.commons.io.function.Uncheck;
import org.apache.commons.io.input.UnsynchronizedByteArrayInputStream;
@@ -32,6 +33,48 @@ import
org.apache.commons.io.input.UnsynchronizedByteArrayInputStream;
//@NotThreadSafe
public final class UnsynchronizedByteArrayOutputStream extends
AbstractByteArrayOutputStream {
+ /**
+ * Builds a new {@link UnsynchronizedByteArrayOutputStream} instance.
+ * <p>
+ * Using File IO:
+ * </p>
+ * <pre>{@code
+ * UnsynchronizedByteArrayOutputStream s =
UnsynchronizedByteArrayOutputStream.builder()
+ * .setBufferSize(8192)
+ * .get()}
+ * </pre>
+ * <p>
+ * Using NIO Path:
+ * </p>
+ * <pre>{@code
+ * UnsynchronizedByteArrayOutputStream s =
UnsynchronizedByteArrayOutputStream.builder()
+ * .setBufferSize(8192)
+ * .get()}
+ * </pre>
+ */
+ public static class Builder extends
AbstractStreamBuilder<UnsynchronizedByteArrayOutputStream, Builder> {
+
+ /**
+ * Constructs a new instance.
+ *
+ * Only uses the buffer size attribute.
+ */
+ @Override
+ public UnsynchronizedByteArrayOutputStream get() {
+ return new UnsynchronizedByteArrayOutputStream(getBufferSize());
+ }
+
+ }
+
+ /**
+ * Constructs a new {@link Builder}.
+ *
+ * @return a new {@link Builder}.
+ */
+ public static Builder builder() {
+ return new Builder();
+ }
+
/**
* Fetches entire contents of an {@link InputStream} and represent same
data as result InputStream.
* <p>
@@ -73,7 +116,7 @@ public final class UnsynchronizedByteArrayOutputStream
extends AbstractByteArray
*/
public static InputStream toBufferedInputStream(final InputStream input,
final int size) throws IOException {
// It does not matter if a ByteArrayOutputStream is not closed as
close() is a no-op
- try (UnsynchronizedByteArrayOutputStream output = new
UnsynchronizedByteArrayOutputStream(size)) {
+ try (UnsynchronizedByteArrayOutputStream output =
builder().setBufferSize(size).get()) {
output.write(input);
return output.toInputStream();
}
@@ -81,8 +124,11 @@ public final class UnsynchronizedByteArrayOutputStream
extends AbstractByteArray
/**
* Creates a new byte array output stream. The buffer capacity is initially
+ *
* {@value AbstractByteArrayOutputStream#DEFAULT_SIZE} bytes, though its
size increases if necessary.
+ * @deprecated Use {@link #builder()}.
*/
+ @Deprecated
public UnsynchronizedByteArrayOutputStream() {
this(DEFAULT_SIZE);
}
@@ -92,7 +138,9 @@ public final class UnsynchronizedByteArrayOutputStream
extends AbstractByteArray
*
* @param size the initial size
* @throws IllegalArgumentException if size is negative
+ * @deprecated Use {@link #builder()}.
*/
+ @Deprecated
public UnsynchronizedByteArrayOutputStream(final int size) {
if (size < 0) {
throw new IllegalArgumentException("Negative initial size: " +
size);
diff --git a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
index 06d5ccd6..e201f69b 100644
--- a/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
+++ b/src/main/java/org/apache/commons/io/output/WriterOutputStream.java
@@ -95,6 +95,11 @@ public class WriterOutputStream extends OutputStream {
this.charsetDecoder = getCharset().newDecoder();
}
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to a Writer.
+ */
@SuppressWarnings("resource")
@Override
public WriterOutputStream get() throws IOException {
@@ -157,7 +162,7 @@ public class WriterOutputStream extends OutputStream {
}
/**
- * Check if the JDK in use properly supports the given charset.
+ * Checks if the JDK in use properly supports the given charset.
*
* @param charset the charset to check the support for
*/
diff --git a/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
b/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
index d0f659d1..1142c70e 100644
--- a/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
+++ b/src/main/java/org/apache/commons/io/output/XmlStreamWriter.java
@@ -65,6 +65,11 @@ public class XmlStreamWriter extends Writer {
setCharset(StandardCharsets.UTF_8);
}
+ /**
+ * Constructs a new instance.
+ *
+ * @throws UnsupportedOperationException if the origin cannot be
converted to an OutputStream.
+ */
@SuppressWarnings("resource")
@Override
public XmlStreamWriter get() throws IOException {
diff --git
a/src/test/java/org/apache/commons/io/input/MemoryMappedFileInputStreamTest.java
b/src/test/java/org/apache/commons/io/input/MemoryMappedFileInputStreamTest.java
index ce3c2d61..a26b46a8 100644
---
a/src/test/java/org/apache/commons/io/input/MemoryMappedFileInputStreamTest.java
+++
b/src/test/java/org/apache/commons/io/input/MemoryMappedFileInputStreamTest.java
@@ -62,6 +62,14 @@ public class MemoryMappedFileInputStreamTest {
return Files.write(Files.createTempFile(tempDir, null, null),
RandomUtils.nextBytes(size));
}
+ private MemoryMappedFileInputStream newStream(final Path file) throws
IOException {
+ return MemoryMappedFileInputStream.builder().setPath(file).get();
+ }
+
+ private MemoryMappedFileInputStream newStream(final Path file, final int
bufferSize) throws IOException {
+ return
MemoryMappedFileInputStream.builder().setPath(file).setBufferSize(bufferSize).get();
+ }
+
@Test
void testAlternateBufferSize() throws IOException {
// setup
@@ -69,7 +77,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
1024)) {
+ try (InputStream inputStream = newStream(file, 1024)) {
// verify
assertArrayEquals(expectedData, IOUtils.toByteArray(inputStream));
}
@@ -80,7 +88,7 @@ public class MemoryMappedFileInputStreamTest {
// setup
final Path file = createTestFile(0);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file)) {
+ try (InputStream inputStream = newStream(file)) {
// verify
assertArrayEquals(EMPTY_BYTE_ARRAY,
IOUtils.toByteArray(inputStream));
}
@@ -93,7 +101,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file)) {
+ try (InputStream inputStream = newStream(file)) {
// verify
assertArrayEquals(expectedData, IOUtils.toByteArray(inputStream));
}
@@ -105,7 +113,7 @@ public class MemoryMappedFileInputStreamTest {
final Path file = createTestFile(1 * 1024 * 1024);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
1024)) {
+ try (InputStream inputStream = newStream(file, 1024)) {
inputStream.close();
// verify
Assertions.assertThrows(IOException.class, () ->
IOUtils.toByteArray(inputStream));
@@ -118,7 +126,7 @@ public class MemoryMappedFileInputStreamTest {
final Path file = createTestFile(2);
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
1024)) {
+ try (InputStream inputStream = newStream(file, 1024)) {
final int b1 = inputStream.read();
final int b2 = inputStream.read();
assertEquals(-1, inputStream.read());
@@ -134,7 +142,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
10)) {
+ try (InputStream inputStream = newStream(file, 10)) {
assertEquals(1, inputStream.skip(1));
final byte[] data = IOUtils.toByteArray(inputStream);
// verify
@@ -147,7 +155,7 @@ public class MemoryMappedFileInputStreamTest {
// setup
final Path file = createTestFile(0);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file)) {
+ try (InputStream inputStream = newStream(file)) {
assertEquals(0, inputStream.skip(5));
// verify
assertArrayEquals(EMPTY_BYTE_ARRAY,
IOUtils.toByteArray(inputStream));
@@ -161,7 +169,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
10)) {
+ try (InputStream inputStream = newStream(file, 10)) {
IOUtils.toByteArray(inputStream, 5);
assertEquals(3, inputStream.skip(3));
final byte[] data = IOUtils.toByteArray(inputStream);
@@ -177,7 +185,7 @@ public class MemoryMappedFileInputStreamTest {
final Path file = createTestFile(10);
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file)) {
+ try (InputStream inputStream = newStream(file)) {
assertEquals(0, inputStream.skip(amountToSkip));
// verify
assertArrayEquals(expectedData, IOUtils.toByteArray(inputStream));
@@ -191,7 +199,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
10)) {
+ try (InputStream inputStream = newStream(file, 10)) {
IOUtils.toByteArray(inputStream, 5);
assertEquals(6, inputStream.skip(6));
final byte[] data = IOUtils.toByteArray(inputStream);
@@ -206,7 +214,7 @@ public class MemoryMappedFileInputStreamTest {
final Path file = createTestFile(100);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
10)) {
+ try (InputStream inputStream = newStream(file, 10)) {
IOUtils.toByteArray(inputStream, 5);
assertEquals(95, inputStream.skip(96));
// verify
@@ -221,7 +229,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file,
10)) {
+ try (InputStream inputStream = newStream(file, 10)) {
IOUtils.toByteArray(inputStream, 5);
assertEquals(5, inputStream.skip(5));
final byte[] data = IOUtils.toByteArray(inputStream);
@@ -267,7 +275,7 @@ public class MemoryMappedFileInputStreamTest {
final byte[] expectedData = Files.readAllBytes(file);
// test
- try (InputStream inputStream = new MemoryMappedFileInputStream(file)) {
+ try (InputStream inputStream = newStream(file)) {
// verify
assertArrayEquals(expectedData, IOUtils.toByteArray(inputStream));
}
diff --git
a/src/test/java/org/apache/commons/io/input/UnsynchronizedFilterInputStreamTest.java
b/src/test/java/org/apache/commons/io/input/UnsynchronizedFilterInputStreamTest.java
index 818e3eef..ab4e3d94 100644
---
a/src/test/java/org/apache/commons/io/input/UnsynchronizedFilterInputStreamTest.java
+++
b/src/test/java/org/apache/commons/io/input/UnsynchronizedFilterInputStreamTest.java
@@ -57,7 +57,7 @@ public class UnsynchronizedFilterInputStreamTest {
protected void setUp() throws IOException {
fileName = Files.createTempFile(getClass().getSimpleName(), ".tst");
Files.write(fileName, DATA.getBytes("UTF-8"));
- is = new
UnsynchronizedFilterInputStream(Files.newInputStream(fileName));
+ is =
UnsynchronizedFilterInputStream.builder().setInputStream(Files.newInputStream(fileName)).get();
}
/**
diff --git
a/src/test/java/org/apache/commons/io/output/UncheckedFilterWriterTest.java
b/src/test/java/org/apache/commons/io/output/UncheckedFilterWriterTest.java
index 10b0ee3c..d9c1e323 100644
--- a/src/test/java/org/apache/commons/io/output/UncheckedFilterWriterTest.java
+++ b/src/test/java/org/apache/commons/io/output/UncheckedFilterWriterTest.java
@@ -39,10 +39,10 @@ public class UncheckedFilterWriterTest {
@SuppressWarnings("resource")
@BeforeEach
- public void setUp() {
+ public void setUp() throws IOException {
exception = new IOException("test exception");
- brokenWriter = UncheckedFilterWriter.on(new BrokenWriter(exception));
- stringWriter = UncheckedFilterWriter.on(new StringWriter());
+ brokenWriter = UncheckedFilterWriter.builder().setWriter(new
BrokenWriter(exception)).get();
+ stringWriter = UncheckedFilterWriter.builder().setWriter(new
StringWriter()).get();
}
@SuppressWarnings("resource")
