<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- 
/****************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
 ****************************************************************/

 -->
<document>
    <properties>
        <title>Mime4J</title>
    </properties>
    <body>
        <section name="Mime4j">
            <p>
                Apache James Mime4J is developed by the 
                <a href="http://james.apache.org/">Apache James</a> team but now has a
                dedicated <a href="http://james.apache.org/mail.html#Mime4j">mailing list</a>.
            </p>
            <p>Apache James Mime4J provides a parser, 
                <a href="apidocs/org/apache/james/mime4j/parser/MimeStreamParser.html">
                    <code>MimeStreamParser</code>
                </a>, for e-mail message streams in plain rfc822 and MIME
                format. The parser uses a callback mechanism to report parsing
                events such as the start of an entity header, the start of a
                body, etc. If you are familiar with the <a
                href="http://www.saxproject.org/">SAX</a> XML parser interface
                you should have no problem getting started with mime4j. </p>
            <p> The parser only deals with the structure of the message stream.
                It won't do any decoding of base64 or quoted-printable encoded
                header fields and bodies. This is intentional - the parser
                should only provide the most basic functionality needed to build
                more complex parsers. However, mime4j does include facilities to
                decode bodies and fields and the <code>Message</code> class
                described below handles decoding of fields and bodies
                transparently. </p>
            <p> The parser has been designed to be extremely tolerant against
                messages violating the standards. It has been tested using a
                large corpus (&gt;5000) of e-mail messages. As a benchmark
                the widely used perl <code>MIME::Tools</code>
                parser has been used. mime4j and MIME:Tools rarely differ
                (&lt;25 in those 5000). When they do (which only occurs
                for illegally formatted spam messages) we think mime4j does a
                better job. </p>
            <p> mime4j can also be used to build a tree representation of an
                e-mail message using the 
                <a href="apidocs/org/apache/james/mime4j/message/Message.html">
                    <code>Message</code>
                </a> class. Using this facility mime4j automatically handles the
                decoding of fields and bodies and uses temporary files for large
                attachments. This representation is similar to the
                representation constructed by the JavaMail API:s but is more
                tolerant to messages violating the standards. </p>
        </section>
        <section name="Examples">
            <p>
                As part of our git repository we provide a couple of
                <a href="https://github.com/apache/james-mime4j/tree/master/examples">
                examples</a> to ease the use of MIME4J.
            </p>
            <p>
                Read the following <a href="samples.html">page</a>.
            </p>
        </section>
    </body>
</document>