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