org.apache.james.mime4j.parser
Class MimeTokenStream

java.lang.Object
  org.apache.james.mime4j.parser.MimeTokenStream

All Implemented Interfaces:

EntityStates, RecursionMode

public class MimeTokenStream
extends java.lang.Object
implements EntityStates, RecursionMode

Parses MIME (or RFC822) message streams of bytes or characters. The stream is converted into an event stream.

Typical usage:

      MimeTokenStream stream = new MimeTokenStream();
      stream.parse(new FileInputStream("mime.msg"));
      for (int state = stream.getState();
           state != MimeTokenStream.T_END_OF_STREAM;
           state = stream.next()) {
          switch (state) {
            case MimeTokenStream.T_BODY:
              System.out.println("Body detected, contents = "
                + stream.getInputStream() + ", header data = "
                + stream.getBodyDescriptor());
              break;
            case MimeTokenStream.T_FIELD:
              System.out.println("Header field detected: "
                + stream.getField());
              break;
            case MimeTokenStream.T_START_MULTIPART:
              System.out.println("Multipart message detexted,"
                + " header data = "
                + stream.getBodyDescriptor());
            ...
          }
      }
 

Instances of MimeTokenStream are reusable: Invoking the method parse(InputStream) resets the token streams internal state. However, they are definitely not thread safe. If you have a multi threaded application, then the suggested use is to have one instance per thread.

Field Summary

Fields inherited from interface org.apache.james.mime4j.parser.EntityStates

T_BODY, T_END_BODYPART, T_END_HEADER, T_END_MESSAGE, T_END_MULTIPART, T_END_OF_STREAM, T_EPILOGUE, T_FIELD, T_PREAMBLE, T_RAW_ENTITY, T_START_BODYPART, T_START_HEADER, T_START_MESSAGE, T_START_MULTIPART

Fields inherited from interface org.apache.james.mime4j.parser.RecursionMode

M_FLAT, M_NO_RECURSE, M_RAW, M_RECURSE

Constructor Summary

	MimeTokenStream() Constructs a standard (lax) stream.
protected	MimeTokenStream(MimeEntityConfig config)

Method Summary

static MimeTokenStream	createMaximalDescriptorStream() Creates a stream that creates a more detailed body descriptor.
static MimeTokenStream	createStrictValidationStream() Creates a stream that strictly validates the input.
BodyDescriptor	getBodyDescriptor() Gets a descriptor for the current entity.
java.io.InputStream	getDecodedInputStream() This method returns a transfer decoded stream based on the MIME fields with the standard defaults.
Field	getField() This method is valid, if getState() returns EntityStates.T_FIELD.
java.io.InputStream	getInputStream() This method returns the raw entity, preamble, or epilogue contents.
java.io.Reader	getReader() Gets a reader configured for the current body or body part.
int	getRecursionMode() Gets the current recursion mode.
int	getState() Returns the current state.
boolean	isRaw() Determines if this parser is currently in raw mode.
int	next() This method advances the token stream to the next token.
void	parse(java.io.InputStream stream) Instructs the MimeTokenStream to parse the given streams contents.
void	parseHeadless(java.io.InputStream stream, java.lang.String contentType) Instructs the MimeTokenStream to parse the given content with the content type.
void	setRecursionMode(int mode) Sets the current recursion.
static java.lang.String	stateToString(int state) Renders a state as a string suitable for logging.
void	stop() Finishes the parsing and stops reading lines.

Methods inherited from class java.lang.Object

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

Constructor Detail

MimeTokenStream

public MimeTokenStream()

Constructs a standard (lax) stream. Optional validation events will be logged only. Use createStrictValidationStream() to create a stream that strictly validates the input.

MimeTokenStream

protected MimeTokenStream(MimeEntityConfig config)

Method Detail

createMaximalDescriptorStream

public static final MimeTokenStream createMaximalDescriptorStream()

Creates a stream that creates a more detailed body descriptor.

Returns:

MimeTokenStream, not null

createStrictValidationStream

public static final MimeTokenStream createStrictValidationStream()

Creates a stream that strictly validates the input.

Returns:

MimeTokenStream which throws a MimeException whenever possible issues are dedicated in the input

parse

public void parse(java.io.InputStream stream)

Instructs the MimeTokenStream to parse the given streams contents. If the MimeTokenStream has already been in use, resets the streams internal state.

