de.esoco.coroutine.step.nio

Class AsynchronousFileStep

java.lang.Object

org.obrel.core.RelatedObject

de.esoco.coroutine.CoroutineStep<I,O>

de.esoco.coroutine.step.nio.AsynchronousChannelStep<java.nio.ByteBuffer,java.nio.ByteBuffer>

de.esoco.coroutine.step.nio.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.

Nested Class Summary

Nested classes/interfaces inherited from class de.esoco.coroutine.step.nio.AsynchronousChannelStep

AsynchronousChannelStep.ChannelCallback<V,C extends java.nio.channels.AsynchronousChannel>, AsynchronousChannelStep.ChannelOperation<C extends java.nio.channels.AsynchronousChannel>

Field Summary

Fields

Modifier and Type	Field and 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.

Fields inherited from class de.esoco.coroutine.step.nio.AsynchronousChannelStep

CHANNEL_GROUP

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected java.nio.ByteBuffer	execute(java.nio.ByteBuffer rData, Continuation<?> rContinuation) This method must be implemented by subclasses to provide the actual functionality of this step.
protected java.nio.channels.AsynchronousFileChannel	getFileChannel(Continuation<?> rContinuation) 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 sFileName, java.nio.file.OpenOption rMode, java.nio.file.OpenOption... rExtraOptions) A helper function that opens a file channel for a certain file name and open options.
protected abstract boolean	performAsyncOperation(int nBytesProcessed, java.nio.channels.AsynchronousFileChannel rChannel, java.nio.ByteBuffer rData, AsynchronousChannelStep.ChannelCallback<java.lang.Integer,java.nio.channels.AsynchronousFileChannel> rCallback) Implementation of the ChannelOperation functional interface method signature.
protected abstract void	performBlockingOperation(java.nio.channels.AsynchronousFileChannel aChannel, java.nio.ByteBuffer rData) Must be implemented for the blocking execution of a step.
void	runAsync(java.util.concurrent.CompletableFuture<java.nio.ByteBuffer> fPreviousExecution, CoroutineStep<java.nio.ByteBuffer,?> rNextStep, Continuation<?> rContinuation) 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 de.esoco.coroutine.step.nio.AsynchronousChannelStep

getChannelGroup

Methods inherited from class de.esoco.coroutine.CoroutineStep

fail, runBlocking, terminateCoroutine, toString

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 org.obrel.core.FluentRelatable

with, with, with

Methods inherited from interface org.obrel.core.Relatable

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

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

_with

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> fGetFileChannel)

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:

fGetFileChannel - A function that opens a file channel for the current continuation

Method Detail

openFileChannel

protected static java.nio.channels.AsynchronousFileChannel openFileChannel(java.lang.String sFileName,
                                                                           java.nio.file.OpenOption rMode,
                                                                           java.nio.file.OpenOption... rExtraOptions)

A helper function that opens a file channel for a certain file name and open options.

Parameters:

sFileName - The file name

rMode - The open option for the file access mode (e.g. READ, WRITE)

rExtraOptions - Optional extra file open options

Returns:

The file channel

runAsync

public void runAsync(java.util.concurrent.CompletableFuture<java.nio.ByteBuffer> fPreviousExecution,
                     CoroutineStep<java.nio.ByteBuffer,?> rNextStep,
                     Continuation<?> rContinuation)

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:

fPreviousExecution - The future of the previous code execution

rNextStep - The next step to execute or NULL for none

rContinuation - The continuation of the execution

performAsyncOperation

protected abstract boolean performAsyncOperation(int nBytesProcessed,
                                                 java.nio.channels.AsynchronousFileChannel rChannel,
                                                 java.nio.ByteBuffer rData,
                                                 AsynchronousChannelStep.ChannelCallback<java.lang.Integer,java.nio.channels.AsynchronousFileChannel> rCallback)
                                          throws java.lang.Exception

Implementation of the ChannelOperation functional interface method signature.

Throws:

java.lang.Exception

See Also:

AsynchronousChannelStep.ChannelOperation.execute(int,java.nio.channels.AsynchronousChannel, ByteBuffer, AsynchronousChannelStep.ChannelCallback)

performBlockingOperation

protected abstract void performBlockingOperation(java.nio.channels.AsynchronousFileChannel aChannel,
                                                 java.nio.ByteBuffer rData)
                                          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:

aChannel - The channel to perform the operation on

rData - The byte buffer for the operation data

Throws:

java.lang.Exception - Any kind of exception may be thrown

execute

protected java.nio.ByteBuffer execute(java.nio.ByteBuffer rData,
                                      Continuation<?> rContinuation)

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:

rData - The input value

rContinuation - The continuation of the execution

Returns:

The result of the execution

getFileChannel

protected java.nio.channels.AsynchronousFileChannel getFileChannel(Continuation<?> rContinuation)
                                                            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:

rContinuation - 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