/****************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
 ****************************************************************/

package org.apache.james.mime4j.parser;

import org.apache.james.mime4j.BodyDescriptor;
import org.apache.james.mime4j.MimeException;

import java.io.IOException;
import java.io.InputStream;

/**
 * Represents the interal state of a MIME entity, which is being retrieved 
 * from an input stream by a MIME parser.
 */
public interface EntityStateMachine {

    /**
     * Return the current state of the entity.
     * 
     * @see EntityStates
     * 
     * @return current state
     */
    int getState();
    
    /**
     * Sets the current recursion mode.
     * The recursion mode specifies the approach taken to parsing parts.
     * {@link RecursionMode#M_RAW} mode does not parse the part at all.
     * {@link RecursionMode#M_RECURSE} mode recursively parses each mail
     * when an <code>message/rfc822</code> part is encounted;
     * {@link RecursionMode#M_NO_RECURSE} does not.
     * 
     * @see RecursionMode
     * 
     * @param recursionMode
     */
    void setRecursionMode(int recursionMode);
    
    /**
     * Advances the state machine to the next state in the 
     * process of the MIME stream parsing. This method 
     * may return an new state machine that represents an embedded 
     * entity, which must be parsed before the parsing process of 
     * the current entity can proceed.
     * 
     * @return a state machine of an embedded entity, if encountered, 
     * <code>null</code> otherwise.
     *  
     * @throws IOException if an I/O error occurs.
     * @throws MimeException if the message can not be processed due 
     *  to the MIME specification violation.
     */
    EntityStateMachine advance() throws IOException, MimeException;
    
    /**
     * Returns description of the entity body.
     * 
     * @return body description
     * 
     * @throws IllegalStateException if the body description cannot be
     *  obtained at the current stage of the parsing process. 
     */
    BodyDescriptor getBodyDescriptor() throws IllegalStateException;
    
    /**
     * Returns content stream of the entity body.
     * 
     * @return input stream
     * 
     * @throws IllegalStateException if the content stream cannot be
     *  obtained at the current stage of the parsing process. 
     */
    InputStream getContentStream() throws IllegalStateException;
 
    /**
     * Returns current header field.
     * 
     * @return header field
     * 
     * @throws IllegalStateException if a header field cannot be
     *  obtained at the current stage of the parsing process. 
     */
    String getField() throws IllegalStateException;
    
    /**
     * Returns name of the current header field.
     * 
     * @return field name
     * 
     * @throws IllegalStateException if a header field cannot be
     *  obtained at the current stage of the parsing process. 
     */
    String getFieldName() throws IllegalStateException;

    /**
     * Returns value of the current header field.
     * 
     * @return field value
     * 
     * @throws IllegalStateException if a header field cannot be
     *  obtained at the current stage of the parsing process. 
     */
    String getFieldValue() throws IllegalStateException;
    
}