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
020package org.apache.james.mime4j.stream;
021
022import org.apache.james.mime4j.MimeException;
023
024import java.io.IOException;
025import 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 */
031public 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}