Class ChannelFactory
- Direct Known Subclasses:
ChannelFactory.Fallback
,ChannelFactory.Stream
prepare(…)
method analyzes the given input Object
and tries to return a factory instance
capable to open at least a ReadableByteChannel
for that input. For some kinds of input like Path
or
URL
, the readable(…)
method can be invoked an arbitrary number of times for creating as many
channels as needed. But for other kinds of input like InputStream
, only one channel can be returned.
In such case, only the first readable(…)
method invocation will succeed and all subsequent ones
will throw an exception.
Multi-threading
This class is not thread-safe, except for the staticprepare(…)
method.
Callers are responsible for synchronizing their call to any member methods (readable(…)
, etc).- Since:
- 0.8
- Version:
- 1.2
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
private static final class
A factory that returns an existing channel as-is. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final Set
<StandardOpenOption> Options to be rejected byprepare(Object, boolean, String, OpenOption[])
for safety reasons, unlessallowWriteOnly
istrue
.final boolean
Whether this factory suggests to use direct buffers instead of heap buffers. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
ChannelFactory
(boolean suggestDirectBuffer) For subclass constructors. -
Method Summary
Modifier and TypeMethodDescriptionboolean
canOpen()
Returnstrue
if this factory is capable to create another readable byte channel.inputStream
(String filename, StoreListeners listeners) Returns the readable channel as an input stream.boolean
Returns whether the streams or channels created by this factory is coupled with thestorage
argument given to theprepare(…)
method.outputStream
(String filename, StoreListeners listeners) Returns the writable channel as an output stream.private static ChannelFactory
prepare
(Object storage, boolean allowWriteOnly, String encoding, OpenOption[] options) Returns a byte channel factory without wrappers, ornull
if unsupported.static ChannelFactory
prepare
(Object storage, boolean allowWriteOnly, String encoding, OpenOption[] options, UnaryOperator<ChannelFactory> wrapper) Returns a byte channel factory from the given input or output, ornull
if the given input/output is unsupported.abstract ReadableByteChannel
readable
(String filename, StoreListeners listeners) Returns a byte channel from the input given to theprepare(…)
method.private static void
recoverableException
(Exception warning) Invoked for reporting exceptions that may be normal behavior.abstract WritableByteChannel
writable
(String filename, StoreListeners listeners) Returns a byte channel from the output given to theprepare(…)
method.
-
Field Details
-
ILLEGAL_OPTIONS
Options to be rejected byprepare(Object, boolean, String, OpenOption[])
for safety reasons, unlessallowWriteOnly
istrue
. -
suggestDirectBuffer
public final boolean suggestDirectBufferWhether this factory suggests to use direct buffers instead of heap buffers. Direct buffer should be used for channels on the default file system or other native source of data, and avoided otherwise.
-
-
Constructor Details
-
ChannelFactory
protected ChannelFactory(boolean suggestDirectBuffer) For subclass constructors.- Parameters:
suggestDirectBuffer
- whether this factory suggests to use direct buffers instead of heap buffers.
-
-
Method Details
-
prepare
public static ChannelFactory prepare(Object storage, boolean allowWriteOnly, String encoding, OpenOption[] options, UnaryOperator<ChannelFactory> wrapper) throws IOException Returns a byte channel factory from the given input or output, ornull
if the given input/output is unsupported. More specifically:- If the given storage is
null
, then this method returnsnull
. - If the given storage is a
ReadableByteChannel
or anInputStream
, then the factory will return that input directly or indirectly as a wrapper. - If the given storage is a
WritableByteChannel
or anOutputStream
and theallowWriteOnly
argument istrue
, then the factory will return that output directly or indirectly as a wrapper. - If the given storage is a
Path
,File
,URL
,URI
orCharSequence
and the file is not a directory, then the factory will open new channels on demand.
WRITE
option, (s)he still needs to verify if the returned channel implementsWritableByteChannel
. This is because the channel may be opened byURL.openStream()
, in which case the options are ignored.The following options are illegal for read operations and will cause an exception to be thrown if provided while
allowWriteOnly
isfalse
:APPEND
,TRUNCATE_EXISTING
,DELETE_ON_CLOSE
. We reject those options because this method is primarily designed for readable channels, with optional data edition. Since the write option is not guaranteed to be honored, we have to reject the options that would alter significantly the channel behavior depending on whether we have been able to honor the options or not.- Parameters:
storage
- the stream or the file to open, ornull
.allowWriteOnly
- whether to allow wrappingWritableByteChannel
andOutputStream
.encoding
- if the input is an encoded URL, the character encoding (normally"UTF-8"
). If the URL is not encoded, thennull
. This argument is ignored if the given input does not need to be converted from URL toFile
.options
- the options to use for creating a new byte channel. Can be null or empty for read-only.wrapper
- a function for creating wrapper around the factory, ornull
if none. It can be used for installing listener or for transforming data on the fly.- Returns:
- the channel factory for the given input, or
null
if the given input is of unknown type. - Throws:
IOException
- if an error occurred while processing the given input.
- If the given storage is
-
prepare
private static ChannelFactory prepare(Object storage, boolean allowWriteOnly, String encoding, OpenOption[] options) throws IOException Returns a byte channel factory without wrappers, ornull
if unsupported. This method performs the same work thaninvalid reference
above method
- Parameters:
storage
- the stream or the file to open, ornull
.allowWriteOnly
- whether to allow wrappingWritableByteChannel
andOutputStream
.encoding
- if the input is an encoded URL, the character encoding (normally"UTF-8"
).options
- the options to use for creating a new byte channel. Can be null or empty for read-only.- Returns:
- the channel factory for the given input, or
null
if the given input is of unknown type. - Throws:
IOException
- if an error occurred while processing the given input.
-
isCoupled
public boolean isCoupled()Returns whether the streams or channels created by this factory is coupled with thestorage
argument given to theprepare(…)
method. This istrue
if the storage is anInputStream
,OutputStream
orChannel
, andfalse
if the storage is aPath
,File
,URL
,URI
or equivalent.- Returns:
- whether using the streams or channels will affect the original
storage
object.
-
canOpen
public boolean canOpen()Returnstrue
if this factory is capable to create another readable byte channel. This method returnsfalse
if this factory is capable to create only one channel andreadable(…)
has already been invoked.- Returns:
- whether
readable(…)
orwritable(…)
can be invoked.
-
inputStream
public InputStream inputStream(String filename, StoreListeners listeners) throws DataStoreException, IOException Returns the readable channel as an input stream. The returned stream is not buffered; it is caller's responsibility to wrap the stream in aBufferedInputStream
if desired.The default implementation wraps the channel returned by
readable(String, StoreListeners)
. This wrapping is preferred to direct instantiation ofFileInputStream
in order to take in account theOpenOption
s.- Parameters:
filename
- data store name to report in case of failure.listeners
- set of registeredStoreListener
s for the data store, ornull
if none.- Returns:
- the input stream.
- Throws:
DataStoreException
- if the channel is read-once.IOException
- if the input stream or its underlying byte channel cannot be created.
-
outputStream
public OutputStream outputStream(String filename, StoreListeners listeners) throws DataStoreException, IOException Returns the writable channel as an output stream. The returned stream is not buffered; it is caller's responsibility to wrap the stream in aBufferedOutputStream
if desired.The default implementation wraps the channel returned by
writable(String, StoreListeners)
. This wrapping is preferred to direct instantiation ofFileOutputStream
in order to take in account theOpenOption
s.- Parameters:
filename
- data store name to report in case of failure.listeners
- set of registeredStoreListener
s for the data store, ornull
if none.- Returns:
- the output stream.
- Throws:
DataStoreException
- if the channel is write-once.IOException
- if the output stream or its underlying byte channel cannot be created.
-
readable
public abstract ReadableByteChannel readable(String filename, StoreListeners listeners) throws DataStoreException, IOException Returns a byte channel from the input given to theprepare(…)
method. If the channel has already been created and this method cannot create it twice, then this method throws an exception.- Parameters:
filename
- data store name to report in case of failure.listeners
- set of registeredStoreListener
s for the data store, ornull
if none.- Returns:
- the channel for the given input.
- Throws:
DataStoreException
- if the channel is read-once.IOException
- if an error occurred while opening the channel.
-
writable
public abstract WritableByteChannel writable(String filename, StoreListeners listeners) throws DataStoreException, IOException Returns a byte channel from the output given to theprepare(…)
method. If the channel has already been created and this method cannot create it twice, then this method throws an exception.- Parameters:
filename
- data store name to report in case of failure.listeners
- set of registeredStoreListener
s for the data store, ornull
if none.- Returns:
- the channel for the given output.
- Throws:
DataStoreException
- if the channel is write-once.IOException
- if an error occurred while opening the channel.
-
recoverableException
Invoked for reporting exceptions that may be normal behavior. This method logs the exception atLevel.FINE
without stack trace.
-