An InputStream implementation based on an underlying FileChannel's memory mapped ByteBuffer, supporting mark and reset(). More...

Inheritance diagram for org.jau.io.MappedByteBufferInputStream:

Collaboration diagram for org.jau.io.MappedByteBufferInputStream:

Classes
enum	CacheMode

interface	FileResizeOp
	File resize interface allowing a file to change its size, e.g. More...

Public Member Functions
	MappedByteBufferInputStream (final FileChannel fileChannel, final FileChannel.MapMode mmode, final CacheMode cmode, final int sliceShift) throws IOException
	Creates a new instance using the given `FileChannel`. More...

	MappedByteBufferInputStream (final FileChannel fileChannel, final FileChannel.MapMode mmode, final CacheMode cmode) throws IOException
	Creates a new instance using the given `FileChannel`, given mapping-mode, given cache-mode and the `DEFAULT_SLICE_SHIFT`. More...

	MappedByteBufferInputStream (final FileChannel fileChannel) throws IOException
	Creates a new instance using the given `FileChannel`, `read-only` mapping mode, `CacheMode#FLUSH_PRE_HARD` and the `DEFAULT_SLICE_SHIFT`. More...

final synchronized void	setSynchronous (final boolean s)
	Enable or disable synchronous mode. More...

final synchronized boolean	getSynchronous ()
	Return `synchronous mode`. More...

final synchronized void	close () throws IOException

final synchronized void	setFileResizeOp (final FileResizeOp fileResizeOp) throws IllegalStateException

final synchronized void	setLength (final long newTotalSize) throws IOException
	Resize the underlying `FileChannel`'s size and adjusting this instance via `accordingly`. More...

final synchronized void	notifyLengthChange (final long newTotalSize) throws IOException
	Notify this instance that the underlying `FileChannel`'s size has been changed and adjusting this instances buffer slices and states accordingly. More...

final synchronized void	flush (final boolean metaData) throws IOException
	Similar to `OutputStream#flush()`, synchronizes all mapped buffers from local storage via `MappedByteBuffer#force()` as well as the `FileChannel#force(boolean)` w/o `metaData`. More...

final synchronized MappedByteBufferOutputStream	getOutputStream (final FileResizeOp fileResizeOp) throws IllegalStateException, IOException
	Returns a new MappedByteBufferOutputStream instance sharing all resources of this input stream, including all buffer slices. More...

final synchronized ByteBuffer	currentSlice () throws IOException
	Return the mapped `ByteBuffer` slice at the current `position()`. More...

final synchronized ByteBuffer	nextSlice () throws IOException
	Return the next mapped `ByteBuffer` slice from the current `position()`, implicitly setting `position(long)` to the start of the returned next slice, see `currentSlice()`. More...

final synchronized void	flushSlices () throws IOException
	Releases the mapped `ByteBuffer` slices. More...

final synchronized CacheMode	getCacheMode ()
	Return the used `CacheMode`. More...

final synchronized long	length ()
	Returns the total size in bytes of the `InputStream`. More...

final synchronized long	remaining () throws IOException
	Returns the number of remaining available bytes of the `InputStream`, i.e. More...

final synchronized int	available () throws IOException
	See `remaining()` for an accurate variant. More...

final synchronized long	position () throws IOException
	Returns the absolute position of the `InputStream`. More...

final synchronized MappedByteBufferInputStream	position (final long newPosition) throws IOException
	Sets the absolute position of the `InputStream` to `newPosition`. More...

final boolean	markSupported ()

final synchronized void	mark (final int readlimit)

final synchronized void	reset () throws IOException

final synchronized long	skip (final long n) throws IOException

final synchronized int	read () throws IOException

final synchronized int	read (final byte[] b, final int off, final int len) throws IOException

final synchronized int	read (final ByteBuffer b, final int len) throws IOException
	Perform similar to `read(byte[], int, int)` with `ByteBuffer` instead of byte array. More...

Static Public Attributes
static final int	DEFAULT_SLICE_SHIFT
	Default slice shift, i.e. More...

Detailed Description

