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 }