com.jmatio.io

Class MatFileReader

java.lang.Object

com.jmatio.io.MatFileReader

public class MatFileReader
extends Object

MAT-file reader. Reads MAT-file into MLArray objects. Usage:

 //read in the file
 MatFileReader mfr = new MatFileReader( "mat_file.mat" );
 
 //get array of a name "my_array" from file
 MLArray mlArrayRetrived = mfr.getMLArray( "my_array" );
 
 //or get the collection of all arrays that were stored in the file
 Map content = mfr.getContent();
 

Author:

Wojciech Gradkowski (wgradkowski@gmail.com)

See Also:

MatFileFilter

Field Summary

Fields

Modifier and Type	Field and Description
static int	DIRECT_BYTE_BUFFER
static int	HEAP_BYTE_BUFFER
static int	MEMORY_MAPPED_FILE
static String	UNMAP_NOT_SUPPORTED_REASON if UNMAP_SUPPORTED is false, this contains the reason why unmapping is not supported.
static boolean	UNMAP_SUPPORTED true, if this platform supports unmapping mmapped files.

Constructor Summary

Constructors

Constructor and Description
MatFileReader()
MatFileReader(File file) Creates instance of MatFileReader and reads MAT-file from file.
MatFileReader(File file, MatFileFilter filter) Creates instance of MatFileReader and reads MAT-file from file.
MatFileReader(String fileName) Creates instance of MatFileReader and reads MAT-file from location given as fileName.
MatFileReader(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
Map<String,MLArray>	getContent() Returns a map of MLArray objects that were inside MAT-file.
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(String name) Returns the value to which the red file maps the specified array name.
Map<String,MLArray>	read(File file) Reads the content of a MAT-file and returns the mapped content.
Map<String,MLArray>	read(File file, int policy) Reads the content of a MAT-file and returns the mapped content.
Map<String,MLArray>	read(File file, MatFileFilter filter, int policy) Reads the content of a MAT-file and returns the mapped content.
static void	setAllowObjectDeserialization(boolean allowDeserialization) Java objects can be stored in an MAT file.

Methods inherited from class java.lang.Object

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

Field Detail

UNMAP_SUPPORTED

public static final boolean UNMAP_SUPPORTED

true, if this platform supports unmapping mmapped files.

UNMAP_NOT_SUPPORTED_REASON

public static final String UNMAP_NOT_SUPPORTED_REASON

if UNMAP_SUPPORTED is false, this contains the reason why unmapping is not supported.

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

Constructor Detail

MatFileReader

public MatFileReader(String fileName)
              throws 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:

IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader(String fileName,
                     MatFileFilter filter)
              throws 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

filter - array name filter.

Throws:

IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader(File file)
              throws IOException

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

Parameters:

file - the MAT-file

Throws:

IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader(File file,
                     MatFileFilter filter)
              throws 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, int)

Parameters:

file - the MAT-file

filter - array name filter.

Throws:

IOException - when error occurred while processing the file.

MatFileReader

public MatFileReader()

Method Detail

setAllowObjectDeserialization

public static void setAllowObjectDeserialization(boolean allowDeserialization)

Java objects can be stored in an MAT file. If you do not absolutely trust the source of the file, it is better to leave this set to the default value: false. See: owasp's description

Parameters:

allowDeserialization - whether or not to allow deserialization of Java objects

read

public Map<String,MLArray> read(File file)
                         throws 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:

IOException - if error occurs during file processing

read

public Map<String,MLArray> read(File file,
                                int policy)
                         throws 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:

IOException - if error occurs during file processing

read

public Map<String,MLArray> read(File file,
                                MatFileFilter filter,
                                int policy)
                         throws IOException

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

Parameters:

file - a valid MAT-file file to be read

filter - the array filter applied during reading

policy - the file memory allocation policy

Returns:

the same as getContent()

Throws:

IOException - if error occurs during file processing

See Also:

MatFileFilter

getMatFileHeader

public MatFileHeader getMatFileHeader()

Gets MAT-file header

Returns:

- a MatFileHeader object

getData

public 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(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:

name - - 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 Map<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.