An InputStream implementation based on an underlying FileChannel's memory mapped ByteBuffer, supporting mark and reset().

Implementation allows full memory mapped ByteBuffer coverage via FileChannel beyond its size limitation of Integer#MAX_VALUE utilizing an array of ByteBuffer slices.

Implementation further allows full random access via position() and position(long) and accessing the memory mapped ByteBuffer slices directly via currentSlice() and nextSlice().

Since: 0.3.0

Definition at line 56 of file MappedByteBufferInputStream.java.

Constructor & Destructor Documentation

◆ MappedByteBufferInputStream() [1/3]

org.jau.io.MappedByteBufferInputStream.MappedByteBufferInputStream	(	final FileChannel	fileChannel,
		final FileChannel.MapMode	mmode,
		final CacheMode	cmode,
		final int	sliceShift
	)		throws IOException

Creates a new instance using the given FileChannel.

The ByteBuffer slices will be mapped lazily at first usage.

Parameters

fileChannel	the file channel to be mapped lazily.
mmode	the map mode, default is `FileChannel.MapMode#READ_ONLY`.
cmode	the caching mode, default is `CacheMode#FLUSH_PRE_HARD`.
sliceShift	the pow2 slice size, default is `DEFAULT_SLICE_SHIFT`.

Exceptions

IOException

Definition at line 247 of file MappedByteBufferInputStream.java.

◆ MappedByteBufferInputStream() [2/3]

org.jau.io.MappedByteBufferInputStream.MappedByteBufferInputStream	(	final FileChannel	fileChannel,
		final FileChannel.MapMode	mmode,
		final CacheMode	cmode
	)		throws IOException

Creates a new instance using the given FileChannel, given mapping-mode, given cache-mode and the DEFAULT_SLICE_SHIFT.

The ByteBuffer slices will be mapped lazily at first usage.

Parameters

fileChannel	the file channel to be used.
mmode	the map mode, default is `FileChannel.MapMode#READ_ONLY`.
cmode	the caching mode, default is `CacheMode#FLUSH_PRE_HARD`.

Exceptions

IOException

Definition at line 265 of file MappedByteBufferInputStream.java.

◆ MappedByteBufferInputStream() [3/3]

org.jau.io.MappedByteBufferInputStream.MappedByteBufferInputStream ( final FileChannel fileChannel ) throws IOException

Creates a new instance using the given FileChannel, read-only mapping mode, CacheMode#FLUSH_PRE_HARD and the DEFAULT_SLICE_SHIFT.

The ByteBuffer slices will be mapped FileChannel.MapMode#READ_ONLY lazily at first usage.

Parameters

fileChannel the file channel to be used.

Exceptions

IOException

Definition at line 279 of file MappedByteBufferInputStream.java.

Member Function Documentation

◆ available()

final synchronized int org.jau.io.MappedByteBufferInputStream.available ( ) throws IOException

See remaining() for an accurate variant.

Exceptions

IOException if a buffer slice operation failed.

Definition at line 702 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ close()

final synchronized void org.jau.io.MappedByteBufferInputStream.close ( ) throws IOException

Definition at line 312 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ currentSlice()

final synchronized ByteBuffer org.jau.io.MappedByteBufferInputStream.currentSlice ( ) throws IOException

Return the mapped ByteBuffer slice at the current position().

Due to the nature of using sliced buffers mapping the whole region, user has to determine whether the returned buffer covers the desired region and may fetch the nextSlice() until satisfied.
It is also possible to repeat this operation after reposition the stream via position(long) or skip(long) to a position within the next block, similar to nextSlice().

Exceptions

IOException if a buffer slice operation failed.

Definition at line 503 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ flush()

final synchronized void org.jau.io.MappedByteBufferInputStream.flush ( final boolean metaData ) throws IOException

Similar to OutputStream#flush(), synchronizes all mapped buffers from local storage via MappedByteBuffer#force() as well as the FileChannel#force(boolean) w/o metaData.

Parameters

metaData TODO

Exceptions

IOException if this stream has been closed.

Definition at line 453 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ flushSlices()

final synchronized void org.jau.io.MappedByteBufferInputStream.flushSlices ( ) throws IOException

