uk.ac.starlink.fits
Class MappedFile

java.lang.Object
  |
  +--uk.ac.starlink.fits.MappedFile
All Implemented Interfaces:
ArrayDataInput, ArrayDataOutput, DataInput, DataOutput, RandomAccess

public class MappedFile
extends Object
implements ArrayDataInput, ArrayDataOutput, RandomAccess

Provides mapped access to a data 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.

The ArrayDataInput interface contains a lot of methods declared like

     int read(type[]) throws IOException;
 
whose behaviour is not documented - when do they throw an exception and what do they return? The behaviour implemented here follows that of the nom.tam.util.BufferedFile implementation (which is similarly undocumented). It is as follows:

Consult the BufferedFile documentation for more details.

Current limitations:

None of these is insurmountable, and future releases may remove these limitations.


Nested Class Summary
static class MappedFile.FileTooLongException
          Exception indicating that a file is too long to map.
 
Constructor Summary
MappedFile(ByteBuffer buf)
          Constructs a MappedFile object from a byte buffer.
MappedFile(String filename)
          Constructs a MappedFile object by mapping the whole of an existing file using read-only mode.
MappedFile(String filename, String mode)
          Constructs a MappedFile object by mapping the whole of an existing file with a given mode.
MappedFile(String filename, 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()
           
 long getFilePointer()
           
 int length()
          Returns the length of the file.
 int read(boolean[] buf)
           
 int read(boolean[] buf, int start, int length)
           
 int read(byte[] buf)
           
 int read(byte[] buf, int start, int length)
           
 int read(char[] buf)
           
 int read(char[] buf, int start, int length)
           
 int read(double[] buf)
           
 int read(double[] buf, int start, int length)
           
 int read(float[] buf)
           
 int read(float[] buf, int start, int length)
           
 int read(int[] buf)
           
 int read(int[] buf, int start, int length)
           
 int read(long[] buf)
           
 int read(long[] buf, int start, int length)
           
 int read(short[] buf)
           
 int read(short[] buf, int start, int length)
           
 int readArray(Object o)
           
 boolean readBoolean()
           
 byte readByte()
           
 char readChar()
           
 double readDouble()
           
 float readFloat()
           
 void readFully(byte[] buf)
           
 void readFully(byte[] buf, int start, int len)
          Reads a specified number of bytes into an array.
 int readInt()
           
 String readLine()
          Deprecated. see DataInputStream.readLine()
 long readLong()
           
 short readShort()
           
 int readUnsignedByte()
           
 int readUnsignedShort()
           
 String readUTF()
           
 void seek(long offsetFromStart)
           
 long skip(long offset)
           
 int skipBytes(int toSkip)
           
 void write(boolean[] buf)
           
 void write(boolean[] buf, int start, int length)
           
 void write(byte[] buf)
           
 void write(byte[] buf, int start, int length)
           
 void write(char[] buf)
           
 void write(char[] buf, int start, int length)
           
 void write(double[] buf)
           
 void write(double[] buf, int start, int length)
           
 void write(float[] buf)
           
 void write(float[] buf, int start, int length)
           
 void write(int val)
           
 void write(int[] buf)
           
 void write(int[] buf, int start, int length)
           
 void write(long[] buf)
           
 void write(long[] buf, int start, int length)
           
 void write(short[] buf)
           
 void write(short[] buf, int start, int length)
           
 void write(String[] strings)
           
 void write(String[] strings, int start, int length)
           
 void writeArray(Object o)
           
 void writeBoolean(boolean val)
           
 void writeByte(int val)
           
 void writeBytes(String s)
           
 void writeChar(int val)
           
 void writeChars(String s)
           
 void writeDouble(double val)
           
 void writeFloat(float val)
           
 void writeInt(int val)
           
 void writeLong(long val)
           
 void writeShort(int val)
           
 void writeUTF(String str)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MappedFile

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

Parameters:
buf - byte buffer

MappedFile

public MappedFile(String filename)
           throws 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
IOException

MappedFile

public MappedFile(String filename,
                  String mode)
           throws 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
IOException

MappedFile

public MappedFile(String filename,
                  String mode,
                  long start,
                  int size)
           throws 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
Method Detail

seek

public void seek(long offsetFromStart)
          throws IOException
Specified by:
seek in interface RandomAccess
IOException

skip

public long skip(long offset)
Specified by:
skip in interface ArrayDataInput

getFilePointer

public long getFilePointer()
Specified by:
getFilePointer in interface RandomAccess

skipBytes

public int skipBytes(int toSkip)
Specified by:
skipBytes in interface DataInput

length

public int length()
Returns the length of the file.

Returns:
file length in bytes

close

public void close()
Specified by:
close in interface ArrayDataInput

flush

public void flush()
Specified by:
flush in interface ArrayDataOutput

readBoolean

public boolean readBoolean()
                    throws EOFException
Specified by:
readBoolean in interface DataInput
EOFException

readByte

public byte readByte()
              throws EOFException
Specified by:
readByte in interface DataInput
EOFException

readShort

public short readShort()
                throws EOFException
Specified by:
readShort in interface DataInput
EOFException

readChar

public char readChar()
              throws EOFException
Specified by:
readChar in interface DataInput
EOFException

readInt

public int readInt()
            throws EOFException
Specified by:
readInt in interface DataInput
EOFException

readLong

public long readLong()
              throws EOFException
Specified by:
readLong in interface DataInput
EOFException

readFloat

public float readFloat()
                throws EOFException
Specified by:
readFloat in interface DataInput
EOFException

readDouble

public double readDouble()
                  throws EOFException
Specified by:
readDouble in interface DataInput
EOFException

readUnsignedByte

public int readUnsignedByte()
                     throws EOFException
Specified by:
readUnsignedByte in interface DataInput
EOFException

readUnsignedShort

public int readUnsignedShort()
                      throws EOFException
Specified by:
readUnsignedShort in interface DataInput
EOFException

readUTF

public String readUTF()
               throws IOException
Specified by:
readUTF in interface DataInput
IOException

readLine

public String readLine()
                throws IOException
Deprecated. see DataInputStream.readLine()

Not implemented - this method is deprecated in any case.

Specified by:
readLine in interface DataInput
Throws:
UnsupportedOperationException
IOException

readFully

public void readFully(byte[] buf,
                      int start,
                      int len)
               throws EOFException
Reads a specified number of bytes into an array. Unlike the read methods, this throws an EOFException if insufficient bytes are available. In this case all the bytes that can be read, will be read before the exception is thrown.

Specified by:
readFully in interface DataInput
Parameters:
buf - the byte buffer into which to read
start - the index in buf at which to start putting bytes
len - the number of bytes which must be read
Throws:
EOFException - if there are fewer than len bytes left

read

public int read(byte[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(boolean[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(short[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(char[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(int[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(long[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(float[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(double[] buf,
                int start,
                int length)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

readFully

public void readFully(byte[] buf)
               throws EOFException
Specified by:
readFully in interface DataInput
EOFException

read

public int read(byte[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(boolean[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(short[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(char[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(int[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(long[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(float[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

read

public int read(double[] buf)
         throws EOFException
Specified by:
read in interface ArrayDataInput
EOFException

readArray

public int readArray(Object o)
              throws EOFException
Specified by:
readArray in interface ArrayDataInput
EOFException

writeBoolean

public void writeBoolean(boolean val)
                  throws IOException
Specified by:
writeBoolean in interface DataOutput
IOException

writeByte

public void writeByte(int val)
               throws IOException
Specified by:
writeByte in interface DataOutput
IOException

writeShort

public void writeShort(int val)
                throws IOException
Specified by:
writeShort in interface DataOutput
IOException

writeChar

public void writeChar(int val)
               throws IOException
Specified by:
writeChar in interface DataOutput
IOException

writeInt

public void writeInt(int val)
              throws IOException
Specified by:
writeInt in interface DataOutput
IOException

writeLong

public void writeLong(long val)
               throws IOException
Specified by:
writeLong in interface DataOutput
IOException

writeFloat

public void writeFloat(float val)
                throws IOException
Specified by:
writeFloat in interface DataOutput
IOException

writeDouble

public void writeDouble(double val)
                 throws IOException
Specified by:
writeDouble in interface DataOutput
IOException

write

public void write(byte[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(boolean[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(short[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(char[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(int[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(long[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(float[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(double[] buf,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(String[] strings,
                  int start,
                  int length)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(int val)
           throws IOException
Specified by:
write in interface DataOutput
IOException

writeBytes

public void writeBytes(String s)
                throws IOException
Specified by:
writeBytes in interface DataOutput
IOException

writeChars

public void writeChars(String s)
                throws IOException
Specified by:
writeChars in interface DataOutput
IOException

writeUTF

public void writeUTF(String str)
              throws IOException
Specified by:
writeUTF in interface DataOutput
IOException

write

public void write(byte[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(boolean[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(short[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(char[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(int[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(long[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(float[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(double[] buf)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

write

public void write(String[] strings)
           throws IOException
Specified by:
write in interface ArrayDataOutput
IOException

writeArray

public void writeArray(Object o)
                throws IOException
Specified by:
writeArray in interface ArrayDataOutput
IOException

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.