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    }