Package net.lecousin.framework.io

New java Input/Output model adding more flexibility and asynchronous operations.

See: Description

Interface Summary

Interface	Description
IO	Base interface for all IO, see the package documentation net.lecousin.framework.io.
IO.KnownSize	Add capability to know the size of an IO.
IO.OutputToInput	An OutputToInput is an IO on which a producer is writing, and a consumer is reading. The producer receive it as a Writable, and the consumer as a Readable. Both can work concurrently: as soon as data is written by the producer, it can be read by the consumer. The producer must call the method endOfData or signalErrorBeforeEndOfData, so the consumer can receive the information it reaches the end of the IO. The implementations may add additional capabilities such as Readable.Seekable if it keeps the data.
IO.PositionKnown	Capability to get the current position on an IO.
IO.Readable	Add the capability to read forward on an IO.
IO.Readable.Buffered	Indicates the IO is buffered, and add operations.
IO.Readable.Seekable	Add read operations to read at a specific position.
IO.ReadableByteStream	Add capability to read byte by byte, typically a buffered IO.
IO.Resizable	Add capability to resize the IO.
IO.Seekable	Capability to set the position on an IO.
IO.Writable	Add the capability to write forward on an IO.
IO.Writable.Buffered	Add a flush operation to force writing on the underlying IO.
IO.Writable.Seekable	Add operations to write at a specific position.
IO.WritableByteStream	Add capability to write byte by byte.
IO.WriterAsync	Simple interface for something to which we can write buffers asynchronously.
IOUtil.RecursiveAsyncSupplierListener.OnSuccess<T>	On success listener that receive the listener instance to perform recursive operation.

Class Summary

Class	Description
AbstractIO	Utility class as a base for IO implementations.
FileIO	IO on a file, using one of the 3 sub-classes: FileIO.ReadOnly, FileIO.WriteOnly, FileIO.ReadWrite.
FileIO.ReadOnly	FileIO in read-only mode.
FileIO.ReadWrite	FileIO with read and write operations.
FileIO.WriteOnly	FileIO in write-only mode.
FragmentedSubIO	A fragmented sub-IO allows to specify a list of fragments inside a seekable IO, and does like those fragments are a contiguous IO.
FragmentedSubIO.Readable	Readable fragmented IO.
FragmentedSubIO.ReadWrite	Readable and Writable fragmented IO.
IOAsInputStream	Convert an IO into an InputStream.
IOAsOutputStream	Convert an IO into an OutputStream.
IOAsOutputStream.ByteStream	Implementation of IOAsOutputStream for a WritableByteStream.
IOAsOutputStream.Writable	Default implementation of IOAsOutputStream for a Writable.
IOFromInputStream	Implements Readable from an InputStream.
IOFromInputStream.KnownSize	Add the capability to get the size to IOFromInputStream.
IOFromOutputStream	Implements Writable from an OutputStream.
IOUtil	Utility methods for IO.
IOUtil.RecursiveAsyncSupplierListener<T>	Recursive listener, forwarding error or cancel and calling onDone on error.
IOWritePool	This class can be used if you are writing to a IO.Writable, but you don't want to wait for the previous write to be done before to write again.
LinkedIO	Make several IOs as a single one.
LinkedIO.Readable	Linked Readable IO.
LinkedIO.Readable.Buffered	Linked Readable Buffered IO.
LinkedIO.Readable.Buffered.DeterminedSize	Linked Readable Buffered IO and add the DeterminedSize capability.
LinkedIO.Readable.DeterminedSize	Linked Readable IO and add the DeterminedSize capability.
LinkedIO.Readable.Seekable	Linked Readable Seekable IO.
LinkedIO.Readable.Seekable.Buffered	Linked Readable, Seekable and Buffered IO.
LinkedIO.Readable.Seekable.Buffered.DeterminedSize	Add the DeterminedSize capability.
LinkedIO.Readable.Seekable.DeterminedSize	Add the DeterminedSize capability.
LinkedIO.ReadWrite	Linked Readable and Writable IO.
PositionKnownWrapper<IOType extends IO>	Add the capability to known on which position we are on an IO.
PositionKnownWrapper.Readable	Add the capability to known on which position we are on a Readable.
PositionKnownWrapper.Readable.Buffered	Add the capability to known on which position we are on a Buffered Readable.
SubIO	Sub-part of an IO.
SubIO.Readable	Sub-part of a Readable IO.
SubIO.Readable.Seekable	Sub-part of a Seekable Readable IO.
SubIO.Readable.Seekable.Buffered	Sub-part of a Buffered Seekable Readable IO.
SubIO.ReadWrite	Sub-part of a Seekable Readable and Writable IO.
SubIO.Writable	Sub-part of a Writable IO.
SubIO.Writable.Seekable	Sub-part of a Seekable Writable IO.
TemporaryFiles	Utility class to create temporary files.

Enum Summary

Enum	Description
IO.OperationType	Synchronous ou asynchronous operation.
IO.Seekable.SeekType	List of possible seek operations.

Package net.lecousin.framework.io Description

New java Input/Output model adding more flexibility and asynchronous operations.

The model provided by Java is very basic and mainly based on streams (reading or writing forward).
Our model add two main additions:

• Flexibility by using interfaces that define the capabilities of an Input/Output implementation such as Readable, Writable, Seekable, Resizable, Buffered...
• Asynchronous operations allowing multi-threading

Interface defining capabilities

Each implementation defines its capabilities through a set of interfaces defined in IO:

• IO.Readable is similar to an InputStream: data can be read forward
• IO.Writable is similar to an OutputStream: data can be written forward
• IO.Seekable adds the capability to move backward or forward
• IO.Readable.Seekable extends IO.Readable, IO.Seekable and add operations to read data directly at a specific position
• IO.Writable.Seekable extends IO.Writable, IO.Seekable and add operations to write data directly at a specific position
• IO.PositionKnown adds the capability to get the current position
• IO.Resizable adds the capability to resize the IO
• IO.KnownSize adds the capability to know the current size of an IO
• IO.ReadableByteStream adds the capability to read a single byte instead of a buffer
• IO.WritableByteStream adds the capability to write a single byte instead of a buffer
• IO.Readable.Buffered defines a buffered Readable and adds some operations that are efficient when buffered
• IO.Writable.Buffered defines a buffered Writable and adds some operations that are efficient when buffered

By using those interfaces to define the capabilities of the IO adds much more flexibility:

• We can test the capabilities by using instanceof operator
• We can declare the required capabilities in a method signature using generics like this: public <T extends IO.Readable.Seekable & IO.Writable.Seekable> void myMethod(T io);

More details on each interface can be found on their respective Javadoc.

Bridges between Java IO and our model are available: IOFromInputStream, IOFromOutputStream, IOAsInputStream, IOAsOutputStream.

Asynchronous operations

Each interface define both synchronous and asynchronous operations.
Synchronous operations should be avoided when not on a Buffered implementation, but are still available when we want to keep an algorithm simple and synchronous, however those operations may block the thread waiting for the operation to complete.
Asynchronous operations allow to design multi-threaded algorithms and to do not block threads.