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()
+----
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.