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)
• ¹ = Characters are converted to bytes using the default Charset.
• ² 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 java.io.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.
<C extends java.nio.channels.Channel> C	getChannel(java.lang.Class<C> channelType, java.nio.file.OpenOption... options)	Gets this origin as a Channel of the given type, if possible.
protected java.nio.channels.Channel	getChannel(java.nio.file.OpenOption... options)	Gets this origin as a Channel, if possible.
java.lang.CharSequence	getCharSequence(java.nio.charset.Charset charset)	Gets this origin as a byte array, if possible.
java.io.File	getFile()	Gets this origin as a File, if possible.
java.io.InputStream	getInputStream(java.nio.file.OpenOption... options)	Gets this origin as an InputStream, if possible.
java.io.OutputStream	getOutputStream(java.nio.file.OpenOption... options)	Gets this origin as an OutputStream, if possible.
java.nio.file.Path	getPath()	Gets this origin as a Path, if possible.
java.io.RandomAccessFile	getRandomAccessFile(java.nio.file.OpenOption... openOption)	Gets this origin as a RandomAccessFile, if possible.
java.io.Reader	getReader(java.nio.charset.Charset charset)	Gets a new Reader on the origin, buffered by default.
java.io.Writer	getWriter(java.nio.charset.Charset charset, java.nio.file.OpenOption... options)	Gets a new Writer on the origin, buffered by default.
long	size()	Gets the size of the origin, if possible.
java.lang.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 Detail

AbstractOrigin

protected AbstractOrigin(T origin)

Constructs a new instance for subclasses.

Parameters:

origin - The origin, not null.

Throws:

java.lang.NullPointerException - if origin is null.

Method Detail

get

public T get()

Gets the origin, never null.

Returns:

the origin, never null.

See Also:

IOSupplier.getUnchecked()

getByteArray

public byte[] getByteArray()
                    throws java.io.IOException

Gets this origin as a byte array, if possible.

Returns:

this origin as a byte array, if possible.

Throws:

java.io.IOException - if an I/O error occurs.

java.lang.UnsupportedOperationException - if the origin cannot be converted to a Path.

getByteArray

public byte[] getByteArray(long position,
                           int length)
                    throws java.io.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:

java.lang.UnsupportedOperationException - if the origin cannot be converted to a Path.

java.lang.ArithmeticException - if the position overflows an int

java.io.IOException - if an I/O error occurs.

Since:

2.13.0

getChannel

public final <C extends java.nio.channels.Channel> C getChannel(java.lang.Class<C> channelType,
                                                                java.nio.file.OpenOption... options)
                                                         throws java.io.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:

java.io.IOException - If an I/O error occurs.

java.lang.UnsupportedOperationException - If this origin cannot be converted to a channel of the given type.

Since:

2.21.0

See Also:

getChannel(OpenOption...)

getChannel

protected java.nio.channels.Channel getChannel(java.nio.file.OpenOption... options)
                                        throws java.io.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:

java.io.IOException - If an I/O error occurs.

java.lang.UnsupportedOperationException - If this origin cannot be converted to a channel.

Since:

2.21.0

See Also:

getChannel(Class, OpenOption...)

getCharSequence

public java.lang.CharSequence getCharSequence(java.nio.charset.Charset charset)
                                       throws java.io.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:

java.io.IOException - if an I/O error occurs.

java.lang.UnsupportedOperationException - if the origin cannot be converted to a Path.

getFile

public java.io.File getFile()

Gets this origin as a File, if possible.

Returns:

this origin as a File, if possible.

Throws:

java.lang.UnsupportedOperationException - if this method is not implemented in a concrete subclass.

getInputStream

public java.io.InputStream getInputStream(java.nio.file.OpenOption... options)
                                   throws java.io.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:

java.io.IOException - if an I/O error occurs.

java.lang.UnsupportedOperationException - if the origin cannot be converted to a Path.

getOutputStream

public java.io.OutputStream getOutputStream(java.nio.file.OpenOption... options)
                                     throws java.io.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:

java.io.IOException - if an I/O error occurs.

java.lang.UnsupportedOperationException - if the origin cannot be converted to a Path.

getPath

public java.nio.file.Path getPath()

Gets this origin as a Path, if possible.

Returns:

this origin as a Path, if possible.

Throws:

java.lang.UnsupportedOperationException - if this method is not implemented in a concrete subclass.

getRandomAccessFile

public java.io.RandomAccessFile getRandomAccessFile(java.nio.file.OpenOption... openOption)
                                             throws java.io.FileNotFoundException

Gets this origin as a RandomAccessFile, if possible.

Parameters:

openOption - options like StandardOpenOption.

Returns:

this origin as a RandomAccessFile, if possible.

Throws:

java.io.FileNotFoundException - See RandomAccessFile(File, String).

java.lang.UnsupportedOperationException - if this method is not implemented in a concrete subclass.

Since:

2.18.0

getReader

public java.io.Reader getReader(java.nio.charset.Charset charset)
                         throws java.io.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:

java.io.IOException - if an I/O error occurs opening the file.

getWriter

public java.io.Writer getWriter(java.nio.charset.Charset charset,
                                java.nio.file.OpenOption... options)
                         throws java.io.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:

java.io.IOException - if an I/O error occurs opening or creating the file.

java.lang.UnsupportedOperationException - if the origin cannot be converted to a Path.

size

public long size()
          throws java.io.IOException

Gets the size of the origin, if possible.

Returns:

the size of the origin in bytes or characters.

Throws:

java.io.IOException - if an I/O error occurs.

Since:

2.13.0

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object