FileMessageFactory (Apache Tomcat 9.0.120 API Documentation)
Description: declaration: package: org.apache.catalina.ha.deploy, class: FileMessageFactory

# Class FileMessageFactory

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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected boolean`
  `closed`
  Once the factory is used, it cannot be reused.
  `protected long`
  `creationTime`
  Deprecated.
  Unused.
  `protected byte[]`
  `data`
  The bytes that we hold the data in, not thread safe.
  `protected final 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 long`
  `lastModified`
  The time this instance was last modified.
  `protected int`
  `maxValidTime`
  The maximum time (in seconds) this instance will be allowed to exist from lastModifiedTime.
  `protected final 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 final 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 final 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

  Modifier and Type
  Method
  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()`
  main
  `static FileMessageFactory`
  `getInstance(File f, boolean openForWrite)`
  Creates a factory to read or write from a file.
  `int`
  `getMaxValidTime()`
  Returns the maximum time in seconds that this factory instance is allowed to exist from last modification.
  `boolean`
  `isValid()`
  Checks if this factory instance is still valid based on the maximum valid time.
  `static void`
  `main(String[] args)`
  Deprecated.
  This method will be removed in Tomcat 10.0.x
  `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)`
  Sets the maximum time in seconds that this factory instance is allowed to exist from last modification.
  `boolean`
  `writeMessage(FileMessage msg)`
  Writes a message to file.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### READ_SIZE

    public static final int READ_SIZE
    The number of bytes that we read from file
    See Also:
      - Constant Field Values

  - ### file

    protected final File file
    The file that we are reading/writing

  - ### openForWrite

    protected final 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 final 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

    @Deprecated protected long creationTime
    Deprecated.
    Unused. This will be removed in Tomcat 11.
    The time this instance was created. (in milliseconds)

  - ### lastModified

    protected long lastModified
    The time this instance was last modified.

  - ### maxValidTime

    protected int maxValidTime
    The maximum time (in seconds) this instance will be allowed to exist from lastModifiedTime.

- ## Method Details

  - ### 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

    @Deprecated public static void main(String[] args) throws Exception
    Deprecated.
    This method will be removed in Tomcat 10.0.x
    Example usage.
    Parameters:
      `args` - String[], args[0] - read from filename, args[1] write to filename
    Throws:
      `Exception` - An error occurred

  - ### getFile

    public File getFile()
    main

  - ### isValid

    public boolean isValid()
    Checks if this factory instance is still valid based on the maximum valid time. If the instance has been idle longer than maxValidTime, it will be cleaned up.
    Returns:
      True if the factory is still valid, false if it has expired

  - ### getMaxValidTime

    public int getMaxValidTime()
    Returns the maximum time in seconds that this factory instance is allowed to exist from last modification.
    Returns:
      The maximum valid time in seconds

  - ### setMaxValidTime

    public void setMaxValidTime(int maxValidTime)
    Sets the maximum time in seconds that this factory instance is allowed to exist from last modification.
    Parameters:
      `maxValidTime` - The maximum valid time in seconds