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.stream.BodyDescriptor;
024 import org.apache.james.mime4j.stream.Field;
025
026 import java.io.IOException;
027 import java.io.InputStream;
028
029 /**
030 * <p>
031 * Receives notifications of the content of a plain RFC822 or MIME message.
032 * Implement this interface and register an instance of that implementation
033 * with a <code>MimeStreamParser</code> instance using its
034 * {@link org.apache.james.mime4j.parser.MimeStreamParser#setContentHandler(ContentHandler)}
035 * method. The parser uses the <code>ContentHandler</code> instance to report
036 * basic message-related events like the start and end of the body of a
037 * part in a multipart MIME entity.
038 * </p>
039 * <p>
040 * Throwing an exception from an event method will terminate the message
041 * processing, i.e. no new events will be generated for that message.
042 * <p>
043 * Events will be generated in the order the corresponding elements occur in
044 * the message stream parsed by the parser. E.g.:
045 * <pre>
046 * startMessage()
047 * startHeader()
048 * field(...)
049 * field(...)
050 * ...
051 * endHeader()
052 * startMultipart()
053 * preamble(...)
054 * startBodyPart()
055 * startHeader()
056 * field(...)
057 * field(...)
058 * ...
059 * endHeader()
060 * body()
061 * endBodyPart()
062 * startBodyPart()
063 * startHeader()
064 * field(...)
065 * field(...)
066 * ...
067 * endHeader()
068 * body()
069 * endBodyPart()
070 * epilogue(...)
071 * endMultipart()
072 * endMessage()
073 * </pre>
074 * The above shows an example of a MIME message consisting of a multipart
075 * body containing two body parts.
076 * </p>
077 * <p>
078 * See MIME RFCs 2045-2049 for more information on the structure of MIME
079 * messages and RFC 822 and 2822 for the general structure of Internet mail
080 * messages.
081 * </p>
082 */
083 public interface ContentHandler {
084
085 /**
086 * Called when a new message starts (a top level message or an embedded
087 * rfc822 message).
088 *
089 * @throws MimeException on processing errors
090 */
091 void startMessage() throws MimeException;
092
093 /**
094 * Called when a message ends.
095 *
096 * @throws MimeException on processing errors
097 */
098 void endMessage() throws MimeException;
099
100 /**
101 * Called when a new body part starts inside a
102 * <code>multipart/*</code> entity.
103 *
104 * @throws MimeException on processing errors
105 */
106 void startBodyPart() throws MimeException;
107
108 /**
109 * Called when a body part ends.
110 *
111 * @throws MimeException on processing errors
112 */
113 void endBodyPart() throws MimeException;
114
115 /**
116 * Called when a header (of a message or body part) is about to be parsed.
117 *
118 * @throws MimeException on processing errors
119 */
120 void startHeader() throws MimeException;
121
122 /**
123 * Called for each field of a header.
124 *
125 * @param rawField the MIME field.
126 * @throws MimeException on processing errors
127 */
128 void field(Field rawField) throws MimeException;
129
130 /**
131 * Called when there are no more header fields in a message or body part.
132 *
133 * @throws MimeException on processing errors
134 */
135 void endHeader() throws MimeException;
136
137 /**
138 * Called for the preamble (whatever comes before the first body part)
139 * of a <code>multipart/*</code> entity.
140 *
141 * @param is used to get the contents of the preamble.
142 * @throws MimeException on processing errors
143 * @throws IOException should be thrown on I/O errors.
144 */
145 void preamble(InputStream is) throws MimeException, IOException;
146
147 /**
148 * Called for the epilogue (whatever comes after the final body part)
149 * of a <code>multipart/*</code> entity.
150 *
151 * @param is used to get the contents of the epilogue.
152 * @throws MimeException on processing errors
153 * @throws IOException should be thrown on I/O errors.
154 */
155 void epilogue(InputStream is) throws MimeException, IOException;
156
157 /**
158 * Called when the body of a multipart entity is about to be parsed.
159 *
160 * @param bd encapsulates the values (either read from the
161 * message stream or, if not present, determined implictly
162 * as described in the
163 * MIME rfc:s) of the <code>Content-Type</code> and
164 * <code>Content-Transfer-Encoding</code> header fields.
165 * @throws MimeException on processing errors
166 */
167 void startMultipart(BodyDescriptor bd) throws MimeException;
168
169 /**
170 * Called when the body of an entity has been parsed.
171 *
172 * @throws MimeException on processing errors
173 */
174 void endMultipart() throws MimeException;
175
176 /**
177 * Called when the body of a discrete (non-multipart) entity is about to
178 * be parsed.
179 *
180 * @param bd see {@link #startMultipart(BodyDescriptor)}
181 * @param is the contents of the body. NOTE: this is the raw body contents
182 * - it will not be decoded if encoded. The <code>bd</code>
183 * parameter should be used to determine how the stream data
184 * should be decoded.
185 * @throws MimeException on processing errors
186 * @throws IOException should be thrown on I/O errors.
187 */
188 void body(BodyDescriptor bd, InputStream is)
189 throws MimeException, IOException;
190
191 /**
192 * Called when a new entity (message or body part) starts and the
193 * parser is in <code>raw</code> mode.
194 *
195 * @param is the raw contents of the entity.
196 * @throws MimeException on processing errors
197 * @throws IOException should be thrown on I/O errors.
198 * @see org.apache.james.mime4j.parser.MimeStreamParser#setRaw()
199 */
200 void raw(InputStream is) throws MimeException, IOException;
201
202 }