Releases the mapped ByteBuffer slices.

Exceptions

IOException if a buffer slice operation failed.

Definition at line 554 of file MappedByteBufferInputStream.java.

◆ getCacheMode()

final synchronized CacheMode org.jau.io.MappedByteBufferInputStream.getCacheMode ( )

Return the used CacheMode.

If a desired CacheMode is not available, it may fall back to an available one at runtime, see CacheMode#FLUSH_PRE_HARD.
This evaluation only happens if the CacheMode != CacheMode#FLUSH_NONE and while attempting to flush an unused buffer slice.

Definition at line 665 of file MappedByteBufferInputStream.java.

◆ getOutputStream()

final synchronized MappedByteBufferOutputStream org.jau.io.MappedByteBufferInputStream.getOutputStream ( final FileResizeOp fileResizeOp ) throws IllegalStateException, IOException

Returns a new MappedByteBufferOutputStream instance sharing all resources of this input stream, including all buffer slices.

Exceptions

IllegalStateException	if attempting to set the `FileResizeOp` to a different value than before
IOException	if this instance was opened w/ `FileChannel.MapMode#READ_ONLY` or if this stream has been `closed`.

Definition at line 483 of file MappedByteBufferInputStream.java.

◆ getSynchronous()

final synchronized boolean org.jau.io.MappedByteBufferInputStream.getSynchronous ( )

Return synchronous mode.

Definition at line 301 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ length()

final synchronized long org.jau.io.MappedByteBufferInputStream.length ( )

Returns the total size in bytes of the InputStream.

  0 <= position() <= length()

Definition at line 674 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ mark()

final synchronized void org.jau.io.MappedByteBufferInputStream.mark ( final int readlimit )

Parameter readLimit is not used in this implementation, since 0.3.0

Definition at line 782 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

◆ markSupported()

final boolean org.jau.io.MappedByteBufferInputStream.markSupported ( )

Definition at line 770 of file MappedByteBufferInputStream.java.

◆ nextSlice()

final synchronized ByteBuffer org.jau.io.MappedByteBufferInputStream.nextSlice ( ) throws IOException

Return the next mapped ByteBuffer slice from the current position(), implicitly setting position(long) to the start of the returned next slice, see currentSlice().

If no subsequent slice is available, null is being returned.

Exceptions

IOException if a buffer slice operation failed.

Definition at line 538 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ notifyLengthChange()

final synchronized void org.jau.io.MappedByteBufferInputStream.notifyLengthChange ( final long newTotalSize ) throws IOException

Notify this instance that the underlying FileChannel's size has been changed and adjusting this instances buffer slices and states accordingly.

Should be called by user API when aware of such event.

Parameters

newTotalSize the new total size

Exceptions

IOException if a buffer slice operation failed

Definition at line 391 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ position() [1/2]

final synchronized long org.jau.io.MappedByteBufferInputStream.position ( ) throws IOException

Returns the absolute position of the InputStream.

  0 <= position() <= length()

Exceptions

IOException if a buffer slice operation failed.

Definition at line 715 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ position() [2/2]

final synchronized MappedByteBufferInputStream org.jau.io.MappedByteBufferInputStream.position ( final long newPosition ) throws IOException

Sets the absolute position of the InputStream to newPosition.

  0 <= position() <= length()

Parameters

newPosition The new position, which must be non-negative and ≤ length().

Returns: this instance

Exceptions

IOException if a buffer slice operation failed or stream is closed.

Definition at line 733 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

◆ read() [1/3]

final synchronized int org.jau.io.MappedByteBufferInputStream.read ( ) throws IOException

Definition at line 824 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ read() [2/3]

final synchronized int org.jau.io.MappedByteBufferInputStream.read	(	final byte[]	b,
		final int	off,
		final int	len
	)		throws IOException

Definition at line 836 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

◆ read() [3/3]

final synchronized int org.jau.io.MappedByteBufferInputStream.read	(	final ByteBuffer	b,
		final int	len
	)		throws IOException

Perform similar to read(byte[], int, int) with ByteBuffer instead of byte array.

