src/main/java/org/apache/james/mime4j/ContentHandler.java

   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  * Throwing an exception from an event method will terminate the message
  37  * processing, i.e. no new events will be generated for that message.
  38  * <p>
  39  * Events will be generated in the order the corresponding elements occur in
  40  * the message stream parsed by the parser. E.g.:
  41  * <pre>
  42  *      startMessage()
  43  *          startHeader()
  44  *              field(...)
  45  *              field(...)
  46  *              ...
  47  *          endHeader()
  48  *          startMultipart()
  49  *              preamble(...)
  50  *              startBodyPart()
  51  *                  startHeader()
  52  *                      field(...)
  53  *                      field(...)
  54  *                      ...
  55  *                  endHeader()
  56  *                  body()
  57  *              endBodyPart()
  58  *              startBodyPart()
  59  *                  startHeader()
  60  *                      field(...)
  61  *                      field(...)
  62  *                      ...
  63  *                  endHeader()
  64  *                  body()
  65  *              endBodyPart()
  66  *              epilogue(...)
  67  *          endMultipart()
  68  *      endMessage()
  69  * </pre>
  70  * The above shows an example of a MIME message consisting of a multipart
  71  * body containing two body parts.
  72  * </p>
  73  * <p>
  74  * See MIME RFCs 2045-2049 for more information on the structure of MIME
  75  * messages and RFC 822 and 2822 for the general structure of Internet mail
  76  * messages.
  77  * </p>
  78  *
  79  *
  80  * @version $Id: ContentHandler.java,v 1.3 2004/10/02 12:41:10 ntherning Exp $
  81  */
  82 public interface ContentHandler {
  83
  84     /**
  85      * Called when a new message starts (a top level message or an embedded
  86      * rfc822 message).
  87      *
  88      * @throws MimeException on processing errors
  89      */
  90     void startMessage() throws MimeException;
  91
  92     /**
  93      * Called when a message ends.
  94      *
  95      * @throws MimeException on processing errors
  96      */
  97     void endMessage() throws MimeException;
  98
  99     /**
 100      * Called when a new body part starts inside a
 101      * <code>multipart/*</code> entity.
 102      *
 103      * @throws MimeException on processing errors
 104      */
 105     void startBodyPart() throws MimeException;
 106
 107     /**
 108      * Called when a body part ends.
 109      *
 110      * @throws MimeException on processing errors
 111      */
 112     void endBodyPart() throws MimeException;
 113
 114     /**
 115      * Called when a header (of a message or body part) is about to be parsed.
 116      *
 117      * @throws MimeException on processing errors
 118      */
 119     void startHeader() throws MimeException;
 120
 121     /**
 122      * Called for each field of a header.
 123      *
 124      * @param fieldData the raw contents of the field
 125      *        (<code>Field-Name: field value</code>). The value will not be
 126      *        unfolded.
 127      * @throws MimeException on processing errors
 128      */
 129     void field(String fieldData) throws MimeException;
 130
 131     /**
 132      * Called when there are no more header fields in a message or body part.
 133      *
 134      * @throws MimeException on processing errors
 135      */
 136     void endHeader() throws MimeException;
 137
 138     /**
 139      * Called for the preamble (whatever comes before the first body part)
 140      * of a <code>multipart/*</code> entity.
 141      *
 142      * @param is used to get the contents of the preamble.
 143      * @throws MimeException on processing errors
 144      * @throws IOException should be thrown on I/O errors.
 145      */
 146     void preamble(InputStream is) throws MimeException, IOException;
 147
 148     /**
 149      * Called for the epilogue (whatever comes after the final body part)
 150      * of a <code>multipart/*</code> entity.
 151      *
 152      * @param is used to get the contents of the epilogue.
 153      * @throws MimeException on processing errors
 154      * @throws IOException should be thrown on I/O errors.
 155      */
 156     void epilogue(InputStream is) throws MimeException, IOException;
 157
 158     /**
 159      * Called when the body of a multipart entity is about to be parsed.
 160      *
 161      * @param bd encapsulates the values (either read from the
 162      *        message stream or, if not present, determined implictly
 163      *        as described in the
 164      *        MIME rfc:s) of the <code>Content-Type</code> and
 165      *        <code>Content-Transfer-Encoding</code> header fields.
 166      * @throws MimeException on processing errors
 167      */
 168     void startMultipart(BodyDescriptor bd) throws MimeException;
 169
 170     /**
 171      * Called when the body of an entity has been parsed.
 172      *
 173      * @throws MimeException on processing errors
 174      */
 175     void endMultipart() throws MimeException;
 176
 177     /**
 178      * Called when the body of a discrete (non-multipart) entity is about to
 179      * be parsed.
 180      *
 181      * @param bd see {@link #startMultipart(BodyDescriptor)}
 182      * @param is the contents of the body. NOTE: this is the raw body contents
 183      *           - it will not be decoded if encoded. The <code>bd</code>
 184      *           parameter should be used to determine how the stream data
 185      *           should be decoded.
 186      * @throws MimeException on processing errors
 187      * @throws IOException should be thrown on I/O errors.
 188      */
 189     void body(BodyDescriptor bd, InputStream is)
 190         throws MimeException, IOException;
 191
 192     /**
 193      * Called when a new entity (message or body part) starts and the
 194      * parser is in <code>raw</code> mode.
 195      *
 196      * @param is the raw contents of the entity.
 197      * @throws MimeException on processing errors
 198      * @throws IOException should be thrown on I/O errors.
 199      * @see MimeStreamParser#setRaw(boolean)
 200      */
 201     void raw(InputStream is) throws MimeException, IOException;
 202
 203 }