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}