14fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy/**************************************************************** 24fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Licensed to the Apache Software Foundation (ASF) under one * 34fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * or more contributor license agreements. See the NOTICE file * 44fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * distributed with this work for additional information * 54fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * regarding copyright ownership. The ASF licenses this file * 64fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * to you under the Apache License, Version 2.0 (the * 74fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * "License"); you may not use this file except in compliance * 84fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * with the License. You may obtain a copy of the License at * 94fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * * 104fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * http://www.apache.org/licenses/LICENSE-2.0 * 114fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * * 124fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Unless required by applicable law or agreed to in writing, * 134fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * software distributed under the License is distributed on an * 144fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * 154fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * KIND, either express or implied. See the License for the * 164fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * specific language governing permissions and limitations * 174fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * under the License. * 184fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy ****************************************************************/ 194fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 204fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedypackage org.apache.james.mime4j; 214fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 224fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedyimport java.io.IOException; 234fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedyimport java.io.InputStream; 244fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 254fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy/** 264fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * <p> 274fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Receives notifications of the content of a plain RFC822 or MIME message. 284fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Implement this interface and register an instance of that implementation 294fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * with a <code>MimeStreamParser</code> instance using its 304fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * {@link org.apache.james.mime4j.MimeStreamParser#setContentHandler(ContentHandler)} 314fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * method. The parser uses the <code>ContentHandler</code> instance to report 324fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * basic message-related events like the start and end of the body of a 334fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * part in a multipart MIME entity. 344fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * </p> 354fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * <p> 364fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Events will be generated in the order the corresponding elements occur in 374fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * the message stream parsed by the parser. E.g.: 384fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * <pre> 394fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startMessage() 404fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startHeader() 414fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * field(...) 424fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * field(...) 434fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * ... 444fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endHeader() 454fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startMultipart() 464fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * preamble(...) 474fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startBodyPart() 484fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startHeader() 494fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * field(...) 504fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * field(...) 514fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * ... 524fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endHeader() 534fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * body() 544fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endBodyPart() 554fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startBodyPart() 564fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * startHeader() 574fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * field(...) 584fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * field(...) 594fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * ... 604fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endHeader() 614fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * body() 624fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endBodyPart() 634fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * epilogue(...) 644fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endMultipart() 654fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * endMessage() 664fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * </pre> 674fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * The above shows an example of a MIME message consisting of a multipart 684fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * body containing two body parts. 694fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * </p> 704fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * <p> 714fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * See MIME RFCs 2045-2049 for more information on the structure of MIME 724fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * messages and RFC 822 and 2822 for the general structure of Internet mail 734fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * messages. 744fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * </p> 754fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 764fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 774fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @version $Id: ContentHandler.java,v 1.3 2004/10/02 12:41:10 ntherning Exp $ 784fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 794fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedypublic interface ContentHandler { 804fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 814fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when a new message starts (a top level message or an embedded 824fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * rfc822 message). 834fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 844fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void startMessage(); 854fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 864fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 874fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when a message ends. 884fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 894fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void endMessage(); 904fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 914fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 924fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when a new body part starts inside a 934fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * <code>multipart/*</code> entity. 944fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 954fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void startBodyPart(); 964fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 974fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 984fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when a body part ends. 994fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1004fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void endBodyPart(); 1014fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1024fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1034fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when a header (of a message or body part) is about to be parsed. 1044fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1054fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void startHeader(); 1064fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1074fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1084fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called for each field of a header. 1094fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 1104fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param fieldData the raw contents of the field 1114fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * (<code>Field-Name: field value</code>). The value will not be 1124fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * unfolded. 1134fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1144fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void field(String fieldData); 1154fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1164fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1174fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when there are no more header fields in a message or body part. 1184fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1194fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void endHeader(); 1204fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1214fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1224fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called for the preamble (whatever comes before the first body part) 1234fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * of a <code>multipart/*</code> entity. 1244fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 1254fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param is used to get the contents of the preamble. 1264fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @throws IOException should be thrown on I/O errors. 1274fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1284fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void preamble(InputStream is) throws IOException; 1294fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1304fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1314fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called for the epilogue (whatever comes after the final body part) 1324fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * of a <code>multipart/*</code> entity. 1334fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 1344fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param is used to get the contents of the epilogue. 1354fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @throws IOException should be thrown on I/O errors. 1364fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1374fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void epilogue(InputStream is) throws IOException; 1384fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1394fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1404fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when the body of a multipart entity is about to be parsed. 1414fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 1424fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param bd encapsulates the values (either read from the 1434fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * message stream or, if not present, determined implictly 1444fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * as described in the 1454fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * MIME rfc:s) of the <code>Content-Type</code> and 1464fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * <code>Content-Transfer-Encoding</code> header fields. 1474fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1484fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void startMultipart(BodyDescriptor bd); 1494fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1504fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1514fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when the body of an entity has been parsed. 1524fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1534fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void endMultipart(); 1544fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1554fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1564fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when the body of a discrete (non-multipart) entity is about to 1574fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * be parsed. 1584fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 1594fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param bd see {@link #startMultipart(BodyDescriptor)} 1604fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param is the contents of the body. NOTE: this is the raw body contents 1614fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * - it will not be decoded if encoded. The <code>bd</code> 1624fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * parameter should be used to determine how the stream data 1634fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * should be decoded. 1644fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @throws IOException should be thrown on I/O errors. 1654fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1664fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void body(BodyDescriptor bd, InputStream is) throws IOException; 1674fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy 1684fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy /** 1694fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * Called when a new entity (message or body part) starts and the 1704fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * parser is in <code>raw</code> mode. 1714fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * 1724fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @param is the raw contents of the entity. 1734fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @throws IOException should be thrown on I/O errors. 1744fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy * @see MimeStreamParser#setRaw(boolean) 1754fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy */ 1764fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy void raw(InputStream is) throws IOException; 1774fa0a3295bcacbdcd6a9e7709cf17aa5adb90356Scott Kennedy} 178