This is an automated email from the ASF dual-hosted git repository. chibenwa pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-mime4j.git
commit adfd2a5d78739db07b5959011e6ae0a42653eb24 Author: Benoit TELLIER <[email protected]> AuthorDate: Sun Aug 23 23:00:49 2026 +0700 [DOC] Migrate content to Antora --- docs/antora.yml | 4 +- docs/modules/ROOT/assets/images/james-logo.png | Bin 0 -> 5243 bytes docs/modules/ROOT/nav.adoc | 10 ++ docs/modules/ROOT/pages/development/build.adoc | 62 ++++++++++ docs/modules/ROOT/pages/development/index.adoc | 16 +++ docs/modules/ROOT/pages/index.adoc | 39 +++++- docs/modules/ROOT/pages/samples.adoc | 38 ++++++ docs/modules/ROOT/pages/status.adoc | 27 +++++ docs/modules/ROOT/pages/usage.adoc | 162 +++++++++++++++++++++++++ 9 files changed, 355 insertions(+), 3 deletions(-) diff --git a/docs/antora.yml b/docs/antora.yml index ec23c59f..020ee6df 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,4 +1,6 @@ name: mime4j title: Apache James Mime4j -version: '0.8.4-SNAPSHOT' +version: '0.8.15-SNAPSHOT' prerelease: true +nav: + - modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/assets/images/james-logo.png b/docs/modules/ROOT/assets/images/james-logo.png new file mode 100644 index 00000000..2ef3d9a1 Binary files /dev/null and b/docs/modules/ROOT/assets/images/james-logo.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 00000000..b4140ef4 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,10 @@ +* xref:index.adoc[Overview] +* xref:status.adoc[Status] +* xref:samples.adoc[Examples] +* xref:usage.adoc[Usage] +* xref:development/index.adoc[Developer corner] +** xref:development/build.adoc[Build] +* https://james.apache.org/mail.html#Mime4j[Mailing list] +* https://james.apache.org/mime4j/apidocs/index.html[Javadoc] +* https://issues.apache.org/jira/browse/MIME4J/[Issue tracker] +* https://james.apache.org/download.cgi#Apache_Mime4J[Download releases] diff --git a/docs/modules/ROOT/pages/development/build.adoc b/docs/modules/ROOT/pages/development/build.adoc new file mode 100644 index 00000000..4b599373 --- /dev/null +++ b/docs/modules/ROOT/pages/development/build.adoc @@ -0,0 +1,62 @@ += Building Mime4J + +== Using a stable release + +Go to the https://james.apache.org/download.cgi#Apache_Mime4J[download pages] and download +the most recent release in your preferred format, either `james-mime4j-x.y-src.tar.gz` or +`james-mime4j-x.y-src.zip`. Extracting the archived sources will create the directory +`james-mime4j-x.y/`. + +== Checking out the sources + +Issue the following command in a shell: + +---- +git clone https://github.com/apache/james-mime4j.git +---- + +== Download and install Maven + +You will need to download and install https://maven.apache.org/[Maven] before building the +sources. Maven 3.6.0 is the minimum required version. + +One of the main differences between Maven and plain ant is that Maven manages external +dependencies for your projects and (at least in theory) you should no longer have to store +third-party jar files in your source code tree. It maintains a local repository of +versioned libraries and shares them between your Maven projects. If it can't find the +necessary files there it will attempt to download them from Maven central. So to use the +Maven build, you need to have a network connection available for the initial download of +the project dependencies. + +== Building the Mime4J jar + +Once Maven has been installed, building the project should be as simple as typing + +---- +cd james-mime4j-x.y/ (cd james-mime4j/ if sources come from git) +mvn package +---- + +from the command line. Maven will automatically run all test cases for you and create the +jar file in the `target` directory. + +To install the jars into your local Maven repository run: + +---- +mvn install +---- + +Useful options include: + +* `-DskipTests` to skip the test suite. +* `-T 4` to parallelize the build on several CPUs. + +[NOTE] +==== +Mime4J uses https://javacc.github.io/javacc/[JavaCC] to generate parsers for header fields. +If your IDE does not pick up the generated code automatically, add +`target/generated-sources/javacc` and `target/generated-sources/jjtree` as source folders. +==== + +For more information on using Maven, have a look at the +https://maven.apache.org/[Maven web site]. diff --git a/docs/modules/ROOT/pages/development/index.adoc b/docs/modules/ROOT/pages/development/index.adoc new file mode 100644 index 00000000..e6d8f1fa --- /dev/null +++ b/docs/modules/ROOT/pages/development/index.adoc @@ -0,0 +1,16 @@ += Getting started with Mime4J + +Overview of the getting started documentation. + +[cols="1,2"] +|=== +|Document |Description + +|https://james.apache.org/download.cgi#Apache_Mime4J[Download] +|Before you can start using Mime4J, you'll have to download the distribution to your system +(unless you plan on building the project from source). This document provides links to the +various distributions available. + +|xref:development/build.adoc[Building Mime4J] +|Describes how to build Mime4J from the sources. +|=== diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index ad7ff8cb..f4da1517 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,4 +1,39 @@ -= Apache James jSieve documentation += Apache James Mime4J +image::james-logo.png[link="https://james.apache.org";] -TODO: This is a placeholder. Migrate older documentation. +Apache James Mime4J is developed by the https://james.apache.org/[Apache James] team but +now has a dedicated https://james.apache.org/mail.html#Mime4j[mailing list]. + +Apache James Mime4J provides a parser, +https://james.apache.org/mime4j/apidocs/org/apache/james/mime4j/parser/MimeStreamParser.html[`MimeStreamParser`], +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 http://www.saxproject.org/[SAX] XML parser +interface you should have no problem getting started with Mime4J. + +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 +`Message` class described below handles decoding of fields and bodies transparently. + +The parser has been designed to be extremely tolerant against messages violating the +standards. It has been tested using a large corpus (>5000) of e-mail messages. As a +benchmark the widely used perl `MIME::Tools` parser has been used. Mime4J and MIME::Tools +rarely differ (<25 in those 5000). When they do (which only occurs for illegally formatted +spam messages) we think Mime4J does a better job. + +Mime4J can also be used to build a tree representation of an e-mail message using the +https://james.apache.org/mime4j/apidocs/org/apache/james/mime4j/message/Message.html[`Message`] +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 APIs but is more tolerant to messages violating +the standards. + +== Examples + +As part of our git repository we provide a couple of +https://github.com/apache/james-mime4j/tree/master/examples[examples] to ease the use of Mime4J. + +Read the xref:samples.adoc[examples page]. diff --git a/docs/modules/ROOT/pages/samples.adoc b/docs/modules/ROOT/pages/samples.adoc new file mode 100644 index 00000000..200f8730 --- /dev/null +++ b/docs/modules/ROOT/pages/samples.adoc @@ -0,0 +1,38 @@ += Examples + +The Mime4J distribution includes +https://github.com/apache/james-mime4j/tree/master/examples[examples] which demonstrate how +the library could be used. This section gives you a short review of those samples. For more +information you should download the distribution and study the sample sources. The samples +are in the `examples/` sub-directory. + +Each one of these examples can be run easily from an IDE. + +[cols="1,1"] +|=== +|Sample |Description + +|https://github.com/apache/james-mime4j/tree/master/examples/src/main/java/org/apache/james/mime4j/samples/tree/MessageTree.java[org.apache.james.mime4j.samples.tree.MessageTree] +a|Displays a tree of the contents of a Mime4J `Message` object in a Swing GUI. To try it out run + +---- +java org.apache.james.mime4j.samples.tree.MessageTree path/to/message.msg +---- + +The output is very useful if you want to study the structure of MIME messages. + +|https://github.com/apache/james-mime4j/tree/master/examples/src/main/java/org/apache/james/mime4j/samples/transform/TransformMessage.java[org.apache.james.mime4j.samples.transform.TransformMessage] +|Illustrate how to transform a message into another message without modifying the original. + +|https://github.com/apache/james-mime4j/tree/master/examples/src/main/java/org/apache/james/mime4j/samples/dom/TextPlainMessage.java[org.apache.james.mime4j.samples.dom.TextPlainMessage] +|Illustrate the use of Mime4J DOM API. This example generates a message very similar to the +one from https://www.rfc-editor.org/rfc/rfc5322.txt[RFC 5322] Appendix A.1.1. + +|https://github.com/apache/james-mime4j/tree/master/examples/src/main/java/org/apache/james/mime4j/samples/dom/MultipartMessage.java[org.apache.james.mime4j.samples.dom.MultipartMessage] +|Illustrate the use of Mime4J DOM API. This example creates a multipart/mixed message that +consists of a text/plain and an image/png part. The image is created on the fly; a similar +technique can be used to create PDF or XML attachments, for example. + +|https://github.com/apache/james-mime4j/tree/master/examples/src/main/java/org/apache/james/mime4j/samples/dom/ParsingMessage.java[org.apache.james.mime4j.samples.dom.ParsingMessage] +|Illustrate the use of Mime4J DOM API in order to parse messages. +|=== diff --git a/docs/modules/ROOT/pages/status.adoc b/docs/modules/ROOT/pages/status.adoc new file mode 100644 index 00000000..30a413f4 --- /dev/null +++ b/docs/modules/ROOT/pages/status.adoc @@ -0,0 +1,27 @@ += Status + +The 0.4 release brought a number of significant improvements in terms of supported +capabilities, flexibility and performance. + +The 0.5 release addressed a number of important issues discovered since the 0.4 release. +In particular it improved Mime4J ability to deal with malformed data streams including +those intentionally crafted to cause excessive CPU and memory utilization that can lead to +DoS conditions. + +The 0.6 release brought another round of API enhancements and performance optimizations. +As of this release Mime4J requires a Java 1.5 compatible runtime. + +The 0.7 release brings another round of API enhancements, bug fixes and performance +optimizations. A major effort has been put in code reorganization, separating parsing code +from DOM manipulation code. Mime4J has been restructured into three separate modules: +`core`, `dom` and `storage`. The `core` package provides an event-driven SAX style parser +that relies on a callback mechanism to report parsing events such as the start of an +entity header, the start of a body, etc. The `dom` package contains base/abstract classes +and interfaces for MIME-DOM manipulation aiming to provide the base for a full featured +traversable DOM. Per default the Mime4J DOM builder stores content of individual body +parts in memory. The `storage` package provides support for more complex storage backends +such as on-disk storage systems, overflow on max limit, or encrypted storage through the +JSSE API. + +The next release will be version 0.8. As of this release Mime4J requires a Java 1.6 +compatible runtime. diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc new file mode 100644 index 00000000..9ef09ec2 --- /dev/null +++ b/docs/modules/ROOT/pages/usage.adoc @@ -0,0 +1,162 @@ += Usage + +Mime4J provides two different APIs: an event based API by using the +https://james.apache.org/mime4j/apidocs/org/apache/james/mime4j/parser/MimeStreamParser.html[`MimeStreamParser`]. +Alternatively, you may use the iterative API, which is available through the +https://james.apache.org/mime4j/apidocs/org/apache/james/mime4j/parser/MimeTokenStream.html[`MimeTokenStream`]. +In terms of speed, you should not note any differences. + +* <<Token streams>> +* <<Sample token stream>> +* <<Event handlers>> +* <<Sample event stream>> + +== Token streams + +The iterative approach is using the class +https://james.apache.org/mime4j/apidocs/org/apache/james/mime4j/parser/MimeTokenStream.html[`MimeTokenStream`]. +Here's an example, how you could use the token stream: + +[source,java] +---- +MimeTokenStream stream = new MimeTokenStream(); +stream.parse(new FileInputStream("mime.msg")); +for (EntityState state = stream.getState(); + state != EntityState.T_END_OF_STREAM; + state = stream.next()) { + switch (state) { + case T_BODY: + System.out.println("Body detected, contents = " + + stream.getInputStream() + ", header data = " + + stream.getBodyDescriptor()); + break; + case T_FIELD: + System.out.println("Header field detected: " + + stream.getField()); + break; + case T_START_MULTIPART: + System.out.println("Multipart message detexted," + + " header data = " + + stream.getBodyDescriptor()); + ... + } +} +---- + +The token stream provides a set of tokens. Tokens are identified by a state. Most states +are simply event indicators, with no additional data available. However, there are some +states, which provide additional data. For example, the state `T_BODY`, which indicates +that an actual body is available. If you note this state, then you may ask for the bodies +contents, which are provided through the `getInputStream()` method, or you might ask for +the header data by invoking `getBodyDescriptor()`. + +== Sample token stream + +The following sample should give you a rough idea of the order, in which you'll receive +tokens: + +---- +T_START_MESSAGE + T_START_HEADER + T_FIELD + T_FIELD + ... + T_END_HEADER + T_START_MULTIPART + T_PREAMBLE + T_START_BODYPART + T_START_HEADER + T_FIELD + T_FIELD + ... + T_END_HEADER + T_BODY + T_END_BODYPART + T_START_BODYPART + T_START_HEADER + T_FIELD + T_FIELD + ... + T_END_HEADER + T_BODY + T_END_BODYPART + T_EPILOGUE + T_END_MULTIPART + T_END_MESSAGE +---- + +The example shows a multipart message with two parts. + +== Event handlers + +The event based API requires, that you provide an event handler, which receives events. +The event handler is an object, which implements the +https://james.apache.org/mime4j/apidocs/org/apache/james/mime4j/parser/ContentHandler.html[`ContentHandler`] +interface. Here's an example, how you could implement an event handler: + +[source,java] +---- +public class MyContentHandler extends AbstractContentHandler { + + public void body(BodyDescriptor bd, InputStream is) + throws MimeException, IOException { + System.out.println("Body detected, contents = " + + is + ", header data = " + bd); + } + public void field(String fieldData) throws MimeException { + System.out.println("Header field detected: " + + fieldData); + } + public void startMultipart(BodyDescriptor bd) throws MimeException { + System.out.println("Multipart message detexted, header data = " + + bd); + } + ... +} +---- + +A little bit of additional code allows us to create an example, which is functionally +equivalent to the example from the section on <<Token streams>>: + +[source,java] +---- +ContentHandler handler = new MyContentHandler(); +MimeStreamParser parser = new MimeStreamParser(); +parser.setContentHandler(handler); +parser.parse(new FileInputStream("mime.msg")); +---- + +== Sample event stream + +Like above for tokens, we provide an additional example, which demonstrates the typical +order of events that you have to expect: + +---- +startMessage() + startHeader() + field(...) + field(...) + ... + endHeader() + startMultipart() + preamble(...) + startBodyPart() + startHeader() + field(...) + field(...) + ... + endHeader() + body() + endBodyPart() + startBodyPart() + startHeader() + field(...) + field(...) + ... + endHeader() + body() + endBodyPart() + epilogue(...) + endMultipart() +endMessage() +---- --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
