Package org.apache.sis.internal.storage.io

Class ChannelFactory

java.lang.Object
org.apache.sis.internal.storage.io.ChannelFactory
Direct Known Subclasses:
ChannelFactory.Fallback, ChannelFactory.Stream
public abstract class ChannelFactory extends Object
Opens a readable or writable channel for a given input object (URL, input stream, etc). The 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 static prepare(…) method. Callers are responsible for synchronizing their call to any member methods (readable(…), etc).
Since:
0.8
Version:
1.2

  • Field Details

    • ILLEGAL_OPTIONS

      private static final Set<StandardOpenOption> ILLEGAL_OPTIONS
      Options to be rejected by prepare(Object, boolean, String, OpenOption[]) for safety reasons, unless allowWriteOnly is true.

    • suggestDirectBuffer

      public final boolean suggestDirectBuffer
      Whether 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, or null if the given input/output is unsupported. More specifically:
      • If the given storage is null, then this method returns null.
      • If the given storage is a ReadableByteChannel or an InputStream, then the factory will return that input directly or indirectly as a wrapper.
      • If the given storage is a WritableByteChannel or an OutputStream and the allowWriteOnly argument is true, then the factory will return that output directly or indirectly as a wrapper.
      • If the given storage is a Path, File, URL, URI or CharSequence and the file is not a directory, then the factory will open new channels on demand.
      The given options are used for opening the channel on a best effort basis. In particular, even if the caller provided the WRITE option, (s)he still needs to verify if the returned channel implements WritableByteChannel. This is because the channel may be opened by URL.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 is false: 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, or null.
      allowWriteOnly - whether to allow wrapping WritableByteChannel and OutputStream.
      encoding - if the input is an encoded URL, the character encoding (normally "UTF-8"). If the URL is not encoded, then null. This argument is ignored if the given input does not need to be converted from URL to File.
      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, or null 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.

    • prepare

      private static ChannelFactory prepare(Object storage, boolean allowWriteOnly, String encoding, OpenOption[] options) throws IOException
      Returns a byte channel factory without wrappers, or null if unsupported. This method performs the same work than above method, but without wrappers.
      Parameters:
      storage - the stream or the file to open, or null.
      allowWriteOnly - whether to allow wrapping WritableByteChannel and OutputStream.
      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 the storage argument given to the prepare(…) method. This is true if the storage is an InputStream, OutputStream or Channel, and false if the storage is a Path, File, URL, URI or equivalent.
      Returns:
      whether using the streams or channels will affect the original storage object.

    • canOpen

      public boolean canOpen()
      Returns true if this factory is capable to create another readable byte channel. This method returns false if this factory is capable to create only one channel and readable(…) has already been invoked.
      Returns:
      whether readable(…) or writable(…) 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 a BufferedInputStream if desired.

      The default implementation wraps the channel returned by readable(String, StoreListeners). This wrapping is preferred to direct instantiation of FileInputStream in order to take in account the OpenOptions.

      Parameters:
      filename - data store name to report in case of failure.
      listeners - set of registered StoreListeners for the data store, or null 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 a BufferedOutputStream if desired.

      The default implementation wraps the channel returned by writable(String, StoreListeners). This wrapping is preferred to direct instantiation of FileOutputStream in order to take in account the OpenOptions.

      Parameters:
      filename - data store name to report in case of failure.
      listeners - set of registered StoreListeners for the data store, or null 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 the prepare(…) 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 registered StoreListeners for the data store, or null 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 the prepare(…) 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 registered StoreListeners for the data store, or null 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

      private static void recoverableException(Exception warning)
      Invoked for reporting exceptions that may be normal behavior. This method logs the exception at Level.FINE without stack trace.