uk.ac.starlink.fits
Class MappedFile

java.lang.Object
  uk.ac.starlink.fits.AbstractArrayDataIO
      uk.ac.starlink.fits.MappedFile

All Implemented Interfaces:

java.io.DataInput, java.io.DataOutput, nom.tam.util.ArrayDataInput, nom.tam.util.ArrayDataOutput, nom.tam.util.RandomAccess

public class MappedFile
extends AbstractArrayDataIO
implements nom.tam.util.RandomAccess

Provides mapped access to a data buffer using a single mapped byte buffer, compatible with nom.tam.util classes.

This class implements the nom.tam.util ArrayDataInput, ArrayDataOutput and RandomAccess interfaces in the same way that nom.tam.util.BufferedFile does. Hence it can be used as a drop-in replacement for BufferedFile. Unlike BufferedFile however, it does mapped access to files (using java.nio.Buffer objects). This may be moderately more efficient for sequential access to a file, but is dramatically more efficient if very random access is required. This is because BufferedFile effectively always assumes that you are going to read sequentially, so that accessing a single datum distant from (or before) the last datum accessed always results in filling a whole buffer.

Limitations:

• Files larger than Integer.MAX_VALUE bytes may not currently be accessed
• Access to very large files may fail if virtual memory runs out

Since:

30 Aug 2002

Nested Class Summary

static class

MappedFile.FileTooLongException Exception indicating that a file is too long to map.

Constructor Summary

MappedFile(java.nio.ByteBuffer buf)
Constructs a MappedFile object from a byte buffer.

MappedFile(java.lang.String filename)
Constructs a MappedFile object by mapping the whole of an existing file using read-only mode.

MappedFile(java.lang.String filename, java.lang.String mode)
Constructs a MappedFile object by mapping the whole of an existing file with a given mode.

MappedFile(java.lang.String filename, java.lang.String mode, long start, int size)
Constructs a MappedFile object by mapping part of an existing file with a given mode.

Method Summary

void	close()
void	flush()
protected byte	get() Reads one byte from the current position.
protected void	get(byte[] buf, int offset, int length) Reads bytes into a buffer from the current position.
long	getFilePointer()
long	length() Returns the size of this buffer.
void	mark(int readlimit)
boolean	markSupported()
protected void	put(byte b) Writes a single byte at the current position.
protected void	put(byte[] buf, int offset, int length) Writes bytes from a buffer to the current position.
protected long	remaining() Returns the number of bytes remaining between the current position and the end of the file.
void	reset()
void	seek(long offsetFromStart)
long	skip(long offset)
void	skipAllBytes(int toSkip)
void	skipAllBytes(long toSkip)
int	skipBytes(int toSkip)

Methods inherited from class uk.ac.starlink.fits.AbstractArrayDataIO

read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, readArray, readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLArray, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, writeArray, writeBoolean, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF

Methods inherited from class java.lang.Object

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

Methods inherited from interface nom.tam.util.ArrayDataInput

read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, readArray

Methods inherited from interface java.io.DataInput

readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF

Constructor Detail

MappedFile

public MappedFile(java.nio.ByteBuffer buf)

Constructs a MappedFile object from a byte buffer.

Parameters:

buf - byte buffer

MappedFile

public MappedFile(java.lang.String filename)
           throws java.io.IOException

Constructs a MappedFile object by mapping the whole of an existing file using read-only mode.

Parameters:

filename - name of the file to map

Throws:

MappedFile.FileTooLongException - if the file is too long to map

java.io.IOException

MappedFile

public MappedFile(java.lang.String filename,
                  java.lang.String mode)
           throws java.io.IOException

Constructs a MappedFile object by mapping the whole of an existing file with a given mode.

Parameters:

filename - name of the file to map

mode - mode

Throws:

MappedFile.FileTooLongException - if the file is too long to map

java.io.IOException

MappedFile

public MappedFile(java.lang.String filename,
                  java.lang.String mode,
                  long start,
                  int size)
           throws java.io.IOException

Constructs a MappedFile object by mapping part of an existing file with a given mode.

Parameters:

filename - name of the file to map

mode - mode

start - offset of region to map

size - length of region to map

Throws:

java.io.IOException

Method Detail

seek

public void seek(long offsetFromStart)
          throws java.io.IOException

Specified by:

seek in interface nom.tam.util.RandomAccess

Throws:

java.io.IOException

skip

public long skip(long offset)

Specified by:

skip in interface nom.tam.util.ArrayDataInput

getFilePointer

public long getFilePointer()

Specified by:

getFilePointer in interface nom.tam.util.RandomAccess

skipBytes

public int skipBytes(int toSkip)

Specified by:

skipBytes in interface java.io.DataInput

skipAllBytes

public void skipAllBytes(long toSkip)
                  throws java.io.IOException

Throws:

java.io.IOException

skipAllBytes

public void skipAllBytes(int toSkip)
                  throws java.io.IOException

Throws:

java.io.IOException

markSupported

public boolean markSupported()

mark

public void mark(int readlimit)

reset

public void reset()
           throws java.io.IOException

Throws:

java.io.IOException

get

protected byte get()
            throws java.io.IOException

Description copied from class: AbstractArrayDataIO

Reads one byte from the current position.

Specified by:

get in class AbstractArrayDataIO

Returns:

next byte

Throws:

java.io.IOException

get

protected void get(byte[] buf,
                   int offset,
                   int length)
            throws java.io.IOException

Description copied from class: AbstractArrayDataIO

Reads bytes into a buffer from the current position.

Specified by:

get in class AbstractArrayDataIO

Parameters:

buf - destination buffer

offset - offset of first byte in buf to be written

length - maximum number of bytes to be written to buf

Throws:

java.io.IOException

put

protected void put(byte b)
            throws java.io.IOException

Description copied from class: AbstractArrayDataIO

Writes a single byte at the current position.

Specified by:

put in class AbstractArrayDataIO

Parameters:

b - output byte

Throws:

java.io.IOException

put

protected void put(byte[] buf,
                   int offset,
                   int length)
            throws java.io.IOException

Description copied from class: AbstractArrayDataIO

Writes bytes from a buffer to the current position.

Specified by:

put in class AbstractArrayDataIO

Parameters:

buf - source buffer

offset - offset of first byte in buf to be read

length - number of bytes from buf to be read

Throws:

java.io.IOException

length

public long length()

Description copied from class: AbstractArrayDataIO

Returns the size of this buffer. May be -1 if not known/unlimited.

Specified by:

length in class AbstractArrayDataIO

Returns:

length or -1

remaining

protected long remaining()

Description copied from class: AbstractArrayDataIO

Returns the number of bytes remaining between the current position and the end of the file. If there is no end to the file, it is permissible to return Long.MAX_VALUE;

Specified by:

remaining in class AbstractArrayDataIO

Returns:

number of bytes left in file

close

public void close()

Specified by:

close in interface nom.tam.util.ArrayDataInput

Specified by:

close in interface nom.tam.util.ArrayDataOutput

flush

public void flush()

Specified by:

flush in interface nom.tam.util.ArrayDataOutput