org.apache.james.mime4j.stream
Class MimeTokenStream

java.lang.Object
  extended by org.apache.james.mime4j.stream.MimeTokenStream

public class MimeTokenStream
extends java.lang.Object

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

Typical usage:

      MimeTokenStream stream = new MimeTokenStream();
      InputStream instream = new FileInputStream("mime.msg");
      try {
          stream.parse(instream);
          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());
              ...
              }
          }
      } finally {
          instream.close();
      }
 

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.


Constructor Summary
MimeTokenStream()
          Constructs a standard (lax) stream.
MimeTokenStream(MimeConfig config)
           
MimeTokenStream(MimeConfig config, BodyDescriptorBuilder bodyDescBuilder)
           
MimeTokenStream(MimeConfig config, DecodeMonitor monitor, BodyDescriptorBuilder bodyDescBuilder)
           
MimeTokenStream(MimeConfig config, DecodeMonitor monitor, FieldBuilder fieldBuilder, BodyDescriptorBuilder bodyDescBuilder)
           
 
Method Summary
 BodyDescriptor getBodyDescriptor()
          Gets a descriptor for the current entity.
 MimeConfig getConfig()
           
 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 EntityState.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.
 RecursionMode getRecursionMode()
          Gets the current recursion mode.
 EntityState getState()
          Returns the current state.
 boolean isRaw()
          Determines if this parser is currently in raw mode.
 EntityState 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.
 Field parseHeadless(java.io.InputStream stream, java.lang.String contentType)
          Instructs the MimeTokenStream to parse the given content with the content type.
 void setRecursionMode(RecursionMode mode)
          Sets the current recursion.
static java.lang.String stateToString(EntityState 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 MimeConfig.setStrictParsing(boolean) to turn on strict parsing mode and pass the config object to MimeTokenStream(MimeConfig) to create a stream that strictly validates the input.


MimeTokenStream

public MimeTokenStream(MimeConfig config)

MimeTokenStream

public MimeTokenStream(MimeConfig config,
                       BodyDescriptorBuilder bodyDescBuilder)

MimeTokenStream

public MimeTokenStream(MimeConfig config,
                       DecodeMonitor monitor,
                       BodyDescriptorBuilder bodyDescBuilder)

MimeTokenStream

public MimeTokenStream(MimeConfig config,
                       DecodeMonitor monitor,
                       FieldBuilder fieldBuilder,
                       BodyDescriptorBuilder bodyDescBuilder)
Method Detail

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 Field 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.

Returns:
a parsed Field representing the input contentType

isRaw

public boolean isRaw()
Determines if this parser is currently in raw mode.

Returns:
true if in raw mode, false otherwise.
See Also:
setRecursionMode(RecursionMode)

getRecursionMode

public RecursionMode 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 encountered; RecursionMode.M_NO_RECURSE does not.

Returns:
RecursionMode.M_RECURSE, RecursionMode.M_RAW or RecursionMode.M_NO_RECURSE

setRecursionMode

public void setRecursionMode(RecursionMode 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 encountered; 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 trigger 'end' events to match previously triggered 'start' events.


getState

public EntityState 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 EntityState.T_RAW_ENTITY, EntityState.T_PREAMBLE, or EntityState.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 EntityState.T_RAW_ENTITY, EntityState.T_PREAMBLE, or EntityState.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
UnsupportedCharsetException - if there is no JVM support for decoding the 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:

Returns:
BodyDescriptor, not nulls

getField

public Field getField()
This method is valid, if getState() returns EntityState.T_FIELD.

Returns:
String with the fields raw contents.
Throws:
java.lang.IllegalStateException - getState() returns another value than EntityState.T_FIELD.

next

public EntityState 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 EntityState.T_END_OF_STREAM.
java.io.IOException
MimeException

stateToString

public static final java.lang.String stateToString(EntityState state)
Renders a state as a string suitable for logging.

Parameters:
state -
Returns:
rendered as string, not null

getConfig

public MimeConfig getConfig()


Copyright © 2004-2012 The Apache Software Foundation. All Rights Reserved.