Package org.apache.commons.io.build

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

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

Type Parameters:
  `T` - the type produced by the builder.
  `B` - the concrete builder subclass type.

All Implemented Interfaces:
  `IOSupplier<T>`

Direct Known Subclasses:
  `AbstractOrigin.AbstractRandomAccessFileOrigin`, `AbstractOrigin.ByteArrayOrigin`, `AbstractOrigin.ChannelOrigin`, `AbstractOrigin.CharSequenceOrigin`, `AbstractOrigin.FileOrigin`, `AbstractOrigin.InputStreamOrigin`, `AbstractOrigin.OutputStreamOrigin`, `AbstractOrigin.PathOrigin`, `AbstractOrigin.ReaderOrigin`, `AbstractOrigin.URIOrigin`, `AbstractOrigin.WriterOrigin`

public abstract class AbstractOrigin<T,B extends AbstractOrigin<T,B>> extends AbstractSupplier<T,B>
Abstracts and wraps an origin for builders, where an origin is a `byte[]`, `Channel`, `CharSequence`, `File`, `InputStream`, `IORandomAccessFile`, `OutputStream`, `Path`, `RandomAccessFile`, `Reader`, `URI`, or `Writer`.

An origin represents where bytes/characters come from or go to. Concrete subclasses expose only the operations that make sense for the underlying source or sink; invoking an unsupported operation results in `UnsupportedOperationException` (see, for example, `getFile()` and `getPath()`).

An instance doesn't own its origin, it holds on to it to allow conversions. There are two use cases related to resource management for a Builder:

- A client allocates a Closeable (or AutoCloseable) resource, creates a Builder, and gives the Builder that resource by calling a setter method. No matter what happens next, the client is responsible for releasing the resource (`Closeable.close()`). In this case, the origin wraps but doesn't own the closeable resource. There is no transfer of ownership.
- A client creates a Builder and gives it a non-Closeable object, like a File or a Path. The client then calls the Builder's factory method (like get()), and that call returns a Closeable or a resource that requires releasing in some other way. No matter what happens next, the client is responsible for releasing that resource. In this case, the origin doesn't wrap a closeable resource.

In both cases, the client causes the allocation and is responsible for releasing the resource.

The table below summarizes which views and conversions are supported for each origin type. Column headers show the target view; cells indicate whether that view is available from the origin in that row.

Supported Conversions
Origin Type | byte[] | CS | File | Path | RAF | IS | Reader | RBC | OS | Writer | WBC | Channel type2
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
byte[] | ✔ | ✔ | ✖ | ✖ | ✖ | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | SBC
`CharSequence` (CS) | ✔ | ✔ | ✖ | ✖ | ✖ | ✔1 | ✔ | ✔1 | ✖ | ✖ | ✖ | SBC
`File` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | FC
`Path` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | FC
`IORandomAccessFile` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | FC
`RandomAccessFile` (RAF) | ✔ | ✔ | ✖ | ✖ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | FC
`InputStream` (IS) | ✔ | ✔ | ✖ | ✖ | ✖ | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | RBC
`Reader` | ✔ | ✔ | ✖ | ✖ | ✖ | ✔1 | ✔ | ✔1 | ✖ | ✖ | ✖ | RBC
`ReadableByteChannel` (RBC) | ✔ | ✔ | ✖ | ✖ | ✖ | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | RBC
`OutputStream` (OS) | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✔ | ✔ | ✔ | WBC
`Writer` | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✔1 | ✔ | ✔1 | WBC
`WritableByteChannel` (WBC) | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✖ | ✔ | ✔ | ✔ | WBC
`URI` (FileSystem) | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | FC
`URI` (http/https) | ✔ | ✔ | ✖ | ✖ | ✖ | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | RBC

Legend

- ✔ = Supported
- ✖ = Not supported (throws `UnsupportedOperationException`)
- 1 = Characters are converted to bytes using the default `Charset`.
- 2 Minimum channel type provided by the origin:
  - RBC = ReadableByteChannel
  - WBC = WritableByteChannel
  - SBC = SeekableByteChannel
  - FC = FileChannel
  The exact channel type may be a subtype of the minimum shown.

