com.amx.duet.tools.io
Class FileManager

java.lang.Object
  extended bycom.amx.duet.tools.io.FileManager

public class FileManager
extends java.lang.Object

The FileManager class was created in order to simulate NetLinx file processing. It allows you to open multiple files and manipulate each one individualy until the user chooses to finish processing data by closing each file separately.

Files are processed using the file handle retrieved during a call to FileOpen(). Once the file handle is obtained it can be used in subsequent read, write and close operations.

How to use the FileManager:

 String str = "Hello World!";
 long lRet = FileManager.FILE_OK;
 
 FileManager mngr = FileManager.getInstance();
 long handle = mngr.FileOpen("/user/mydir/myfile.txt", FileManager.IOFLAG_NEW);
 lRet = mngr.FileWrite(handle, str, str.length());
 if (lRet != FileManager.FILE_OK)
 	error("Error [" + lRet + "] occurred while writing to file"); 
 
 ObjectRef rBuffer = new ObjectRef("");
 long len = str.length();
 lRet = mngr.FileRead(handle, rBuffer, len);
 if (lRet == FileManager.FILE_OK)
 	diag("rBuffer = " + rBuffer.toString());
 lRet = mngr.FileClose(handle); 
 

Since:
AMXTools 1.0.0
Version:
1.0.0

Field Summary
static int FILE_ALREADY_CLOSE
           
static int FILE_BUFFER_TOO_SMALL
           
static int FILE_DIRECTORY_EXISTS
           
static int FILE_DIRECTORY_NOT_LOADED
           
static int FILE_DISK_ERROR
           
static int FILE_DISK_FULL
           
static int FILE_END_OF_FILE
           
static int FILE_INVALID_DIRECTORY
           
static int FILE_INVALID_FILENAME
           
static int FILE_INVALID_HANDLE
           
static int FILE_INVALID_IOFLAG
           
static int FILE_INVALID_PARAMETER
           
static int FILE_NAME_EXISTS
           
static int FILE_OK
           
static int IOFLAG_APPEND
           
static int IOFLAG_NEW
           
static int IOFLAG_READ
           
 
Method Summary
 long FileClose(long lFileHandle)
          Closes a file opened with FileOpen().
 long FileOpen(java.lang.String sFilePath, long lIOFlag)
          Opens a file for reading or writing.
 long FileRead(long lFileHandle, ObjectRef rStrBuffer, long lBufLen)
          Reads a block of data from the specified file.
 long FileReadLine(long lFileHandle, ObjectRef rStrBuffer, long lBufLen)
          Reads a line of data from the specified file.
 long FileSeek(long lFileHandle, long lPos)
          Sets the file pointer to the specified position.
 long FileSize(long lFileHandle)
          Retrieves the size of a file on disk.
 long FileWrite(long lFileHandle, java.lang.String sBuffer, long lBufLen)
          Writes a block of data to the specified file.
 long FileWriteLine(long lFileHandle, java.lang.String sBuffer, long lLineLen)
          Writes a line of data to the specified file.
static FileManager getInstance()
          Get a single instance of this class
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FILE_OK

public static final int FILE_OK
See Also:
Constant Field Values

FILE_INVALID_HANDLE

public static final int FILE_INVALID_HANDLE
See Also:
Constant Field Values

FILE_INVALID_FILENAME

public static final int FILE_INVALID_FILENAME
See Also:
Constant Field Values

FILE_INVALID_IOFLAG

public static final int FILE_INVALID_IOFLAG
See Also:
Constant Field Values

FILE_INVALID_DIRECTORY

public static final int FILE_INVALID_DIRECTORY
See Also:
Constant Field Values

FILE_DISK_ERROR

public static final int FILE_DISK_ERROR
See Also:
Constant Field Values

FILE_INVALID_PARAMETER

public static final int FILE_INVALID_PARAMETER
See Also:
Constant Field Values

FILE_ALREADY_CLOSE

public static final int FILE_ALREADY_CLOSE
See Also:
Constant Field Values

FILE_NAME_EXISTS

public static final int FILE_NAME_EXISTS
See Also:
Constant Field Values

FILE_END_OF_FILE

public static final int FILE_END_OF_FILE
See Also:
Constant Field Values

FILE_BUFFER_TOO_SMALL

public static final int FILE_BUFFER_TOO_SMALL
See Also:
Constant Field Values

FILE_DISK_FULL

public static final int FILE_DISK_FULL
See Also:
Constant Field Values

FILE_DIRECTORY_NOT_LOADED

public static final int FILE_DIRECTORY_NOT_LOADED
See Also:
Constant Field Values

FILE_DIRECTORY_EXISTS

public static final int FILE_DIRECTORY_EXISTS
See Also:
Constant Field Values

IOFLAG_READ

public static final int IOFLAG_READ
See Also:
Constant Field Values

IOFLAG_NEW

public static final int IOFLAG_NEW
See Also:
Constant Field Values

IOFLAG_APPEND

public static final int IOFLAG_APPEND
See Also:
Constant Field Values
Method Detail

getInstance

public static FileManager getInstance()
Get a single instance of this class

Returns:
a static instance of the FileManager class

