com.jmatio.io

Class MatFileReader

java.lang.Object

com.jmatio.io.MatFileReader

public class MatFileReader
extends java.lang.Object

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	MatFileReader.ISMatTag TAG operator.

Field Summary

Fields

Modifier and Type	Field and Description
private java.nio.ByteOrder	byteOrder Tells how bytes are organized in the buffer.
private java.util.Map<java.lang.String,MLArray>	data Container for red MLArrays
private static int	DIRECT_BUFFER_LIMIT Reads the content of a MAT-file and returns the mapped content.
static int	DIRECT_BYTE_BUFFER
private MatFileFilter	filter Array name filter
static int	HEAP_BYTE_BUFFER
private MatFileHeader	matFileHeader MAT-file header
static int	MEMORY_MAPPED_FILE

Constructor Summary

Constructors

Constructor and Description
MatFileReader()
MatFileReader(java.io.File file) Creates instance of MatFileReader and reads MAT-file from file.
MatFileReader(java.io.File file, MatFileFilter filter) Creates instance of MatFileReader and reads MAT-file from file.
MatFileReader(java.lang.String fileName) Creates instance of MatFileReader and reads MAT-file from location given as fileName.
MatFileReader(java.lang.String fileName, MatFileFilter filter) Creates instance of MatFileReader and reads MAT-file from location given as fileName.

Method Summary

Modifier and Type	Method and Description
private void	clean(java.lang.Object buffer) Workaround taken from bug #4724038 to release the memory mapped byte buffer.
java.util.Map<java.lang.String,MLArray>	getContent() Returns a map of MLArray objects that were inside MAT-file.
java.util.ArrayList<MLArray>	getData() Deprecated. use getContent which returns a Map to provide easier access to MLArrays contained in MAT-file
MatFileHeader	getMatFileHeader() Gets MAT-file header
MLArray	getMLArray(java.lang.String name) Returns the value to which the red file maps the specified array name.
java.util.Map<java.lang.String,MLArray>	read(java.io.File file) Reads the content of a MAT-file and returns the mapped content.
java.util.Map<java.lang.String,MLArray>	read(java.io.File file, int policy) Reads the content of a MAT-file and returns the mapped content.
java.util.Map<java.lang.String,MLArray>	read(java.io.File file, MatFileFilter filter, int policy)
private void	readData(java.nio.ByteBuffer buf) Reads data form byte buffer.
private int[]	readDimension(java.nio.ByteBuffer buf) Reads Matrix dimensions.
private int[]	readFlags(java.nio.ByteBuffer buf) Reads Matrix flags.
private void	readHeader(java.nio.ByteBuffer buf) Reads MAT-file header.
private MLArray	readMatrix(java.nio.ByteBuffer buf, boolean isRoot) Reads miMATRIX from from input stream.
private java.lang.String	readName(java.nio.ByteBuffer buf) Reads Matrix name.
private java.lang.String	zeroEndByteArrayToString(byte[] bytes) Converts byte array to String.

Methods inherited from class java.lang.Object

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

Field Detail

MEMORY_MAPPED_FILE

public static final int MEMORY_MAPPED_FILE

See Also:

Constant Field Values

DIRECT_BYTE_BUFFER

public static final int DIRECT_BYTE_BUFFER

See Also:

Constant Field Values

HEAP_BYTE_BUFFER

public static final int HEAP_BYTE_BUFFER

See Also:

Constant Field Values

matFileHeader

private MatFileHeader matFileHeader

MAT-file header

data

private java.util.Map<java.lang.String,MLArray> data

Container for red MLArrays

byteOrder

private java.nio.ByteOrder byteOrder

Tells how bytes are organized in the buffer.

filter

private MatFileFilter filter

Array name filter

DIRECT_BUFFER_LIMIT

private static final int DIRECT_BUFFER_LIMIT

Reads the content of a MAT-file and returns the mapped content.

Because of java bug #4724038 which disables releasing the memory mapped resource, additional different allocation modes are available.

• MEMORY_MAPPED_FILE - a memory mapped file
• DIRECT_BYTE_BUFFER - a uses ByteBuffer.allocateDirect(int) method to read in the file contents
• HEAP_BYTE_BUFFER - a uses ByteBuffer.allocate(int) method to read in the file contents

Note: memory mapped file will try to invoke a nasty code to relase it's resources

See Also:

MatFileFilter, Constant Field Values

Constructor Detail

MatFileReader

public MatFileReader(java.lang.String fileName)
              throws java.io.FileNotFoundException,
                     java.io.IOException

Creates instance of MatFileReader and reads MAT-file from location given as fileName. This method reads MAT-file without filtering.

Parameters:

fileName - the MAT-file path String

Throws:

java.io.IOException - when error occurred while processing the file.

java.io.FileNotFoundException

MatFileReader

public MatFileReader(java.lang.String fileName,
                     MatFileFilter filter)
              throws java.io.IOException

Creates instance of MatFileReader and reads MAT-file from location given as fileName. Results are filtered by MatFileFilter. Arrays that do not meet filter match condition will not be available in results.

Parameters:

fileName - the MAT-file path String

MatFileFilter - array name filter.

Throws:

java.io.IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader(java.io.File file)
              throws java.io.IOException

Creates instance of MatFileReader and reads MAT-file from file. This method reads MAT-file without filtering.

Parameters:

file - the MAT-file

Throws:

java.io.IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader(java.io.File file,
                     MatFileFilter filter)
              throws java.io.IOException

Creates instance of MatFileReader and reads MAT-file from file.

Results are filtered by MatFileFilter. Arrays that do not meet filter match condition will not be available in results.

Note: this method reads file using the memory mapped file policy, see notes to #read(File, MatFileFilter, com.jmatio.io.MatFileReader.MallocPolicy)

Parameters:

file - the MAT-file

MatFileFilter - array name filter.

Throws:

java.io.IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader()

Method Detail

read

public java.util.Map<java.lang.String,MLArray> read(java.io.File file)
                                             throws java.io.IOException

Reads the content of a MAT-file and returns the mapped content.

This method calls read(file, new MatFileFilter(), MallocPolicy.MEMORY_MAPPED_FILE).

Parameters:

file - a valid MAT-file file to be read

Returns:

the same as getContent()

Throws:

java.io.IOException - if error occurs during file processing

read

public java.util.Map<java.lang.String,MLArray> read(java.io.File file,
                                                    int policy)
                                             throws java.io.IOException

Reads the content of a MAT-file and returns the mapped content.

This method calls read(file, new MatFileFilter(), policy).

Parameters:

file - a valid MAT-file file to be read

policy - the file memory allocation policy

Returns:

the same as getContent()

Throws:

java.io.IOException - if error occurs during file processing

read

public java.util.Map<java.lang.String,MLArray> read(java.io.File file,
                                                    MatFileFilter filter,
                                                    int policy)
                                             throws java.io.IOException

Throws:

java.io.IOException

clean

private void clean(java.lang.Object buffer)
            throws java.lang.Exception

Workaround taken from bug #4724038 to release the memory mapped byte buffer.

Little quote from SUN: This is highly inadvisable, to put it mildly. It is exceedingly dangerous to forcibly unmap a mapped byte buffer that's visible to Java code. Doing so risks both the security and stability of the system

Since the memory byte buffer used to map the file is not exposed to the outside world, maybe it's save to use it without being cursed by the SUN. Since there is no other solution this will do (don't trust voodoo GC invocation)

Parameters:

buffer - the buffer to be unmapped

Throws:

java.lang.Exception - all kind of evil stuff

getMatFileHeader

public MatFileHeader getMatFileHeader()

Gets MAT-file header

Returns:

- a MatFileHeader object

getData

public java.util.ArrayList<MLArray> getData()

Deprecated. use getContent which returns a Map to provide easier access to MLArrays contained in MAT-file

Returns list of MLArray objects that were inside MAT-file

Returns:

- a ArrayList

getMLArray

public MLArray getMLArray(java.lang.String name)

Returns the value to which the red file maps the specified array name. Returns null if the file contains no content for this name.

Parameters:

- - array name

Returns:

- the MLArray to which this file maps the specified name, or null if the file contains no content for this name.

getContent

public java.util.Map<java.lang.String,MLArray> getContent()

Returns a map of MLArray objects that were inside MAT-file. MLArrays are mapped with MLArrays' names

Returns:

- a Map of MLArrays mapped with their names.

readData

private void readData(java.nio.ByteBuffer buf)
               throws java.io.IOException

Reads data form byte buffer. Searches for either miCOMPRESSED data or miMATRIX data. Compressed data are inflated and the product is recursively passed back to this same method. Modifies buf position.

Parameters:

buf - - input byte buffer

Throws:

java.io.IOException - when error occurs while reading the buffer.

readMatrix

private MLArray readMatrix(java.nio.ByteBuffer buf,
                           boolean isRoot)
                    throws java.io.IOException

Reads miMATRIX from from input stream. If reading was not finished (which is normal for filtered results) returns null. Modifies buf position to the position when reading finished. Uses recursive processing for some ML**** data types.

Parameters:

buf - - input byte buffer

isRoot - - when true informs that if this is a top level matrix

Returns:

- MLArray or null if matrix does not match filter

Throws:

java.io.IOException - when error occurs while reading the buffer.

zeroEndByteArrayToString

private java.lang.String zeroEndByteArrayToString(byte[] bytes)
                                           throws java.io.IOException

Converts byte array to String. It assumes that String ends with \0 value.

Parameters:

bytes - byte array containing the string.

Returns:

String retrieved from byte array.

Throws:

java.io.IOException - if reading error occurred.

readFlags

private int[] readFlags(java.nio.ByteBuffer buf)
                 throws java.io.IOException

Reads Matrix flags. Modifies buf position.

Parameters:

buf - ByteBuffer

Returns:

flags int array

Throws:

java.io.IOException - if reading from buffer fails

readDimension

private int[] readDimension(java.nio.ByteBuffer buf)
                     throws java.io.IOException

Reads Matrix dimensions. Modifies buf position.

Parameters:

buf - ByteBuffer

Returns:

dimensions int array

Throws:

java.io.IOException - if reading from buffer fails

readName

private java.lang.String readName(java.nio.ByteBuffer buf)
                           throws java.io.IOException

Reads Matrix name. Modifies buf position.

Parameters:

buf - ByteBuffer

Returns:

name String

Throws:

java.io.IOException - if reading from buffer fails

readHeader

private void readHeader(java.nio.ByteBuffer buf)
                 throws java.io.IOException

Reads MAT-file header. Modifies buf position.

Parameters:

buf - ByteBuffer

Throws:

java.io.IOException - if reading from buffer fails or if this is not a valid MAT-file