Package org.apache.commons.io.build

# Class AbstractStreamBuilder<T,B extends AbstractStreamBuilder<T,B>>

java.lang.Object
org.apache.commons.io.build.AbstractSupplier<T,B>
org.apache.commons.io.build.AbstractOriginSupplier<T,B>
org.apache.commons.io.build.AbstractStreamBuilder<T,B>

Type Parameters:
  `T` - the type of instances to build.
  `B` - the type of builder subclass.

All Implemented Interfaces:
  `IOSupplier<T>`

Direct Known Subclasses:
  `BufferedFileChannelInputStream.Builder`, `ByteArraySeekableByteChannel.Builder`, `CharSequenceInputStream.Builder`, `ChunkedOutputStream.Builder`, `DeferredFileOutputStream.Builder`, `FileWriterWithEncoding.Builder`, `FilterChannel.AbstractBuilder`, `FilterFileChannel.AbstractBuilder`, `FlushShieldOutputStream.Builder`, `LockableFileWriter.Builder`, `MemoryMappedFileInputStream.Builder`, `ProxyInputStream.AbstractBuilder`, `ProxyOutputStream.Builder`, `QueueInputStream.Builder`, `RandomAccessFileInputStream.Builder`, `RandomAccessFileOutputStream.Builder`, `ReadAheadInputStream.Builder`, `ReaderInputStream.Builder`, `ReversedLinesFileReader.Builder`, `Tailer.Builder`, `UncheckedBufferedReader.Builder`, `UncheckedFilterInputStream.Builder`, `UncheckedFilterOutputStream.Builder`, `UncheckedFilterReader.Builder`, `UncheckedFilterWriter.Builder`, `UnsynchronizedBufferedInputStream.Builder`, `UnsynchronizedByteArrayInputStream.Builder`, `UnsynchronizedByteArrayOutputStream.Builder`, `UnsynchronizedFilterInputStream.Builder`, `ValidatingObjectInputStream.Builder`, `WriterOutputStream.Builder`, `XmlStreamReader.Builder`, `XmlStreamWriter.Builder`

public abstract class AbstractStreamBuilder<T,B extends AbstractStreamBuilder<T,B>> extends AbstractOriginSupplier<T,B>
Abstracts building a typed instance of type `T` where `T` is unbounded. This class contains various properties like a buffer size, buffer size checker, a buffer size default, buffer size maximum, Charset, Charset default, default size checker, and open options. A subclass may use all, some, or none of these properties in building instances of `T`.

Since:
  2.12.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractStreamBuilder()`
  Constructs a new instance for subclasses.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getBufferSize()`
  Gets the buffer size, defaults to `IOUtils.DEFAULT_BUFFER_SIZE` (8192).
  `int`
  `getBufferSizeDefault()`
  Gets the buffer size default, defaults to `IOUtils.DEFAULT_BUFFER_SIZE` (8192).
  `byte[]`
  `getByteArray()`
  Gets a byte array from the origin.
  `<C extends Channel>
  C`
  `getChannel(Class<C> channelType)`
  Gets a Channel from the origin with OpenOption[].
  `CharSequence`
  `getCharSequence()`
  Gets a CharSequence from the origin with a Charset.
  `Charset`
  `getCharset()`
  Gets the Charset, defaults to `Charset.defaultCharset()`.
  `Charset`
  `getCharsetDefault()`
  Gets the Charset default, defaults to `Charset.defaultCharset()`.
  `File`
  `getFile()`
  Gets a File from the origin.
  `InputStream`
  `getInputStream()`
  Gets an InputStream from the origin with OpenOption[].
  `OpenOption[]`
  `getOpenOptions()`
  Gets the OpenOption array.
  `OutputStream`
  `getOutputStream()`
  Gets an OutputStream from the origin with OpenOption[].
  `Path`
  `getPath()`
  Gets a Path from the origin.
  `RandomAccessFile`
  `getRandomAccessFile()`
  Gets a RandomAccessFile from the origin.
  `Reader`
  `getReader()`
  Gets a Reader from the origin with a Charset.
  `Writer`
  `getWriter()`
  Gets a Writer from the origin with an OpenOption[].
  `B`
  `setBufferSize(int bufferSize)`
  Sets the buffer size.
  `B`
  `setBufferSize(Integer bufferSize)`
  Sets the buffer size.
  `B`
  `setBufferSizeChecker(IntUnaryOperator bufferSizeChecker)`
  Sets the buffer size checker function.
  `protected B`
  `setBufferSizeDefault(int bufferSizeDefault)`
  Sets the buffer size for subclasses to initialize.
  `B`
  `setBufferSizeMax(int bufferSizeMax)`
  The maximum buffer size checked by the buffer size checker.
  `B`
  `setCharset(String charset)`
  Sets the Charset.
  `B`
  `setCharset(Charset charset)`
  Sets the Charset.
  `protected B`
  `setCharsetDefault(Charset defaultCharset)`
  Sets the Charset default for subclasses to initialize.
  `B`
  `setOpenOptions(OpenOption... openOptions)`
  Sets the OpenOption array.

  ### Methods inherited from class org.apache.commons.io.build.AbstractOriginSupplier

  `checkOrigin, getOrigin, hasOrigin, newByteArrayOrigin, newChannelOrigin, newCharSequenceOrigin, newFileOrigin, newFileOrigin, newInputStreamOrigin, newOutputStreamOrigin, newPathOrigin, newPathOrigin, newRandomAccessFileOrigin, newRandomAccessFileOrigin, newReaderOrigin, newURIOrigin, newWriterOrigin, setByteArray, setChannel, setCharSequence, setFile, setFile, setInputStream, setOrigin, setOutputStream, setPath, setPath, setRandomAccessFile, setRandomAccessFile, setReader, setURI, setWriter`

  ### Methods inherited from class org.apache.commons.io.build.AbstractSupplier

  `asThis`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.apache.commons.io.function.IOSupplier

  `asSupplier, get, getUnchecked`