FileOpen

public long FileOpen(java.lang.String sFilePath,
                     long lIOFlag)
Opens a file for reading or writing.

If the file is opened successfully, it must be closed (after all reading or writing is completed) by calling FileClose(). If files are not closed, subsequent file open operations may fail due to the limited number of file handles available.

Parameters:
sFilePath - String containing the path to the file to be opened.
lIOFlag -
  • 1 = Read: The file is opened with READONLY status.
  • 2 = R/W New: The file is opened with READWRITE status. If the file currently exists, its contents are erased.
  • 3 = R/W Append: The file is opened with READWRITE status. The current contents of the file are preserved and the file pointer is set to point to the end of the file.
Returns:
If the open operation is successful, this function returns a non-zero integer value representing the handle to the file. This handle must be used in subsequent read, write and close operations.
  • 0 = handle to file (open was successful)
  • -2 = invalid file path or name
  • -5 = disk I/O error
  • -3 = invalid value supplied for IOFlag

FileClose

public long FileClose(long lFileHandle)
Closes a file opened with FileOpen(). This function should be called when all reading or writing to the file is completed.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
Returns:
  • 0 = operation was successful
  • -1 = invalid file handle
  • -7 = file already closed
  • -5 = disk I/O error

FileRead

public long FileRead(long lFileHandle,
                     ObjectRef rStrBuffer,
                     long lBufLen)
Reads a block of data from the specified file. This function reads (from the current location of the file pointer) the number of bytes specified by lBufLen or fewer bytes if the end of file is reached. The bytes are read from the file identified by lFileHandle and are stored in rStrBuffer. The file pointer will automatically be advanced the correct number of bytes so the next read operation continues where the last operation left off.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
rStrBuffer - Must be of type String. Buffer to hold the data to be read.

Create rStrBuffer with a valueOf(String) Example:
ObjectRef rStrBuffer = new ObjectRef("") or rStrBuffer.valueOf("")

lBufLen - maximum number of bytes to read.
Returns:
  • 0 = the number of bytes actually read
  • -1 = invalid file handle
  • -9 = end-of-file reached
  • -5 = disk I/O error
  • -6 = invalid parameter

FileReadLine

public long FileReadLine(long lFileHandle,
                         ObjectRef rStrBuffer,
                         long lBufLen)
Reads a line of data from the specified file.

This function reads from the current location of the file pointer up to the next carriage return or to the end-of-file (EOF), whichever comes first. A complete line will not be read if the buffer length is exceeded before a carriage return (or EOF) is encountered. The bytes are read from the file identified by lFileHandle and are stored in rStrBuffer. The or pair will not be stored in rStrBuffer. If a complete line is read, the file pointer is advanced to the next character in the file after the or pair or to the EOF if the last line was read.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
rStrBuffer - Must be of type String. Buffer to hold the data to be read.

Create rStrBuffer with a valueOf(String) Example:
ObjectRef rStrBuffer = new ObjectRef("") or rStrBuffer.valueOf("")

lBufLen - maximum number of bytes to read.
Returns:
  • 0 = the number of bytes actually read
  • -1 = invalid file handle
  • -9 = EOF (end-of-file) reached
  • -5 = disk I/O error
  • -6 = invalid parameter (buffer length must be greater than zero)

FileSeek

public long FileSeek(long lFileHandle,
                     long lPos)
Sets the file pointer to the specified position.

After FileSeek() is successfully called, subsequent read or write operations begin at the byte number specified by lPos.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
lPos - The byte position to set the file pointer (0 = beginning of file, -1 = end of file)
Returns:
  • 0 = Operation was successful and the result is the current file pointer value
  • -1 = invalid file handle
  • -6 = Invalid parameter (pos points beyond the end-of-file (position is set to the end-of-file))
  • -5 = disk I/O error

FileWrite

public long FileWrite(long lFileHandle,
                      java.lang.String sBuffer,
                      long lBufLen)
Writes a block of data to the specified file.

The data will overwrite or append to the current contents of the file depending on the current position of the file pointer.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
sBuffer - buffer containing the data to write.
lBufLen - number of bytes to write.
Returns:
  • 0 = the number of bytes actually written
  • -1 = invalid file handle
  • -11 = disk full
  • -5 = disk I/O error
  • -6 = invalid parameter (buffer length must be greater than zero)

FileWriteLine

public long FileWriteLine(long lFileHandle,
                          java.lang.String sBuffer,
                          long lLineLen)
Writes a line of data to the specified file.

A character string is automatically appended to the end of the line.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
sBuffer - buffer containing the data to write.
lLineLen - number of bytes to write.
Returns:
  • 0 = the number of bytes actually written
  • -1 = invalid file handle
  • -11 = disk full
  • -5 = disk I/O error
  • -6 = invalid parameter (LineLen must be greater than zero)

FileSize

public long FileSize(long lFileHandle)
Retrieves the size of a file on disk.

Parameters:
lFileHandle - handle to the file returned by FileOpen().
Returns:
the length of data contained in the file or:
  • 0 = Operation was successful and the file contains no data.
  • -1 = invalid file handle


Copyright © 2008 AMX LLC. All Rights Reserved.