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-jsieve.git
commit 7d94f3f985b3562842c8d9463dcc9545ba612466 Author: Benoit TELLIER <[email protected]> AuthorDate: Sun Aug 23 23:31:20 2026 +0700 [DOC] Migrate to antora --- docs/antora.yml | 4 +- .../ROOT/assets/images/james-jsieve-logo.gif | Bin 0 -> 7014 bytes docs/modules/ROOT/nav.adoc | 8 ++ docs/modules/ROOT/pages/features.adoc | 74 +++++++++++++++ docs/modules/ROOT/pages/getting-started.adoc | 99 +++++++++++++++++++++ docs/modules/ROOT/pages/index.adoc | 80 ++++++++++++++++- docs/modules/ROOT/pages/release-notes.adoc | 62 +++++++++++++ docs/modules/ROOT/pages/specifications.adoc | 13 +++ docs/modules/ROOT/pages/utils.adoc | 26 ++++++ 9 files changed, 363 insertions(+), 3 deletions(-) diff --git a/docs/antora.yml b/docs/antora.yml index f5c9f9f..5c310c2 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,4 +1,6 @@ name: jsieve title: Apache James jSieve -version: '0.8-SNAPSHOT' +version: '0.9-SNAPSHOT' prerelease: true +nav: + - modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/assets/images/james-jsieve-logo.gif b/docs/modules/ROOT/assets/images/james-jsieve-logo.gif new file mode 100644 index 0000000..9c7e34f Binary files /dev/null and b/docs/modules/ROOT/assets/images/james-jsieve-logo.gif differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..d11ec72 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,8 @@ +* xref:index.adoc[Overview] +* xref:features.adoc[Sieve Features] +* xref:getting-started.adoc[Getting Started] +* xref:utils.adoc[jSieve Utilities] +* xref:specifications.adoc[Specifications] +* xref:release-notes.adoc[Release Notes] +* https://issues.apache.org/jira/browse/JSIEVE[Issue Tracker] +* https://james.apache.org/download.cgi#Apache_JSieve[Download Releases] diff --git a/docs/modules/ROOT/pages/features.adoc b/docs/modules/ROOT/pages/features.adoc new file mode 100644 index 0000000..6ce4c27 --- /dev/null +++ b/docs/modules/ROOT/pages/features.adoc @@ -0,0 +1,74 @@ += jSieve Features + +== Sieve Features Supported By jSieve + +jSieve is limited only by the platform on which it runs. + +[cols="1,1"] +|=== +|Limits | + +|Maximum Number Of Actions |No intrinsic limit +|Maximum Number Of Nested Blocks |No intrinsic limit +|Maximum Number Of Nested Test Lists |No intrinsic limit +|=== + +jSieve supports the standard control commands specified in RFC 5228. + +[cols="1,1,1"] +|=== +|Control Command |Specification |Supported + +|If |RFC 5228 (REQUIRED) |yes +|Require |RFC 5228 (REQUIRED) |yes +|Stop |RFC 5228 (REQUIRED) |yes +|=== + +jSieve supports all action commands (both required and optional) specified in RFC 5228. + +NOTE: jSieve uses a pluggable `MailAdapter` as an interface to the mail server. +Not all implementations may fully support all actions. + +[cols="1,1,1"] +|=== +|Action Command |Specification |Supported + +|fileinto |RFC 5228 (REQUIRED) |yes +|redirect |RFC 5228 (REQUIRED) |yes +|keep |RFC 5228 (REQUIRED) |yes +|discard |RFC 5228 (REQUIRED) |yes +|reject |RFC 5429 |yes +|ereject |RFC 5429 |no +|=== + +jSieve supports all tests commands specified in RFC 5228. + +[cols="1,1,1"] +|=== +|Test Command |Specification |Supported + +|address |RFC 5228 (REQUIRED) |yes +|allof |RFC 5228 (REQUIRED) |yes +|anyof |RFC 5228 (REQUIRED) |yes +|envelope |RFC 5228 (OPTIONAL) |yes +|exists |RFC 5228 (REQUIRED) |yes +|false |RFC 5228 (REQUIRED) |yes +|header |RFC 5228 (REQUIRED) |yes +|not |RFC 5228 (REQUIRED) |yes +|size |RFC 5228 (REQUIRED) |yes +|true |RFC 5228 (REQUIRED) |yes +|body |RFC 5173 |yes +|vacation |RFC 5230 |yes +|=== + +== jSieve Extension Commands + +jSieve allows extension commands to be developed and plugged in at run time. +The following extension commands ship with jSieve: + +[cols="1,1"] +|=== +|Name |Function + +|Log |Logs messages +|=== diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc new file mode 100644 index 0000000..e840a95 --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -0,0 +1,99 @@ += Getting Started + +Until these pages are fleshed out, the best way to understand jSieve is to read the +javadocs and look at the source code. The jUnit tests illustrate many aspects of the +implementation. + +== Using jSieve + +=== Standalone + +`org.apache.jsieve.SieveFactory` is the primary invocation point for all Sieve operations. +The API is clean and simple. See the javadocs for more details. + +=== In JAMES + +The `SieveMailboxMailet` mailet is part of the jsieve/mailet project. It provides a mailet +that applies SIEVE actions defined by a user SIEVE script to incoming e-mails. Integration +is done in the JAMES code base using a `SieveMailet` in project server/mailet/mailets. +This project: + +* Proposes a `SieveLocator` based on your `SieveRepository` for locating your user Sieve script +* Communicates via URLs with the classes introduced in server/mailet/mailets, allowing it to be +used independently from the API defined in James Mailbox. All you need to use +`SieveMailboxMailet` is a mailet environment + +Note that some integration tests in James server on mail delivery behave as integration tests +for JSIEVE in JAMES. Have a look at `org.apache.james.transport.mailets.delivery.SieveMailetTest`. + +In James server, Sieve scripts are stored by ``SieveRepository``(ies). Note that you can manage +your SIEVE scripts as a user on James using 3 mechanisms, depending on your installation: + +* With `SieveDefaultRepository` one needs to interact with the file system to customize their +scripts (legacy reasons) +* If enabled by the administrator, you can use a ManageSieve server, as specified in RFC-5804 +* Or you can rely on the `ManageSieveMailet` to handle ManageSieve over SMTP + +== Implementing A Mail Adapter + +`org.apache.jsieve.mail.MailAdapter` is the interface API used by jSieve to interact with a +mail server. + +The mail adapter wraps an email and supplies information (required by the script) about the +email. It is responsible for accumulating ``Action``s during the parsing of a script and for +executing them once the parsing is complete. + +See the javadocs for more details and the `SieveMailAdapter` implementation +(`org.apache.jsieve.samples.james.SieveMailAdapter`) for the mailets environment. + +== Implementing Extension Commands + +A parser is already implemented using jjTree. So the Sieve entities you will implement will +already be called with parsed arguments. You will have to validate such arguments (SIEVE syntax +check), handle parsing state modification (such as saying an action was taken, see +`SieveContext.getCommandStateManager()` for a deeper insight), and implement the behavior you +want regarding these arguments. + +You can implement additional extension commands. +`org.apache.jsieve.commands.extensions.Log` is an example of an extension command. It is +recommended that extension commands extend `AbstractCommand` +(`org.apache.jsieve.commands.AbstractCommand`). See the javadocs for more details. + +Commands need to be registered with `org.apache.jsieve.ConfigurationManager` before they can be +used. This may be done programmatically but the recommended method is by altering the +`org/apache/jsieve/commandsmap.properties`, `org/apache/jsieve/testsmap.properties` and +`org/apache/jsieve/comparatorsmap.properties` resource files. + +Commands generate actions that get transferred by commands to the `MailAdapter`. If you +introduce new actions, you will have to extend the `MailAdapter` API if you need more +information or actions from the mail server. + +Writing new tests can be done in a similar way: extend `AbstractTest` to implement your test. +Adding capabilities to the `MailAdapter` might be required. You also need to register it in +`org/apache/jsieve/testsmap.properties`. + +== Building jSieve + +jSieve uses https://maven.apache.org[Maven]. `mvn clean install` compiles the jSieve project +and installs it. + +== Comments, Questions and Issues + +jSieve is a sub-project of Apache James. Please direct your comments and questions to the +relevant https://james.apache.org/mail.html[James list]. + +To report issues, such as bugs, go to the +https://issues.apache.org/jira/browse/JSIEVE[jSieve Issue Tracker]. As jSieve comes with a +fairly extensive suite of jUnit tests, it would be most helpful for bug reports to be +accompanied by an illustrative jUnit test case. + +=== Frequently Asked Questions + +==== Why Do Tests Using Non-ASCII Characters Fail? + +`SIEVE` specifies that https://tools.ietf.org/html/rfc2278[UTF-8] encoding is used for scripts. +This format is an international standard and has wide support but not all platforms use this +encoding by default. + +By default, jSieve expects that scripts are encoded using `UTF-8`. Either set the encoding +programmatically or ensure that the script is encoded using `UTF-8`. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index ad7ff8c..5f18407 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,4 +1,80 @@ -= Apache James jSieve documentation += Apache James jSieve +image::james-jsieve-logo.gif[jSieve logo] -TODO: This is a placeholder. Migrate older documentation. +== What is jSieve? + +jSieve is a Java implementation of the Sieve mail filtering language defined by +https://tools.ietf.org/html/rfc5228[RFC 5228]. jSieve is implemented as a language +processor that can be plugged into any internet mail application to add Sieve support. + +jSieve is a subproject of https://james.apache.org[Apache JAMES]. All who are interested +in developing jSieve and JAMES will be warmly welcomed on the +https://james.apache.org/mail.html[mailing lists]. + +jSieve consists of two products: + +* *Apache JSieve* is a Sieve library coded in Java. See xref:getting-started.adoc[Getting Started] +and xref:features.adoc[Sieve Features]. +* xref:utils.adoc[*Apache JSieve Utilities*] contains utility classes helpful when using Sieve +but not considered sufficiently core to be included in the main library. + +=== What is Sieve? + +Sieve is an extensible mail filtering language. Its limited expressiveness (no loops or +variables, no tests with side effects) allows user created scripts to be run safely on email +servers. Sieve is targeted at the final delivery phase (where an incoming email is transferred +to a user's mailbox). + +Sieve scripts are composed of commands. Control commands manage the execution of the script. +Test commands define side-effect free criteria. Action commands are mail operations to be +performed. + +== Extensions Supported + +=== Body Extension + +https://tools.ietf.org/html/rfc5173[RFC 5173] (Sieve Email Filtering: Body Extension) describes +an extension command that tests the body of an email for one or more strings. + +=== Sieve-In-Xml + +https://tools.ietf.org/html/draft-freed-sieve-in-xml-04[Sieve-in-xml] is an Internet Draft. +It describes a method for converting Sieve scripts to and from XML fragments. +xref:utils.adoc[JSieve Utilities] contains an experimental preview of a subset of this draft +to allow early feedback. xref:utils.adoc#sieve-in-xml[More...] + +== News + +=== October/2022 - jSieve-0.8 released + +The Apache JAMES team is happy to announce the availability of +https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.8]. + +=== May/2010 - jSieve-0.5 released + +The Apache JAMES team is happy to announce the availability of +https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.5]. +See https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=10412&version=12314991&styleName=Html[release notes] +for more details. + +=== May/2010 - jSieve-0.4 released + +The Apache JAMES team is happy to announce the availability of +https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.4]. +See https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=10412&styleName=Html&version=12313855[release notes] +for more details. + +=== Jun/2008 - jSieve-0.3 released + +The Apache JAMES team is happy to announce the availability of +https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.3]. +This is the first modular release including a filtering +https://james.apache.org/mailet[mailet] as well as many fixes and improvements. +See the xref:release-notes.adoc[release notes] for more details. + +=== Aug/2008 - jSieve-0.2 released + +The Apache JAMES team is happy to announce the availability of +https://james.apache.org/download.cgi#Apache_JSieve[Apache jSieve 0.2]. +This first public release is a major milestone for JSieve. diff --git a/docs/modules/ROOT/pages/release-notes.adoc b/docs/modules/ROOT/pages/release-notes.adoc new file mode 100644 index 0000000..992da23 --- /dev/null +++ b/docs/modules/ROOT/pages/release-notes.adoc @@ -0,0 +1,62 @@ += Release Notes + +jSieve is a Java implementation of the Sieve mail filtering language defined by +https://tools.ietf.org/html/rfc5228[RFC 5228]. jSieve is implemented as a language processor +that can be plugged into any internet mail application to add Sieve support. + +== Comments, Questions and Issues + +jSieve is a sub-project of Apache James. Please direct your comments and questions to the +relevant https://james.apache.org/mail.html[James list]. + +To report issues, such as bugs, go to https://issues.apache.org/jira/browse/JSIEVE. +As jSieve comes with a fairly extensive suite of jUnit tests, it would be most helpful for bug +reports to be accompanied by an illustrative jUnit test case. + +== Licensing and legal issues + +For legal and licensing issues, please look in the legal section of the documentation or read +the `LICENSE.txt` and `NOTICE.txt` files. + +== Version 0.3 + +This release is the first to include mailet and utility modules, in addition to the core parsing +library. The configuration API has changed significantly to replace magic singletons with POJOs +suitable for IoC. The default configuration mechanism has been retained so though calls have +changed, existing configurations should still be compatible. + +Utilities include node serializers to xml and sieve script. The mailet module provides Sieve +in the James 3 codebase. + +=== Sub-tasks Completed + +* https://issues.apache.org/jira/browse/JSIEVE-27[JSIEVE-27] - Refactor ComparatorManager +* https://issues.apache.org/jira/browse/JSIEVE-29[JSIEVE-29] - Refactor ConfigurationManager +* https://issues.apache.org/jira/browse/JSIEVE-32[JSIEVE-32] - Refactor TestManager +* https://issues.apache.org/jira/browse/JSIEVE-37[JSIEVE-37] - Push main source down a level +* https://issues.apache.org/jira/browse/JSIEVE-38[JSIEVE-38] - Modular Ant Build +* https://issues.apache.org/jira/browse/JSIEVE-44[JSIEVE-44] - Create Check Module +* https://issues.apache.org/jira/browse/JSIEVE-45[JSIEVE-45] - Extract Reusable Ant Macros +* https://issues.apache.org/jira/browse/JSIEVE-46[JSIEVE-46] - Unified Distribution +* https://issues.apache.org/jira/browse/JSIEVE-48[JSIEVE-48] - Release Quality Maven Build + +=== Bugs Fixed + +* https://issues.apache.org/jira/browse/JSIEVE-49[JSIEVE-49] - CPU spins when `:matches` expression contains `"*************"` + +=== Improvements Made + +* https://issues.apache.org/jira/browse/JSIEVE-47[JSIEVE-47] - Access to script comments +* https://issues.apache.org/jira/browse/JSIEVE-52[JSIEVE-52] - Check Support For Numeric Quantifiers + +=== New Features Added + +* https://issues.apache.org/jira/browse/JSIEVE-43[JSIEVE-43] - Add API for generating a Sieve script from a parse tree +* https://issues.apache.org/jira/browse/JSIEVE-50[JSIEVE-50] - Sieve-In-XML (Experimental Preview) + +=== Tasks Completed + +* https://issues.apache.org/jira/browse/JSIEVE-16[JSIEVE-16] - Singletons -> IoC +* https://issues.apache.org/jira/browse/JSIEVE-24[JSIEVE-24] - Include build time libraries (javacc, javamail, activation) in the source distribution +* https://issues.apache.org/jira/browse/JSIEVE-33[JSIEVE-33] - Remove `.junit.` package name from tests +* https://issues.apache.org/jira/browse/JSIEVE-34[JSIEVE-34] - Make jsieve a multimodule project diff --git a/docs/modules/ROOT/pages/specifications.adoc b/docs/modules/ROOT/pages/specifications.adoc new file mode 100644 index 0000000..9d328c9 --- /dev/null +++ b/docs/modules/ROOT/pages/specifications.adoc @@ -0,0 +1,13 @@ += Specifications + +The specifications jSieve implements or relies upon: + +* https://tools.ietf.org/html/rfc2234[RFC 2234] - Augmented BNF for Syntax Specifications (ABNF) +* https://tools.ietf.org/html/rfc2244[RFC 2244] - Application Configuration Access Protocol (ACAP) +* https://tools.ietf.org/html/rfc2298[RFC 2298] - Message Disposition Notification (MDN) +* https://tools.ietf.org/html/rfc4790[RFC 4790] - Internet Application Protocol Collation Registry (IAPCR) +* https://tools.ietf.org/html/rfc5173[RFC 5173] - Sieve Email Filtering: Body Extension +* https://tools.ietf.org/html/rfc5228[RFC 5228] - Sieve: An Email Filtering Language +* https://tools.ietf.org/html/rfc5230[RFC 5230] - Sieve Email Filtering: Vacation Extension +* https://tools.ietf.org/html/rfc5429[RFC 5429] - Sieve Email Filtering: Reject and Extended Reject Extensions +* https://tools.ietf.org/html/rfc5804[RFC 5804] - A Protocol for Remotely Managing Sieve Scripts (ManageSieve) diff --git a/docs/modules/ROOT/pages/utils.adoc b/docs/modules/ROOT/pages/utils.adoc new file mode 100644 index 0000000..6900bc9 --- /dev/null +++ b/docs/modules/ROOT/pages/utils.adoc @@ -0,0 +1,26 @@ += Apache jSieve Utilities + +== Introduction + +jSieve Utilities collects lightweight frameworks and utilities useful when working with Sieve +(in general) and xref:index.adoc[jSieve] (in particular). + +They are shipped as the `org.apache.james:apache-jsieve-util` artifact. + +== Highlights + +=== Script Checker + +Checks Sieve scripts. Includes monitoring controlled execution of a script against a message. + +[[sieve-in-xml]] +=== Sieve In Xml + +https://tools.ietf.org/html/draft-freed-sieve-in-xml-04[Sieve-in-xml] is an Internet Draft. +It describes a method to convert Sieve scripts to and from an XML format suitable for editing +by a UI. A typical use case is as the payload for a web based editor backed by web services. + +`OutputUtils` contains an experimental preview of a subset of this draft. It allows a jSieve +node tree to be output as sieve-in-xml. Full support is planned but feedback is encouraged, +through the https://james.apache.org/mail.html[mailing lists] or the +https://issues.apache.org/jira/browse/JSIEVE[issue tracker]. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