Parameters

b	the `ByteBuffer` sink, data is written at current `ByteBuffer#position()`
len	the number of bytes to read

Returns: the number of bytes read, -1 for EOS

Exceptions

IOException if a buffer slice operation failed or stream has been closed.

Definition at line 879 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

◆ remaining()

final synchronized long org.jau.io.MappedByteBufferInputStream.remaining ( ) throws IOException

Returns the number of remaining available bytes of the InputStream, i.e.

length() - position().

  0 <= position() <= length()

<p<blockquote>‍

In contrast to InputStream's available() method, this method returns the proper return type long.

Exceptions

IOException if a buffer slice operation failed.

Definition at line 690 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reset()

final synchronized void org.jau.io.MappedByteBufferInputStream.reset ( ) throws IOException

Exceptions

IOException if this stream has not been marked, a buffer slice operation failed or stream has been closed.

Definition at line 798 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

◆ setFileResizeOp()

final synchronized void org.jau.io.MappedByteBufferInputStream.setFileResizeOp ( final FileResizeOp fileResizeOp ) throws IllegalStateException

Parameters

fileResizeOp the new FileResizeOp.

Exceptions

IllegalStateException if attempting to set the FileResizeOp to a different value than before

Definition at line 338 of file MappedByteBufferInputStream.java.

◆ setLength()

final synchronized void org.jau.io.MappedByteBufferInputStream.setLength ( final long newTotalSize ) throws IOException

Resize the underlying FileChannel's size and adjusting this instance via accordingly.

User must have a FileResizeOp registered before.

Implementation calls notifyLengthChange(long) after FileResizeOp#setLength(long).

Parameters

newTotalSize the new total size

Exceptions

IOException if no FileResizeOp has been registered or if a buffer slice operation failed

Definition at line 358 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setSynchronous()

final synchronized void org.jau.io.MappedByteBufferInputStream.setSynchronous ( final boolean s )

Enable or disable synchronous mode.

If synchronous mode is enabled, mapped buffers will be flushed if resized, written to or closing in read-write mapping mode.

If synchronous mode is enabled, FileChannel#force(boolean) is issued if resizing or closing and not in read-only mapping mode.

Parameters

s	`true` to enable synchronous mode

Definition at line 295 of file MappedByteBufferInputStream.java.

Here is the caller graph for this function:

◆ skip()

final synchronized long org.jau.io.MappedByteBufferInputStream.skip ( final long n ) throws IOException

Exceptions

IOException if a buffer slice operation failed or stream is closed.

Definition at line 811 of file MappedByteBufferInputStream.java.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ DEFAULT_SLICE_SHIFT

final int org.jau.io.MappedByteBufferInputStream.DEFAULT_SLICE_SHIFT

static

Default slice shift, i.e.

1L << shift, denoting slice size in MiB:

64bit machines -> 30 = 1024 MiB
32bit machines -> 29 = 512 MiB

In case the default is too much of-used up address-space, one may choose other values:

29 -> 512 MiB
28 -> 256 MiB
27 -> 128 MiB
26 -> 64 MiB

Definition at line 132 of file MappedByteBufferInputStream.java.

The documentation for this class was generated from the following file:

java_base/org/jau/io/MappedByteBufferInputStream.java

Classes

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MappedByteBufferInputStream() [1/3]

◆ MappedByteBufferInputStream() [2/3]

◆ MappedByteBufferInputStream() [3/3]

Member Function Documentation

◆ available()

◆ close()

◆ currentSlice()

◆ flush()

◆ flushSlices()

◆ getCacheMode()

◆ getOutputStream()

◆ getSynchronous()

◆ length()

◆ mark()

◆ markSupported()

◆ nextSlice()

◆ notifyLengthChange()

◆ position() [1/2]

◆ position() [2/2]

◆ read() [1/3]

◆ read() [2/3]

◆ read() [3/3]

◆ remaining()

◆ reset()

◆ setFileResizeOp()

◆ setLength()

◆ setSynchronous()

◆ skip()

Member Data Documentation

◆ DEFAULT_SLICE_SHIFT