FileMessageFactory (Apache Tomcat 7.0.109 API Documentation)

java.lang.Object
- org.apache.catalina.ha.deploy.FileMessageFactory

```
public class FileMessageFactory
extends Object
```
This factory is used to read files and write files by splitting them up into smaller messages. So that entire files don't have to be read into memory.
The factory can be used as a reader or writer but not both at the same time. When done reading or writing the factory will close the input or output streams and mark the factory as closed. It is not possible to use it after that.
To force a cleanup, call cleanup() from the calling object.
This class is not thread safe.

Version:

1.0

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`closed` Once the factory is used, it cannot be reused.
`protected long`	`creationTime` The time this instance was created.
`protected byte[]`	`data` The bytes that we hold the data in, not thread safe.
`protected File`	`file` The file that we are reading/writing
`protected FileInputStream`	`in` When openForWrite=false, the input stream is held by this variable
`protected boolean`	`isWriting` Flag that indicates if a thread is writing messages to disk.
`protected AtomicLong`	`lastMessageProcessed` The number of the last message processed.
`protected int`	`maxValidTime` The maximum valid time(in seconds) from creationTime.
`protected Map<Long,FileMessage>`	`msgBuffer` Messages received out of order are held in the buffer until required.
`protected int`	`nrOfMessagesProcessed` The number of messages we have written
`protected boolean`	`openForWrite` True means that we are writing with this factory.
`protected FileOutputStream`	`out` When openForWrite=true, the output stream is held by this variable
`static int`	`READ_SIZE` The number of bytes that we read from file
`protected long`	`size` The total size of the file
`protected long`	`totalNrOfMessages` The total number of packets that we split this file into

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`checkState(boolean openForWrite)` Check to make sure the factory is able to perform the function it is asked to do.
`void`	`cleanup()` Closes the factory, its streams and sets all its references to null
`File`	`getFile()`
`static FileMessageFactory`	`getInstance(File f, boolean openForWrite)` Creates a factory to read or write from a file.
`int`	`getMaxValidTime()`
`boolean`	`isValid()`
`static void`	`main(String[] args)` Example usage.
`FileMessage`	`readMessage(FileMessage f)` Reads file data into the file message and sets the size, totalLength, totalNrOfMsgs and the message number If EOF is reached, the factory returns null, and closes itself, otherwise the same message is returned as was passed in.
`void`	`setMaxValidTime(int maxValidTime)`
`boolean`	`writeMessage(FileMessage msg)` Writes a message to file.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - READ_SIZE
```
public static final int READ_SIZE
```
    The number of bytes that we read from file
    
    See Also:
    Constant Field Values
  - file
```
protected File file
```
    The file that we are reading/writing
  - openForWrite
```
protected boolean openForWrite
```
    True means that we are writing with this factory. False means that we are reading with this factory
  - closed
```
protected boolean closed
```
    Once the factory is used, it cannot be reused.
  - in
```
protected FileInputStream in
```
    When openForWrite=false, the input stream is held by this variable
  - out
```
protected FileOutputStream out
```
    When openForWrite=true, the output stream is held by this variable
  - nrOfMessagesProcessed
```
protected int nrOfMessagesProcessed
```
    The number of messages we have written
  - size
```
protected long size
```
    The total size of the file
  - totalNrOfMessages
```
protected long totalNrOfMessages
```
    The total number of packets that we split this file into
  - lastMessageProcessed
```
protected AtomicLong lastMessageProcessed
```
    The number of the last message processed. Message IDs are 1 based.
  - msgBuffer
```
protected Map<Long,FileMessage> msgBuffer
```
    Messages received out of order are held in the buffer until required. If everything is worked as expected, messages will spend very little time in the buffer.
  - data
```
protected byte[] data
```
    The bytes that we hold the data in, not thread safe.
  - isWriting
```
protected boolean isWriting
```
    Flag that indicates if a thread is writing messages to disk. Access to this flag must be synchronised.
  - creationTime
```
protected long creationTime
```
    The time this instance was created. (in milliseconds)
  - maxValidTime
```
protected int maxValidTime
```
    The maximum valid time(in seconds) from creationTime.
- Method Detail
  - getInstance
```
public static FileMessageFactory getInstance(File f,
                             boolean openForWrite)
                                      throws FileNotFoundException,
                                             IOException
```
    Creates a factory to read or write from a file. When opening for read, the readMessage can be invoked, and when opening for write the writeMessage can be invoked.
    
    Parameters:
    f - File - the file to be read or written
    openForWrite - boolean - true, means we are writing to the file, false means we are reading from it
    
    Returns:
    FileMessageFactory
    
    Throws:
    
    FileNotFoundException - - if the file to be read doesn't exist
    
    IOException - - if it fails to create the file that is to be written
  - readMessage
```
public FileMessage readMessage(FileMessage f)
                        throws IllegalArgumentException,
                               IOException
```
    Reads file data into the file message and sets the size, totalLength, totalNrOfMsgs and the message number
    If EOF is reached, the factory returns null, and closes itself, otherwise the same message is returned as was passed in. This makes sure that not more memory is ever used. To remember, neither the file message or the factory are thread safe. Don't hand off the message to one thread and read the same with another.
    
    Parameters:
    f - FileMessage - the message to be populated with file data
    
    Returns:
    FileMessage - returns the same message passed in as a parameter, or null if EOF
    
    Throws:
    
    IllegalArgumentException - - if the factory is for writing or is closed
    
    IOException - - if a file read exception occurs
  - writeMessage
```
public boolean writeMessage(FileMessage msg)
                     throws IllegalArgumentException,
                            IOException
```
    Writes a message to file. If (msg.getMessageNumber() == msg.getTotalNrOfMsgs()) the output stream will be closed after writing.
    
    Parameters:
    msg - FileMessage - message containing data to be written
    
    Returns:
    returns true if the file is complete and outputstream is closed, false otherwise.
    
    Throws:
    
    IllegalArgumentException - - if the factory is opened for read or closed
    
    IOException - - if a file write error occurs
  - cleanup
```
public void cleanup()
```
    Closes the factory, its streams and sets all its references to null
  - checkState
```
protected void checkState(boolean openForWrite)
                   throws IllegalArgumentException
```
    Check to make sure the factory is able to perform the function it is asked to do. Invoked by readMessage/writeMessage before those methods proceed.
    
    Parameters:
    openForWrite - The value to check
    
    Throws:
    
    IllegalArgumentException - if the state is not the expected one
  - main
```
public static void main(String[] args)
                 throws Exception
```
    Example usage.
    
    Parameters:
    args - String[], args[0] - read from filename, args[1] write to filename
    
    Throws:
    
    Exception - An error occurred
  - getFile
```
public File getFile()
```
  - isValid
```
public boolean isValid()
```
  - getMaxValidTime
```
public int getMaxValidTime()
```
  - setMaxValidTime
```
public void setMaxValidTime(int maxValidTime)
```

Class FileMessageFactory

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

READ_SIZE

file

openForWrite

closed

in

out

nrOfMessagesProcessed

size

totalNrOfMessages

lastMessageProcessed

msgBuffer

data

isWriting

creationTime

maxValidTime

Method Detail

getInstance

readMessage

writeMessage

cleanup

checkState

main

getFile

isValid

getMaxValidTime

setMaxValidTime