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 
20 package org.apache.james.mime4j;
21 
22 import java.io.IOException;
23 import 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  */
79 public interface ContentHandler {
80     /**
81      * Called when a new message starts (a top level message or an embedded
82      * rfc822 message).
83      */
startMessage()84     void startMessage();
85 
86     /**
87      * Called when a message ends.
88      */
endMessage()89     void endMessage();
90 
91     /**
92      * Called when a new body part starts inside a
93      * <code>multipart/*</code> entity.
94      */
startBodyPart()95     void startBodyPart();
96 
97     /**
98      * Called when a body part ends.
99      */
endBodyPart()100     void endBodyPart();
101 
102     /**
103      * Called when a header (of a message or body part) is about to be parsed.
104      */
startHeader()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      */
field(String fieldData)114     void field(String fieldData);
115 
116     /**
117      * Called when there are no more header fields in a message or body part.
118      */
endHeader()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      */
preamble(InputStream is)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      */
epilogue(InputStream is)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      */
startMultipart(BodyDescriptor bd)148     void startMultipart(BodyDescriptor bd);
149 
150     /**
151      * Called when the body of an entity has been parsed.
152      */
endMultipart()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      */
body(BodyDescriptor bd, InputStream is)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      */
raw(InputStream is)176     void raw(InputStream is) throws IOException;
177 }
178