001 /****************************************************************
002 * Licensed to the Apache Software Foundation (ASF) under one *
003 * or more contributor license agreements. See the NOTICE file *
004 * distributed with this work for additional information *
005 * regarding copyright ownership. The ASF licenses this file *
006 * to you under the Apache License, Version 2.0 (the *
007 * "License"); you may not use this file except in compliance *
008 * with the License. You may obtain a copy of the License at *
009 * *
010 * http://www.apache.org/licenses/LICENSE-2.0 *
011 * *
012 * Unless required by applicable law or agreed to in writing, *
013 * software distributed under the License is distributed on an *
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015 * KIND, either express or implied. See the License for the *
016 * specific language governing permissions and limitations *
017 * under the License. *
018 ****************************************************************/
019
020 package org.apache.james.mime4j.stream;
021
022 import org.apache.james.mime4j.MimeException;
023
024 import java.io.IOException;
025 import java.io.InputStream;
026
027 /**
028 * Represents the interal state of a MIME entity, which is being retrieved
029 * from an input stream by a MIME parser.
030 */
031 public interface EntityStateMachine {
032
033 /**
034 * Return the current state of the entity.
035 *
036 * @see EntityState
037 *
038 * @return current state
039 */
040 EntityState getState();
041
042 /**
043 * Sets the current recursion mode.
044 * The recursion mode specifies the approach taken to parsing parts.
045 * {@link RecursionMode#M_RAW} mode does not parse the part at all.
046 * {@link RecursionMode#M_RECURSE} mode recursively parses each mail
047 * when an <code>message/rfc822</code> part is encounted;
048 * {@link RecursionMode#M_NO_RECURSE} does not.
049 *
050 * @see RecursionMode
051 *
052 * @param recursionMode
053 */
054 void setRecursionMode(RecursionMode recursionMode);
055
056 /**
057 * Advances the state machine to the next state in the
058 * process of the MIME stream parsing. This method
059 * may return an new state machine that represents an embedded
060 * entity, which must be parsed before the parsing process of
061 * the current entity can proceed.
062 *
063 * @return a state machine of an embedded entity, if encountered,
064 * <code>null</code> otherwise.
065 *
066 * @throws IOException if an I/O error occurs.
067 * @throws MimeException if the message can not be processed due
068 * to the MIME specification violation.
069 */
070 EntityStateMachine advance() throws IOException, MimeException;
071
072 /**
073 * Returns description of the entity body.
074 *
075 * @return body description
076 *
077 * @throws IllegalStateException if the body description cannot be
078 * obtained at the current stage of the parsing process.
079 */
080 BodyDescriptor getBodyDescriptor() throws IllegalStateException;
081
082 /**
083 * Returns content stream of the entity body.
084 *
085 * @return input stream
086 *
087 * @throws IllegalStateException if the content stream cannot be
088 * obtained at the current stage of the parsing process.
089 */
090 InputStream getContentStream() throws IllegalStateException;
091
092 /**
093 * Returns the decoded content stream of the entity body.
094 *
095 * @return input stream
096 *
097 * @throws IllegalStateException if the content stream cannot be
098 * obtained at the current stage of the parsing process.
099 */
100 InputStream getDecodedContentStream() throws IllegalStateException;
101
102 /**
103 * Returns current header field.
104 *
105 * @return header field
106 *
107 * @throws IllegalStateException if a header field cannot be
108 * obtained at the current stage of the parsing process.
109 */
110 Field getField() throws IllegalStateException;
111
112 }