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 */ 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