parseHeadless

public void parseHeadless(java.io.InputStream stream,
                          java.lang.String contentType)

Instructs the MimeTokenStream to parse the given content with the content type. The message stream is assumed to have no message header and is expected to begin with a message body. This can be the case when the message content is transmitted using a different transport protocol such as HTTP.

If the MimeTokenStream has already been in use, resets the streams internal state.

isRaw

public boolean isRaw()

Determines if this parser is currently in raw mode.

Returns:

true if in raw mode, false otherwise.

See Also:

setRecursionMode(int)

getRecursionMode

public int getRecursionMode()

Gets the current recursion mode. The recursion mode specifies the approach taken to parsing parts. RecursionMode.M_RAW mode does not parse the part at all. RecursionMode.M_RECURSE mode recursively parses each mail when an message/rfc822 part is encounted; RecursionMode.M_NO_RECURSE does not.

Returns:

RecursionMode.M_RECURSE, RecursionMode.M_RAW or RecursionMode.M_NO_RECURSE

setRecursionMode

public void setRecursionMode(int mode)

Sets the current recursion. The recursion mode specifies the approach taken to parsing parts. RecursionMode.M_RAW mode does not parse the part at all. RecursionMode.M_RECURSE mode recursively parses each mail when an message/rfc822 part is encounted; RecursionMode.M_NO_RECURSE does not.

Parameters:

mode - RecursionMode.M_RECURSE, RecursionMode.M_RAW or RecursionMode.M_NO_RECURSE

stop

public void stop()

Finishes the parsing and stops reading lines. NOTE: No more lines will be parsed but the parser will still call ContentHandler.endMultipart(), ContentHandler.endBodyPart(), ContentHandler.endMessage(), etc to match previous calls to ContentHandler.startMultipart(BodyDescriptor), ContentHandler.startBodyPart(), ContentHandler.startMessage(), etc.

getState

public int getState()

Returns the current state.

getInputStream

public java.io.InputStream getInputStream()

This method returns the raw entity, preamble, or epilogue contents.

This method is valid, if getState() returns either of EntityStates.T_RAW_ENTITY, EntityStates.T_PREAMBLE, or EntityStates.T_EPILOGUE.

Returns:

Data stream, depending on the current state.

Throws:

java.lang.IllegalStateException - getState() returns an invalid value.

getDecodedInputStream

public java.io.InputStream getDecodedInputStream()

This method returns a transfer decoded stream based on the MIME fields with the standard defaults.

This method is valid, if getState() returns either of EntityStates.T_RAW_ENTITY, EntityStates.T_PREAMBLE, or EntityStates.T_EPILOGUE.

Returns:

Data stream, depending on the current state.

Throws:

java.lang.IllegalStateException - getState() returns an invalid value.

getReader

public java.io.Reader getReader()

Gets a reader configured for the current body or body part. The reader will return a transfer and charset decoded stream of characters based on the MIME fields with the standard defaults. This is a conveniance method and relies on getInputStream(). Consult the javadoc for that method for known limitations.

Returns:

Reader, not null

Throws:

java.lang.IllegalStateException - getState() returns an invalid value

java.nio.charset.UnsupportedCharsetException - if there is no JVM support for decoding the charset

java.nio.charset.IllegalCharsetNameException - if the charset name specified in the mime type is illegal

See Also:

getInputStream()

getBodyDescriptor

public BodyDescriptor getBodyDescriptor()

Gets a descriptor for the current entity. This method is valid if getState() returns:

• EntityStates.T_BODY
• EntityStates.T_START_MULTIPART
• EntityStates.T_EPILOGUE
• EntityStates.T_PREAMBLE

Returns:

BodyDescriptor, not nulls

getField

public Field getField()

This method is valid, if getState() returns EntityStates.T_FIELD.

Returns:

String with the fields raw contents.

Throws:

java.lang.IllegalStateException - getState() returns another value than EntityStates.T_FIELD.

next

public int next()
         throws java.io.IOException,
                MimeException

This method advances the token stream to the next token.

Throws:

java.lang.IllegalStateException - The method has been called, although getState() was already EntityStates.T_END_OF_STREAM.

java.io.IOException

MimeException

stateToString

public static final java.lang.String stateToString(int state)

Renders a state as a string suitable for logging.

Parameters:

state -

Returns:

rendered as string, not null