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