Since:
  2.12.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `AbstractOrigin.AbstractRandomAccessFileOrigin<T extends RandomAccessFile,B extends AbstractOrigin.AbstractRandomAccessFileOrigin<T,B>>`
  A `RandomAccessFile` origin.
  `static class`
  `AbstractOrigin.ByteArrayOrigin`
  A `byte[]` origin.
  `static class`
  `AbstractOrigin.ChannelOrigin`
  A `Channel` origin.
  `static class`
  `AbstractOrigin.CharSequenceOrigin`
  A `CharSequence` origin.
  `static class`
  `AbstractOrigin.FileOrigin`
  A `File` origin.
  `static class`
  `AbstractOrigin.InputStreamOrigin`
  An `InputStream` origin.
  `static class`
  `AbstractOrigin.IORandomAccessFileOrigin`
  An `IORandomAccessFile` origin.
  `static class`
  `AbstractOrigin.OutputStreamOrigin`
  An `OutputStream` origin.
  `static class`
  `AbstractOrigin.PathOrigin`
  A `Path` origin.
  `static class`
  `AbstractOrigin.RandomAccessFileOrigin`
  A `RandomAccessFile` origin.
  `static class`
  `AbstractOrigin.ReaderOrigin`
  A `Reader` origin.
  `static class`
  `AbstractOrigin.URIOrigin`
  A `URI` origin.
  `static class`
  `AbstractOrigin.WriterOrigin`
  A `Writer` origin.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractOrigin(T origin)`
  Constructs a new instance for subclasses.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `T`
  `get()`
  Gets the origin, never null.
  `byte[]`
  `getByteArray()`
  Gets this origin as a byte array, if possible.
  `byte[]`
  `getByteArray(long position, int length)`
  Gets a portion of this origin as a byte array, if possible.
  `final <C extends Channel>
  C`
  `getChannel(Class<C> channelType, OpenOption... options)`
  Gets this origin as a Channel of the given type, if possible.
  `protected Channel`
  `getChannel(OpenOption... options)`
  Gets this origin as a Channel, if possible.
  `CharSequence`
  `getCharSequence(Charset charset)`
  Gets this origin as a byte array, if possible.
  `File`
  `getFile()`
  Gets this origin as a File, if possible.
  `InputStream`
  `getInputStream(OpenOption... options)`
  Gets this origin as an InputStream, if possible.
  `OutputStream`
  `getOutputStream(OpenOption... options)`
  Gets this origin as an OutputStream, if possible.
  `Path`
  `getPath()`
  Gets this origin as a Path, if possible.
  `RandomAccessFile`
  `getRandomAccessFile(OpenOption... openOption)`
  Gets this origin as a RandomAccessFile, if possible.
  `Reader`
  `getReader(Charset charset)`
  Gets a new Reader on the origin, buffered by default.
  `Writer`
  `getWriter(Charset charset, OpenOption... options)`
  Gets a new Writer on the origin, buffered by default.
  `long`
  `size()`
  Gets the size of the origin, if possible.
  `String`
  `toString()`

  ### 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, wait, wait, wait`

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

  `asSupplier, getUnchecked`

- ## Constructor Details

  - ### AbstractOrigin

    protected AbstractOrigin(T origin)
    Constructs a new instance for subclasses.
    Parameters:
      `origin` - The origin, not null.
    Throws:
      `NullPointerException` - if `origin` is `null`.

