Package de.esoco.coroutine.step.nio

Class AsynchronousFileStep

  • All Implemented Interfaces:
    de.esoco.lib.property.Fluent<CoroutineStep<java.nio.ByteBuffer,​java.nio.ByteBuffer>>, org.obrel.core.FluentRelatable<CoroutineStep<java.nio.ByteBuffer,​java.nio.ByteBuffer>>, org.obrel.core.Relatable
    Direct Known Subclasses:
    FileRead, FileWrite
    public abstract class AsynchronousFileStep
extends AsynchronousChannelStep<java.nio.ByteBuffer,​java.nio.ByteBuffer>
    The base class for coroutine steps that perform communication on instances of AsynchronousFileChannel. The channel will be opened and connected as necessary. It may also be provided before the step is invoked in a state relation with the type FILE_CHANNEL. If the channel is opened by this step it will have the MetaTypes.MANAGED flag so that it will be automatically closed when the CoroutineScope finishes.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static org.obrel.core.RelationType<java.nio.channels.AsynchronousFileChannel> FILE_CHANNEL
      State: the AsynchronousFileChannel that the steps in a coroutine operate on.
      static org.obrel.core.RelationType<java.lang.Long> FILE_POSITION
      The current position when reading from or writing to a file channel.

    • Constructor Summary

      Constructors 
      Constructor Description
      AsynchronousFileStep​(java.util.function.Function<Continuation<?>,​java.nio.channels.AsynchronousFileChannel> getFileChannel)
      Creates a new instance that opens a file channel with the given factory.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.nio.ByteBuffer execute​(java.nio.ByteBuffer input, Continuation<?> continuation)
      This method must be implemented by subclasses to provide the actual functionality of this step.
      protected java.nio.channels.AsynchronousFileChannel getFileChannel​(Continuation<?> continuation)
      Returns the channel to be used by this step.
      protected java.util.function.Function<Continuation<?>,​java.nio.channels.AsynchronousFileChannel> getFileChannelFactory()
      Returns the file channel factory of this step.
      protected static java.nio.channels.AsynchronousFileChannel openFileChannel​(java.lang.String fileName, java.nio.file.OpenOption mode, java.nio.file.OpenOption... extraOptions)
      A helper function that opens a file channel for a certain file name and open options.
      protected abstract boolean performAsyncOperation​(int bytesProcessed, java.nio.channels.AsynchronousFileChannel channel, java.nio.ByteBuffer data, AsynchronousChannelStep.ChannelCallback<java.lang.Integer,​java.nio.channels.AsynchronousFileChannel> callback)
      Implementation of the ChannelOperation functional interface method signature.
      protected abstract void performBlockingOperation​(java.nio.channels.AsynchronousFileChannel channel, java.nio.ByteBuffer data)
      Must be implemented for the blocking execution of a step.
      void runAsync​(java.util.concurrent.CompletableFuture<java.nio.ByteBuffer> previousExecution, CoroutineStep<java.nio.ByteBuffer,​?> nextStep, Continuation<?> continuation)
      Runs this execution step asynchronously as a continuation of a previous code execution in a CompletableFuture and proceeds to the next step afterwards.

      • Methods inherited from class org.obrel.core.RelatedObject

        deleteRelation, get, getRelation, getRelations, notifyRelationListeners, readRelations, relationsEqual, relationsHashCode, relationsString, set, set, transform, writeRelations

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface de.esoco.lib.property.Fluent

        _with

      • Methods inherited from interface org.obrel.core.FluentRelatable

        with, with, with

      • Methods inherited from interface org.obrel.core.Relatable

        deleteRelation, deleteRelation, deleteRelations, get, getAll, getOption, getRelation, getRelationCount, getRelations, getRelations, hasFlag, hasRelation, hasRelations, init, set, set, set, set, set, setOption, streamRelations, transform

    • Field Detail

      • FILE_CHANNEL

        public static final org.obrel.core.RelationType<java.nio.channels.AsynchronousFileChannel> FILE_CHANNEL
        State: the AsynchronousFileChannel that the steps in a coroutine operate on.

      • FILE_POSITION

        public static final org.obrel.core.RelationType<java.lang.Long> FILE_POSITION
        The current position when reading from or writing to a file channel. Can also be set in advance to start reading from that position instead of the file start.

    • Constructor Detail

      • AsynchronousFileStep

        public AsynchronousFileStep​(java.util.function.Function<Continuation<?>,​java.nio.channels.AsynchronousFileChannel> getFileChannel)
        Creates a new instance that opens a file channel with the given factory. The factory may return NULL if the step should use a file channel that is stored in a state relation with the type FILE_CHANNEL.
        Parameters:
        getFileChannel - A function that opens a file channel for the current continuation

    • Method Detail

      • openFileChannel

        protected static java.nio.channels.AsynchronousFileChannel openFileChannel​(java.lang.String fileName,
                                                                           java.nio.file.OpenOption mode,
                                                                           java.nio.file.OpenOption... extraOptions)
        A helper function that opens a file channel for a certain file name and open options.
        Parameters:
        fileName - The file name
        mode - The open option for the file access mode (e.g. READ, WRITE)
        extraOptions - Optional extra file open options
        Returns:
        The file channel

      • runAsync

        public void runAsync​(java.util.concurrent.CompletableFuture<java.nio.ByteBuffer> previousExecution,
                     CoroutineStep<java.nio.ByteBuffer,​?> nextStep,
                     Continuation<?> continuation)
        Runs this execution step asynchronously as a continuation of a previous code execution in a CompletableFuture and proceeds to the next step afterwards.

        Subclasses that need to suspend the invocation of the next step until some condition is met (e.g. sending or receiving data has finished) need to override this method and create a Suspension by invoking Continuation.suspend(CoroutineStep, CoroutineStep) on the next step. If the condition that caused the suspension resolves the coroutine execution can be resumed by calling Suspension.resume(Object).

        Subclasses that override this method also need to handle errors by terminating any further execution (i.e. not resuming a suspension if such exists) and forwarding the causing exception to Continuation.fail(Throwable).

        Overrides:
        runAsync in class CoroutineStep<java.nio.ByteBuffer,​java.nio.ByteBuffer>
        Parameters:
        previousExecution - The future of the previous code execution
        nextStep - The next step to execute or NULL for none
        continuation - The continuation of the execution

      • execute

        protected java.nio.ByteBuffer execute​(java.nio.ByteBuffer input,
                                      Continuation<?> continuation)
        This method must be implemented by subclasses to provide the actual functionality of this step.
        Specified by:
        execute in class CoroutineStep<java.nio.ByteBuffer,​java.nio.ByteBuffer>
        Parameters:
        input - The input value
        continuation - The continuation of the execution
        Returns:
        The result of the execution

      • getFileChannel

        protected java.nio.channels.AsynchronousFileChannel getFileChannel​(Continuation<?> continuation)
                                                            throws java.io.IOException
        Returns the channel to be used by this step. This first checks the currently exexcuting coroutine in the continuation parameter for an existing FILE_CHANNEL relation. If that doesn't exists or the channel is closed a new AsynchronousFileChannel will be opened and stored in the coroutine relation. Using the coroutine to store the channel allows coroutines to be structured so that multiple subroutines perform communication on different channels.
        Parameters:
        continuation - The continuation to query for an existing channel
        Returns:
        The socket channel
        Throws:
        java.io.IOException - If opening the channel fails

      • getFileChannelFactory

        protected java.util.function.Function<Continuation<?>,​java.nio.channels.AsynchronousFileChannel> getFileChannelFactory()
        Returns the file channel factory of this step.
        Returns:
        The file channel factory function

      • performBlockingOperation

        protected abstract void performBlockingOperation​(java.nio.channels.AsynchronousFileChannel channel,
                                                 java.nio.ByteBuffer data)
                                          throws java.lang.Exception
        Must be implemented for the blocking execution of a step. It receives an AsynchronousFileChannel which must be accessed through the blocking API (like Future.get()).
        Parameters:
        channel - The channel to perform the operation on
        data - The byte buffer for the operation data
        Throws:
        java.lang.Exception - Any kind of exception may be thrown