Class MappedByteBufferInputStream
- java.lang.Object
-
- java.io.InputStream
-
- com.jogamp.common.nio.MappedByteBufferInputStream
-
- All Implemented Interfaces:
Closeable
,AutoCloseable
public class MappedByteBufferInputStream extends InputStream
AnInputStream
implementation based on an underlyingFileChannel
's memory mappedByteBuffer
,supporting
mark
andreset()
.Implementation allows full memory mapped
ByteBuffer
coverage viaFileChannel
beyond its size limitation ofInteger.MAX_VALUE
utilizing an array ofByteBuffer
slices.
Implementation further allows full random access via
position()
andposition(long)
and accessing the memory mappedByteBuffer
slices directly viacurrentSlice()
andnextSlice()
.- Since:
- 2.3.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
MappedByteBufferInputStream.CacheMode
static interface
MappedByteBufferInputStream.FileResizeOp
File resize interface allowing a file to change its size, e.g.
-
Field Summary
Fields Modifier and Type Field Description static int
DEFAULT_SLICE_SHIFT
Default slice shift, i.e.
-
Constructor Summary
Constructors Constructor Description MappedByteBufferInputStream(FileChannel fileChannel)
Creates a new instance using the givenFileChannel
,read-only
mapping mode,MappedByteBufferInputStream.CacheMode.FLUSH_PRE_HARD
and theDEFAULT_SLICE_SHIFT
.MappedByteBufferInputStream(FileChannel fileChannel, FileChannel.MapMode mmode, MappedByteBufferInputStream.CacheMode cmode)
Creates a new instance using the givenFileChannel
, given mapping-mode, given cache-mode and theDEFAULT_SLICE_SHIFT
.MappedByteBufferInputStream(FileChannel fileChannel, FileChannel.MapMode mmode, MappedByteBufferInputStream.CacheMode cmode, int sliceShift)
Creates a new instance using the givenFileChannel
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description int
available()
Seeremaining()
for an accurate variant.void
close()
ByteBuffer
currentSlice()
Return the mappedByteBuffer
slice at the currentposition()
.void
flush(boolean metaData)
Similar toOutputStream.flush()
, synchronizes all mapped buffers from local storage viaMappedByteBuffer.force()
as well as theFileChannel.force(boolean)
w/ometaData
.void
flushSlices()
Releases the mappedByteBuffer
slices.MappedByteBufferInputStream.CacheMode
getCacheMode()
Return the usedMappedByteBufferInputStream.CacheMode
.MappedByteBufferOutputStream
getOutputStream(MappedByteBufferInputStream.FileResizeOp fileResizeOp)
Returns a new MappedByteBufferOutputStream instance sharing all resources of this input stream, including all buffer slices.boolean
getSynchronous()
Returnsynchronous mode
.long
length()
Returns the total size in bytes of theInputStream
void
mark(int readlimit)
boolean
markSupported()
ByteBuffer
nextSlice()
Return the next mappedByteBuffer
slice from the currentposition()
, implicitly settingposition(long)
to the start of the returned next slice, seecurrentSlice()
.void
notifyLengthChange(long newTotalSize)
Notify this instance that the underlyingFileChannel
's size has been changed and adjusting this instances buffer slices and states accordingly.long
position()
Returns the absolute position of theInputStream
.MappedByteBufferInputStream
position(long newPosition)
Sets the absolute position of theInputStream
tonewPosition
.int
read()
int
read(byte[] b, int off, int len)
int
read(ByteBuffer b, int len)
Perform similar toread(byte[], int, int)
withByteBuffer
instead of byte array.long
remaining()
Returns the number of remaining available bytes of theInputStream
, i.e.void
reset()
void
setFileResizeOp(MappedByteBufferInputStream.FileResizeOp fileResizeOp)
void
setLength(long newTotalSize)
Resize the underlyingFileChannel
's size and adjusting this instance viaaccordingly
.void
setSynchronous(boolean s)
Enable or disable synchronous mode.long
skip(long n)
-
Methods inherited from class java.io.InputStream
nullInputStream, read, readAllBytes, readNBytes, readNBytes, transferTo
-
-
-
-
Field Detail
-
DEFAULT_SLICE_SHIFT
public static final int DEFAULT_SLICE_SHIFT
Default slice shift, i.e. 1L << shift, denoting slice size in MiB:64bit machines
-> 30 = 1024 MiB32bit 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
-
-
Constructor Detail
-
MappedByteBufferInputStream
public MappedByteBufferInputStream(FileChannel fileChannel, FileChannel.MapMode mmode, MappedByteBufferInputStream.CacheMode cmode, int sliceShift) throws IOException
Creates a new instance using the givenFileChannel
.The
ByteBuffer
slices will be mapped lazily at first usage.- Parameters:
fileChannel
- the file channel to be mapped lazily.mmode
- the map mode, default isFileChannel.MapMode.READ_ONLY
.cmode
- the caching mode, default isMappedByteBufferInputStream.CacheMode.FLUSH_PRE_HARD
.sliceShift
- the pow2 slice size, default isDEFAULT_SLICE_SHIFT
.- Throws:
IOException
-
MappedByteBufferInputStream
public MappedByteBufferInputStream(FileChannel fileChannel, FileChannel.MapMode mmode, MappedByteBufferInputStream.CacheMode cmode) throws IOException
Creates a new instance using the givenFileChannel
, given mapping-mode, given cache-mode and theDEFAULT_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 isFileChannel.MapMode.READ_ONLY
.cmode
- the caching mode, default isMappedByteBufferInputStream.CacheMode.FLUSH_PRE_HARD
.- Throws:
IOException
-
MappedByteBufferInputStream
public MappedByteBufferInputStream(FileChannel fileChannel) throws IOException
Creates a new instance using the givenFileChannel
,read-only
mapping mode,MappedByteBufferInputStream.CacheMode.FLUSH_PRE_HARD
and theDEFAULT_SLICE_SHIFT
.The
ByteBuffer
slices will be mappedFileChannel.MapMode.READ_ONLY
lazily at first usage.- Parameters:
fileChannel
- the file channel to be used.- Throws:
IOException
-
-
Method Detail
-
setSynchronous
public final void setSynchronous(boolean s)
Enable or disable synchronous mode.If synchronous mode is enabled, mapped buffers will be
flushed
ifresized
, written to orclosing
inread-write
mapping mode.If synchronous mode is enabled,
FileChannel.force(boolean)
is issued ifresizing
orclosing
and not inread-only
mapping mode.- Parameters:
s
-true
to enable synchronous mode
-
getSynchronous
public final boolean getSynchronous()
Returnsynchronous mode
.
-
close
public final void close() throws IOException
- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Overrides:
close
in classInputStream
- Throws:
IOException
-
setFileResizeOp
public final void setFileResizeOp(MappedByteBufferInputStream.FileResizeOp fileResizeOp) throws IllegalStateException
- Parameters:
fileResizeOp
- the newMappedByteBufferInputStream.FileResizeOp
.- Throws:
IllegalStateException
- if attempting to set theMappedByteBufferInputStream.FileResizeOp
to a different value than before
-
setLength
public final void setLength(long newTotalSize) throws IOException
Resize the underlyingFileChannel
's size and adjusting this instance viaaccordingly
.User must have a
MappedByteBufferInputStream.FileResizeOp
registered
before.Implementation calls
notifyLengthChange(long)
afterMappedByteBufferInputStream.FileResizeOp.setLength(long)
.- Parameters:
newTotalSize
- the new total size- Throws:
IOException
- if noMappedByteBufferInputStream.FileResizeOp
has beenregistered
or if a buffer slice operation failed
-
notifyLengthChange
public final void notifyLengthChange(long newTotalSize) throws IOException
Notify this instance that the underlyingFileChannel
'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- Throws:
IOException
- if a buffer slice operation failed
-
flush
public final void flush(boolean metaData) throws IOException
Similar toOutputStream.flush()
, synchronizes all mapped buffers from local storage viaMappedByteBuffer.force()
as well as theFileChannel.force(boolean)
w/ometaData
.- Parameters:
metaData
- TODO- Throws:
IOException
- if this stream has beenclosed
.
-
getOutputStream
public final MappedByteBufferOutputStream getOutputStream(MappedByteBufferInputStream.FileResizeOp fileResizeOp) throws IllegalStateException, IOException
Returns a new MappedByteBufferOutputStream instance sharing all resources of this input stream, including all buffer slices.- Throws:
IllegalStateException
- if attempting to set theMappedByteBufferInputStream.FileResizeOp
to a different value than beforeIOException
- if this instance was opened w/FileChannel.MapMode.READ_ONLY
or if this stream has beenclosed
.
-
currentSlice
public final ByteBuffer currentSlice() throws IOException
Return the mappedByteBuffer
slice at the currentposition()
.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 viaposition(long)
orskip(long)
to a position within the next block, similar tonextSlice()
.- Throws:
IOException
- if a buffer slice operation failed.
-
nextSlice
public final ByteBuffer nextSlice() throws IOException
Return the next mappedByteBuffer
slice from the currentposition()
, implicitly settingposition(long)
to the start of the returned next slice, seecurrentSlice()
.If no subsequent slice is available,
null
is being returned.- Throws:
IOException
- if a buffer slice operation failed.
-
flushSlices
public final void flushSlices() throws IOException
Releases the mappedByteBuffer
slices.- Throws:
IOException
- if a buffer slice operation failed.
-
getCacheMode
public final MappedByteBufferInputStream.CacheMode getCacheMode()
Return the usedMappedByteBufferInputStream.CacheMode
.If a desired
MappedByteBufferInputStream.CacheMode
is not available, it may fall back to an available one at runtime, seeMappedByteBufferInputStream.CacheMode.FLUSH_PRE_HARD
.
This evaluation only happens if theMappedByteBufferInputStream.CacheMode
!=MappedByteBufferInputStream.CacheMode.FLUSH_NONE
and while attempting to flush an unused buffer slice.
-
length
public final long length()
Returns the total size in bytes of theInputStream
0 <=
position()
<=length()
-
remaining
public final long remaining() throws IOException
Returns the number of remaining available bytes of theInputStream
, i.e.
.length()
-position()
0 <=
position()
<=length()
In contrast to
InputStream
'savailable()
method, this method returns the proper return typelong
.- Throws:
IOException
- if a buffer slice operation failed.
-
available
public final int available() throws IOException
Seeremaining()
for an accurate variant.- Overrides:
available
in classInputStream
- Throws:
IOException
- if a buffer slice operation failed.
-
position
public final long position() throws IOException
Returns the absolute position of theInputStream
.0 <=
position()
<=length()
- Throws:
IOException
- if a buffer slice operation failed.
-
position
public final MappedByteBufferInputStream position(long newPosition) throws IOException
- Parameters:
newPosition
- The new position, which must be non-negative and ≤length()
.- Returns:
- this instance
- Throws:
IOException
- if a buffer slice operation failed or stream isclosed
.
-
markSupported
public final boolean markSupported()
- Overrides:
markSupported
in classInputStream
-
mark
public final void mark(int readlimit)
Parameter
readLimit
is not used in this implementation, since the whole file is memory mapped and no read limitation occurs.- Overrides:
mark
in classInputStream
-
reset
public final void reset() throws IOException
- Overrides:
reset
in classInputStream
- Throws:
IOException
- if this stream has not been marked, a buffer slice operation failed or stream has beenclosed
.
-
skip
public final long skip(long n) throws IOException
- Overrides:
skip
in classInputStream
- Throws:
IOException
- if a buffer slice operation failed or stream isclosed
.
-
read
public final int read() throws IOException
- Specified by:
read
in classInputStream
- Throws:
IOException
-
read
public final int read(byte[] b, int off, int len) throws IOException
- Overrides:
read
in classInputStream
- Throws:
IOException
-
read
public final int read(ByteBuffer b, int len) throws IOException
Perform similar toread(byte[], int, int)
withByteBuffer
instead of byte array.- Parameters:
b
- theByteBuffer
sink, data is written at currentBuffer.position()
len
- the number of bytes to read- Returns:
- the number of bytes read, -1 for EOS
- Throws:
IOException
- if a buffer slice operation failed or stream has beenclosed
.
-
-