- ## Constructor Details

  - ### AbstractStreamBuilder

    public AbstractStreamBuilder()
    Constructs a new instance for subclasses.

- ## Method Details

  - ### getBufferSize

    public int getBufferSize()
    Gets the buffer size, defaults to `IOUtils.DEFAULT_BUFFER_SIZE` (8192).
    Returns:
      the buffer size, defaults to `IOUtils.DEFAULT_BUFFER_SIZE` (8192).

  - ### getBufferSizeDefault

    public int getBufferSizeDefault()
    Gets the buffer size default, defaults to `IOUtils.DEFAULT_BUFFER_SIZE` (8192).
    Returns:
      the buffer size default, defaults to `IOUtils.DEFAULT_BUFFER_SIZE` (8192).

  - ### getByteArray

    public byte[] getByteArray() throws IOException
    Gets a byte array from the origin.
    Returns:
      A byte array.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a byte array.
      `IOException` - if an I/O error occurs.
    Since:
      2.22.0
    See Also:
      - `AbstractOrigin.getByteArray()`

  - ### getChannel

    public <C extends Channel> C getChannel(Class<C> channelType) throws IOException
    Gets a Channel from the origin with OpenOption[].
    Type Parameters:
      `C` - The channel type.
    Parameters:
      `channelType` - The channel type, not null.
    Returns:
      A channel of the specified type.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a `ReadableByteChannel`.
      `IOException` - if an I/O error occurs.
    Since:
      2.21.0
    See Also:
      - `AbstractOrigin.getChannel(java.lang.Class<C>, java.nio.file.OpenOption...)`
      - `getOpenOptions()`

  - ### getCharSequence

    public CharSequence getCharSequence() throws IOException
    Gets a CharSequence from the origin with a Charset.
    Returns:
      An input stream.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a CharSequence.
      `IOException` - if an I/O error occurs.
    Since:
      2.13.0
    See Also:
      - `AbstractOrigin.getCharSequence(Charset)`

  - ### getCharset

    public Charset getCharset()
    Gets the Charset, defaults to `Charset.defaultCharset()`.
    Returns:
      the Charset, defaults to `Charset.defaultCharset()`.

  - ### getCharsetDefault

    public Charset getCharsetDefault()
    Gets the Charset default, defaults to `Charset.defaultCharset()`.
    Returns:
      the Charset default, defaults to `Charset.defaultCharset()`.

  - ### getFile

    public File getFile()
    Gets a File from the origin.
    Returns:
      A File.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a `File`.
    Since:
      2.18.0
    See Also:
      - `AbstractOrigin.getPath()`

  - ### getInputStream

    public InputStream getInputStream() throws IOException
    Gets an InputStream from the origin with OpenOption[].
    Returns:
      An input stream.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to an `InputStream`.
      `IOException` - if an I/O error occurs.
    Since:
      2.13.0
    See Also:
      - `AbstractOrigin.getInputStream(OpenOption...)`
      - `getOpenOptions()`

  - ### getOpenOptions

    public OpenOption[] getOpenOptions()
    Gets the OpenOption array.
    Returns:
      the OpenOption array, this is not a defensive copy, modify at your own risk.

  - ### getOutputStream

    public OutputStream getOutputStream() throws IOException
    Gets an OutputStream from the origin with OpenOption[].
    Returns:
      An OutputStream.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to an `OutputStream`.
      `IOException` - if an I/O error occurs.
    Since:
      2.13.0
    See Also:
      - `AbstractOrigin.getOutputStream(OpenOption...)`
      - `getOpenOptions()`

  - ### getPath

    public Path getPath()
    Gets a Path from the origin.
    Returns:
      A Path.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a `Path`.
    Since:
      2.13.0
    See Also:
      - `AbstractOrigin.getPath()`

  - ### getRandomAccessFile

    public RandomAccessFile getRandomAccessFile() throws IOException
    Gets a RandomAccessFile from the origin.
    Returns:
      A RandomAccessFile.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a `RandomAccessFile`.
      `IOException` - if an I/O error occurs.
    Since:
      2.18.0

  - ### getReader

    public Reader getReader() throws IOException
    Gets a Reader from the origin with a Charset.
    Returns:
      A Reader.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a `Reader`.
      `IOException` - if an I/O error occurs.
    Since:
      2.16.0
    See Also:
      - `AbstractOrigin.getReader(Charset)`
      - `getCharset()`

  - ### getWriter

    public Writer getWriter() throws IOException
    Gets a Writer from the origin with an OpenOption[].
    Returns:
      An writer.
    Throws:
      `IllegalStateException` - if the `origin` is `null`.
      `UnsupportedOperationException` - if the origin cannot be converted to a `Writer`.
      `IOException` - if an I/O error occurs.
    Since:
      2.13.0
    See Also:
      - `AbstractOrigin.getOutputStream(OpenOption...)`
      - `getOpenOptions()`

  - ### setBufferSize

    public B setBufferSize(int bufferSize)
    Sets the buffer size. Invalid input (bufferSize <= 0) resets the value to its default.

    Subclasses may ignore this setting.

    Parameters:
      `bufferSize` - the buffer size, 0 resets to the default from `getBufferSizeDefault()`.
    Returns:
      `this` instance.

  - ### setBufferSize

    public B setBufferSize(Integer bufferSize)
    Sets the buffer size.

    Subclasses may ignore this setting.

    Parameters:
      `bufferSize` - the buffer size, null resets to the default from `getBufferSizeDefault()`.
    Returns:
      `this` instance.

  - ### setBufferSizeChecker

    public B setBufferSizeChecker(IntUnaryOperator bufferSizeChecker)
    Sets the buffer size checker function. Throws a `IllegalArgumentException` by default.
    Parameters:
      `bufferSizeChecker` - the buffer size checker function. null resets to the default behavior.
    Returns:
      `this` instance.
    Since:
      2.14.0

  - ### setBufferSizeDefault

    protected B setBufferSizeDefault(int bufferSizeDefault)
    Sets the buffer size for subclasses to initialize.

    Subclasses may ignore this setting.

    Parameters:
      `bufferSizeDefault` - the buffer size, 0 resets to the default `IOUtils.DEFAULT_BUFFER_SIZE`.
    Returns:
      `this` instance.

  - ### setBufferSizeMax

    public B setBufferSizeMax(int bufferSizeMax)
    The maximum buffer size checked by the buffer size checker. Values less or equal to 0, resets to the int max value. By default, if this value is exceeded, this methods throws an `IllegalArgumentException`.
    Parameters:
      `bufferSizeMax` - maximum buffer size checked by the buffer size checker.
    Returns:
      `this` instance.
    Since:
      2.14.0

  - ### setCharset

    public B setCharset(Charset charset)
    Sets the Charset.

    Subclasses may ignore this setting.

    Parameters:
      `charset` - the Charset, null resets to the default.
    Returns:
      `this` instance.

  - ### setCharset

    public B setCharset(String charset)
    Sets the Charset.

    Subclasses may ignore this setting.

    Parameters:
      `charset` - the Charset name, null resets to the default.
    Returns:
      `this` instance.

  - ### setCharsetDefault

    protected B setCharsetDefault(Charset defaultCharset)
    Sets the Charset default for subclasses to initialize.

    Subclasses may ignore this setting.

    Parameters:
      `defaultCharset` - the Charset name, null resets to the default.
    Returns:
      `this` instance.

  - ### setOpenOptions

    public B setOpenOptions(OpenOption... openOptions)
    Sets the OpenOption array.

    Normally used with InputStream, OutputStream, and Writer.

    Subclasses may ignore this setting.

    Parameters:
      `openOptions` - the OpenOption[] name, null resets to the default, a defensive copy is made.
    Returns:
      `this` instance.
    Since:
      2.13.0
    See Also:
      - `AbstractOriginSupplier.setInputStream(InputStream)`
      - `AbstractOriginSupplier.setOutputStream(OutputStream)`
      - `AbstractOriginSupplier.setWriter(Writer)`