1/****************************************************************
2 * Licensed to the Apache Software Foundation (ASF) under one   *
3 * or more contributor license agreements.  See the NOTICE file *
4 * distributed with this work for additional information        *
5 * regarding copyright ownership.  The ASF licenses this file   *
6 * to you under the Apache License, Version 2.0 (the            *
7 * "License"); you may not use this file except in compliance   *
8 * with the License.  You may obtain a copy of the License at   *
9 *                                                              *
10 *   http://www.apache.org/licenses/LICENSE-2.0                 *
11 *                                                              *
12 * Unless required by applicable law or agreed to in writing,   *
13 * software distributed under the License is distributed on an  *
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
15 * KIND, either express or implied.  See the License for the    *
16 * specific language governing permissions and limitations      *
17 * under the License.                                           *
18 ****************************************************************/
19
20package org.apache.james.mime4j;
21
22import java.io.IOException;
23import java.io.InputStream;
24
25/**
26 * <p>
27 * Receives notifications of the content of a plain RFC822 or MIME message.
28 * Implement this interface and register an instance of that implementation
29 * with a <code>MimeStreamParser</code> instance using its
30 * {@link org.apache.james.mime4j.MimeStreamParser#setContentHandler(ContentHandler)}
31 * method. The parser uses the <code>ContentHandler</code> instance to report
32 * basic message-related events like the start and end of the body of a
33 * part in a multipart MIME entity.
34 * </p>
35 * <p>
36 * Events will be generated in the order the corresponding elements occur in
37 * the message stream parsed by the parser. E.g.:
38 * <pre>
39 *      startMessage()
40 *          startHeader()
41 *              field(...)
42 *              field(...)
43 *              ...
44 *          endHeader()
45 *          startMultipart()
46 *              preamble(...)
47 *              startBodyPart()
48 *                  startHeader()
49 *                      field(...)
50 *                      field(...)
51 *                      ...
52 *                  endHeader()
53 *                  body()
54 *              endBodyPart()
55 *              startBodyPart()
56 *                  startHeader()
57 *                      field(...)
58 *                      field(...)
59 *                      ...
60 *                  endHeader()
61 *                  body()
62 *              endBodyPart()
63 *              epilogue(...)
64 *          endMultipart()
65 *      endMessage()
66 * </pre>
67 * The above shows an example of a MIME message consisting of a multipart
68 * body containing two body parts.
69 * </p>
70 * <p>
71 * See MIME RFCs 2045-2049 for more information on the structure of MIME
72 * messages and RFC 822 and 2822 for the general structure of Internet mail
73 * messages.
74 * </p>
75 *
76 *
77 * @version $Id: ContentHandler.java,v 1.3 2004/10/02 12:41:10 ntherning Exp $
78 */
79public interface ContentHandler {
80    /**
81     * Called when a new message starts (a top level message or an embedded
82     * rfc822 message).
83     */
84    void startMessage();
85
86    /**
87     * Called when a message ends.
88     */
89    void endMessage();
90
91    /**
92     * Called when a new body part starts inside a
93     * <code>multipart/*</code> entity.
94     */
95    void startBodyPart();
96
97    /**
98     * Called when a body part ends.
99     */
100    void endBodyPart();
101
102    /**
103     * Called when a header (of a message or body part) is about to be parsed.
104     */
105    void startHeader();
106
107    /**
108     * Called for each field of a header.
109     *
110     * @param fieldData the raw contents of the field
111     *        (<code>Field-Name: field value</code>). The value will not be
112     *        unfolded.
113     */
114    void field(String fieldData);
115
116    /**
117     * Called when there are no more header fields in a message or body part.
118     */
119    void endHeader();
120
121    /**
122     * Called for the preamble (whatever comes before the first body part)
123     * of a <code>multipart/*</code> entity.
124     *
125     * @param is used to get the contents of the preamble.
126     * @throws IOException should be thrown on I/O errors.
127     */
128    void preamble(InputStream is) throws IOException;
129
130    /**
131     * Called for the epilogue (whatever comes after the final body part)
132     * of a <code>multipart/*</code> entity.
133     *
134     * @param is used to get the contents of the epilogue.
135     * @throws IOException should be thrown on I/O errors.
136     */
137    void epilogue(InputStream is) throws IOException;
138
139    /**
140     * Called when the body of a multipart entity is about to be parsed.
141     *
142     * @param bd encapsulates the values (either read from the
143     *        message stream or, if not present, determined implictly
144     *        as described in the
145     *        MIME rfc:s) of the <code>Content-Type</code> and
146     *        <code>Content-Transfer-Encoding</code> header fields.
147     */
148    void startMultipart(BodyDescriptor bd);
149
150    /**
151     * Called when the body of an entity has been parsed.
152     */
153    void endMultipart();
154
155    /**
156     * Called when the body of a discrete (non-multipart) entity is about to
157     * be parsed.
158     *
159     * @param bd see {@link #startMultipart(BodyDescriptor)}
160     * @param is the contents of the body. NOTE: this is the raw body contents
161     *           - it will not be decoded if encoded. The <code>bd</code>
162     *           parameter should be used to determine how the stream data
163     *           should be decoded.
164     * @throws IOException should be thrown on I/O errors.
165     */
166    void body(BodyDescriptor bd, InputStream is) throws IOException;
167
168    /**
169     * Called when a new entity (message or body part) starts and the
170     * parser is in <code>raw</code> mode.
171     *
172     * @param is the raw contents of the entity.
173     * @throws IOException should be thrown on I/O errors.
174     * @see MimeStreamParser#setRaw(boolean)
175     */
176    void raw(InputStream is) throws IOException;
177}
178