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

Since:
2.12.0

  • Field Details

    • origin

      final T origin
      The non-null origin.

  • 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:

    • 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

      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:

    • 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.

    • getSimpleClassName

      private String getSimpleClassName()
      Gets simple name of the underlying class.
      Returns:
      The simple name of the underlying class.

    • 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

    • unsupportedChannelType

      UnsupportedOperationException unsupportedChannelType(Class<? extends Channel> channelType)

    • unsupportedOperation

      UnsupportedOperationException unsupportedOperation(String method)