net.fortuna.mstor.data
Class MboxFile

java.lang.Object
  net.fortuna.mstor.data.MboxFile

public class MboxFile
extends java.lang.Object

Provides access to an mbox-formatted file. To read an mbox file using a non-standard file encoding you may specify the following system property:

        -Dmstor.mbox.encoding=<some_encoding>
 

If no encoding system property is specified the default file encoding will be used.

Author:

Ben Fortuna

 $Id$

 Created: [6/07/2004]

 Contributors: Paul Legato - fix for purge() method,
  Michael G. Kaiser - add/strip of ">" characters from message content
  matching "From_" pattern (appendMessage()/getMessage())
  

Nested Class Summary

static class

MboxFile.BufferStrategy Strategy for I/O buffers.

Field Summary

static java.lang.String	FROM__PREFIX The prefix for all "From_" lines in an mbox file.
static java.lang.String	KEY_BUFFER_STRATEGY A capability hint to indicate the preferred strategy for reading mbox files into a buffer.
static java.lang.String	READ_ONLY Indicates a file should be opened for reading only.
static java.lang.String	READ_WRITE Indicates a file should be opened for reading and writing.

Constructor Summary

MboxFile(java.io.File file)

MboxFile(java.io.File file, java.lang.String mode)

Method Summary

void	appendMessage(byte[] message) Appends the specified message (represented by a CharSequence) to the mbox file.
void	close() Close the mbox file and release any system resources.
byte[]	getMessage(int index) Convenience method that returns a message as a byte array containing the data for the message at the specified index.
java.io.InputStream	getMessageAsStream(int index) Opens an input stream to the specified message data.
int	getMessageCount() Returns the total number of messages in the mbox file.
static boolean	isValid(java.io.File file) Indicates whether the specified file appears to be a valid mbox file.
void	purge(int[] msgnums) Purge the specified messages from the file.

Methods inherited from class java.lang.Object

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

Field Detail

KEY_BUFFER_STRATEGY

public static final java.lang.String KEY_BUFFER_STRATEGY

A capability hint to indicate the preferred strategy for reading mbox files into a buffer.

See Also:

Constant Field Values

READ_ONLY

public static final java.lang.String READ_ONLY

Indicates a file should be opened for reading only.

See Also:

Constant Field Values

READ_WRITE

public static final java.lang.String READ_WRITE

Indicates a file should be opened for reading and writing.

See Also:

Constant Field Values

FROM__PREFIX

public static final java.lang.String FROM__PREFIX

The prefix for all "From_" lines in an mbox file.

See Also:

Constant Field Values

Constructor Detail

MboxFile

public MboxFile(java.io.File file)
         throws java.io.FileNotFoundException

Parameters:

file - a reference to an mbox data file

Throws:

java.io.FileNotFoundException - where the specified file doesn't exist

MboxFile

public MboxFile(java.io.File file,
                java.lang.String mode)

Parameters:

file - a reference to an mbox data file

mode - the mode used to open the file

Method Detail

getMessageCount

public final int getMessageCount()
                          throws java.io.IOException

Returns the total number of messages in the mbox file.

Returns:

an int

Throws:

java.io.IOException - where an error occurs reading messages

getMessageAsStream

public final java.io.InputStream getMessageAsStream(int index)
                                             throws java.io.IOException

Opens an input stream to the specified message data.

Parameters:

index - the index of the message to open a stream to

Returns:

an input stream

Throws:

java.io.IOException - where an error occurs reading the message

getMessage

public final byte[] getMessage(int index)
                        throws java.io.IOException

Convenience method that returns a message as a byte array containing the data for the message at the specified index.

Parameters:

index - the index of the message to retrieve

Returns:

a byte array

Throws:

java.io.IOException - where an error occurs reading the message

appendMessage

public final void appendMessage(byte[] message)
                         throws java.io.IOException

Appends the specified message (represented by a CharSequence) to the mbox file.

Parameters:

message -

Throws:

java.io.IOException - where an error occurs writing the message data

purge

public final void purge(int[] msgnums)
                 throws java.io.IOException

Purge the specified messages from the file.

Parameters:

msgnums - the indices of the messages to purge

Throws:

java.io.IOException - where an error occurs updating the data file

close

public final void close()
                 throws java.io.IOException

Close the mbox file and release any system resources.

Throws:

java.io.IOException - where an error occurs closing the data file

isValid

public static boolean isValid(java.io.File file)

Indicates whether the specified file appears to be a valid mbox file. Note that this method does not check the entire file for validity, but rather checks the first line for indication that this is an mbox file.

Parameters:

file - an mbox file reference

Returns:

true if the specified file is a valid mbox file