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.parser;
021    
022    import org.apache.james.mime4j.MimeException;
023    import org.apache.james.mime4j.descriptor.BodyDescriptor;
024    
025    import java.io.IOException;
026    import java.io.InputStream;
027    
028    /**
029     * Represents the interal state of a MIME entity, which is being retrieved 
030     * from an input stream by a MIME parser.
031     */
032    public interface EntityStateMachine {
033    
034        /**
035         * Return the current state of the entity.
036         * 
037         * @see EntityStates
038         * 
039         * @return current state
040         */
041        int getState();
042        
043        /**
044         * Sets the current recursion mode.
045         * The recursion mode specifies the approach taken to parsing parts.
046         * {@link RecursionMode#M_RAW} mode does not parse the part at all.
047         * {@link RecursionMode#M_RECURSE} mode recursively parses each mail
048         * when an <code>message/rfc822</code> part is encounted;
049         * {@link RecursionMode#M_NO_RECURSE} does not.
050         * 
051         * @see RecursionMode
052         * 
053         * @param recursionMode
054         */
055        void setRecursionMode(int recursionMode);
056        
057        /**
058         * Advances the state machine to the next state in the 
059         * process of the MIME stream parsing. This method 
060         * may return an new state machine that represents an embedded 
061         * entity, which must be parsed before the parsing process of 
062         * the current entity can proceed.
063         * 
064         * @return a state machine of an embedded entity, if encountered, 
065         * <code>null</code> otherwise.
066         *  
067         * @throws IOException if an I/O error occurs.
068         * @throws MimeException if the message can not be processed due 
069         *  to the MIME specification violation.
070         */
071        EntityStateMachine advance() throws IOException, MimeException;
072        
073        /**
074         * Returns description of the entity body.
075         * 
076         * @return body description
077         * 
078         * @throws IllegalStateException if the body description cannot be
079         *  obtained at the current stage of the parsing process. 
080         */
081        BodyDescriptor getBodyDescriptor() throws IllegalStateException;
082        
083        /**
084         * Returns content stream of the entity body.
085         * 
086         * @return input stream
087         * 
088         * @throws IllegalStateException if the content stream cannot be
089         *  obtained at the current stage of the parsing process. 
090         */
091        InputStream getContentStream() throws IllegalStateException;
092     
093        /**
094         * Returns current header field.
095         * 
096         * @return header field
097         * 
098         * @throws IllegalStateException if a header field cannot be
099         *  obtained at the current stage of the parsing process. 
100         */
101        Field getField() throws IllegalStateException;
102        
103    }