- ## Method Details

  - ### get

    public T get()
    Gets the origin, never null.
    Returns:
      the origin, never null.
    See Also:
      - `IOSupplier.getUnchecked()`

  - ### getByteArray

    public byte[] getByteArray() throws IOException
    Gets this origin as a byte array, if possible.
    Returns:
      this origin as a byte array, if possible.
    Throws:
      `IOException` - if an I/O error occurs.
      `UnsupportedOperationException` - if the origin cannot be converted to a Path.

  - ### getByteArray

    public byte[] getByteArray(long position, int length) throws IOException
    Gets a portion of this origin as a byte array, if possible.
    Parameters:
      `position` - the initial index of the range to be copied, inclusive.
      `length` - How many bytes to copy.
    Returns:
      this origin as a byte array, if possible.
    Throws:
      `UnsupportedOperationException` - if the origin cannot be converted to a Path.
      `ArithmeticException` - if the `position` overflows an int.
      `IOException` - if an I/O error occurs.
    Since:
      2.13.0

  - ### getChannel

    public final <C extends Channel> C getChannel(Class<C> channelType, OpenOption... options) throws IOException
    Gets this origin as a Channel of the given type, if possible.
    Type Parameters:
      `C` - The type of channel to return.
    Parameters:
      `channelType` - The type of channel to return.
      `options` - Options specifying how a file-based origin is opened, ignored otherwise.
    Returns:
      A new Channel on the origin of the given type.
    Throws:
      `IOException` - If an I/O error occurs.
      `UnsupportedOperationException` - If this origin cannot be converted to a channel of the given type.
    Since:
      2.21.0
    See Also:
      - `getChannel(OpenOption...)`

  - ### getChannel

    protected Channel getChannel(OpenOption... options) throws IOException
    Gets this origin as a Channel, if possible.
    Parameters:
      `options` - Options specifying how a file-based origin is opened, ignored otherwise.
    Returns:
      A new Channel on the origin.
    Throws:
      `IOException` - If an I/O error occurs.
      `UnsupportedOperationException` - If this origin cannot be converted to a channel.
    Since:
      2.21.0
    See Also:
      - `getChannel(Class, OpenOption...)`

  - ### getCharSequence

    public CharSequence getCharSequence(Charset charset) throws IOException
    Gets this origin as a byte array, if possible.
    Parameters:
      `charset` - The charset to use if conversion from bytes is needed.
    Returns:
      this origin as a byte array, if possible.
    Throws:
      `IOException` - if an I/O error occurs.
      `UnsupportedOperationException` - if the origin cannot be converted to a Path.

  - ### getFile

    public File getFile()
    Gets this origin as a File, if possible.
    Returns:
      this origin as a File, if possible.
    Throws:
      `UnsupportedOperationException` - if this method is not implemented in a concrete subclass.

  - ### getInputStream

    public InputStream getInputStream(OpenOption... options) throws IOException
    Gets this origin as an InputStream, if possible.
    Parameters:
      `options` - options specifying how the file is opened.
    Returns:
      this origin as an InputStream, if possible.
    Throws:
      `IOException` - if an I/O error occurs.
      `UnsupportedOperationException` - if the origin cannot be converted to a Path.

  - ### getOutputStream

    public OutputStream getOutputStream(OpenOption... options) throws IOException
    Gets this origin as an OutputStream, if possible.
    Parameters:
      `options` - options specifying how the file is opened.
    Returns:
      this origin as an OutputStream, if possible.
    Throws:
      `IOException` - if an I/O error occurs.
      `UnsupportedOperationException` - if the origin cannot be converted to a Path.

  - ### getPath

    public Path getPath()
    Gets this origin as a Path, if possible.
    Returns:
      this origin as a Path, if possible.
    Throws:
      `UnsupportedOperationException` - if this method is not implemented in a concrete subclass.

  - ### getRandomAccessFile

    public RandomAccessFile getRandomAccessFile(OpenOption... openOption) throws FileNotFoundException
    Gets this origin as a RandomAccessFile, if possible.
    Parameters:
      `openOption` - options like `StandardOpenOption`.
    Returns:
      this origin as a RandomAccessFile, if possible.
    Throws:
      `FileNotFoundException` - See `RandomAccessFile(File, String)`.
      `UnsupportedOperationException` - if this method is not implemented in a concrete subclass.
    Since:
      2.18.0

  - ### getReader

    public Reader getReader(Charset charset) throws IOException
    Gets a new Reader on the origin, buffered by default.
    Parameters:
      `charset` - the charset to use for decoding, null maps to the default Charset.
    Returns:
      a new Reader on the origin.
    Throws:
      `IOException` - if an I/O error occurs opening the file.

  - ### getWriter

    public Writer getWriter(Charset charset, OpenOption... options) throws IOException
    Gets a new Writer on the origin, buffered by default.
    Parameters:
      `charset` - the charset to use for encoding.
      `options` - options specifying how the file is opened.
    Returns:
      a new Writer on the origin.
    Throws:
      `IOException` - if an I/O error occurs opening or creating the file.
      `UnsupportedOperationException` - if the origin cannot be converted to a Path.

  - ### size

    public long size() throws IOException
    Gets the size of the origin, if possible.
    Returns:
      the size of the origin in bytes or characters.
    Throws:
      `IOException` - if an I/O error occurs.
    Since:
      2.13.0

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`