You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by rc...@apache.org on 2020/03/17 10:51:14 UTC
[james-project] 04/17: JAMES-3112 Better document RRT mapping types
This is an automated email from the ASF dual-hosted git repository.
rcordier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit d5df3beec36860018a22016baf4103f7ed116280
Author: Benoit Tellier <bt...@linagora.com>
AuthorDate: Tue Mar 10 09:26:50 2020 +0700
JAMES-3112 Better document RRT mapping types
---
.../java/org/apache/james/rrt/lib/Mapping.java | 38 ++++++++++++++++++++++
src/site/markdown/server/manage-webadmin.md | 4 +--
.../xdoc/server/config-recipientrewritetable.xml | 31 ++++++++++++++++++
3 files changed, 71 insertions(+), 2 deletions(-)
diff --git a/server/data/data-api/src/main/java/org/apache/james/rrt/lib/Mapping.java b/server/data/data-api/src/main/java/org/apache/james/rrt/lib/Mapping.java
index 80fab25..c8fc194 100644
--- a/server/data/data-api/src/main/java/org/apache/james/rrt/lib/Mapping.java
+++ b/server/data/data-api/src/main/java/org/apache/james/rrt/lib/Mapping.java
@@ -117,20 +117,58 @@ public interface Mapping {
}
enum Type {
+ /**
+ * Applies the regex on the supplied address.
+ */
Regex("regex:", new UserRewritter.RegexRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToEmpty, TypeOrder.TYPE_ORDER_4),
+ /**
+ * Rewrites the domain of mail addresses.
+ *
+ * Use it for technical purposes.
+ */
Domain("domain:", new UserRewritter.DomainRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToEmpty, TypeOrder.TYPE_ORDER_1),
+ /**
+ * Rewrites the domain of mail addresses.
+ *
+ * User will be able to use this domain as if it was the one of his mail address.
+ */
DomainAlias("domainAlias:", new UserRewritter.DomainRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToEmpty, TypeOrder.TYPE_ORDER_1),
+ /**
+ * Throws an error upon processing
+ */
Error("error:", new UserRewritter.ThrowingRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToEmpty, TypeOrder.TYPE_ORDER_4),
+ /**
+ * Replaces the source address by another one.
+ *
+ * Vehicles the intent of forwarding incoming mails to other users.
+ */
Forward("forward:", new UserRewritter.ReplaceRewriter(), IdentityMappingPolicy.ReturnIdentity,
MailAddressConversionPolicy.ToMailAddress, TypeOrder.TYPE_ORDER_3),
+ /**
+ * Replaces the source address by another one.
+ *
+ * Vehicles the intent of a group registration: group address will be swapped by group member addresses.
+ * (Feature poor mailing list)
+ */
Group("group:", new UserRewritter.ReplaceRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToMailAddress, TypeOrder.TYPE_ORDER_2),
+ /**
+ * Replaces the source address by another one.
+ *
+ * Represents user owned mail address, with which he can interact as if it was his main mail address.
+ */
Alias("alias:", new UserRewritter.ReplaceRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToMailAddress, TypeOrder.TYPE_ORDER_3),
+ /**
+ * Replaces the source address by another one.
+ *
+ * Use for technical purposes, this mapping type do not hold specific intent. Prefer using one of the above
+ * mapping types.
+ */
Address("", new UserRewritter.ReplaceRewriter(), IdentityMappingPolicy.Throw,
MailAddressConversionPolicy.ToMailAddress, TypeOrder.TYPE_ORDER_4);
diff --git a/src/site/markdown/server/manage-webadmin.md b/src/site/markdown/server/manage-webadmin.md
index 65ad585..825b8f9 100644
--- a/src/site/markdown/server/manage-webadmin.md
+++ b/src/site/markdown/server/manage-webadmin.md
@@ -40,7 +40,7 @@ Finally, please note that in case of a malformed URL the 400 bad request respons
- [Cassandra Schema upgrades](#Cassandra_Schema_upgrades)
- [Correcting ghost mailbox](#Correcting_ghost_mailbox)
- [Creating address aliases](#Creating_address_aliases)
- - [Creating address domain aliases](#Creating_address_domain_aliases)
+ - [Creating domain mappings](#Creating_domain_mappings)
- [Creating address forwards](#Creating_address_forwards)
- [Creating address group](#Creating_address_group)
- [Creating regex mapping](#Creating_regex_mapping)
@@ -1874,7 +1874,7 @@ Response codes:
- 204: OK
- 400: Alias structure or member is not valid
-## Creating address domain aliases
+## Creating domain mappings
You can use **webadmin** to define domain mappings.
diff --git a/src/site/xdoc/server/config-recipientrewritetable.xml b/src/site/xdoc/server/config-recipientrewritetable.xml
index 32e064d..829adfc 100644
--- a/src/site/xdoc/server/config-recipientrewritetable.xml
+++ b/src/site/xdoc/server/config-recipientrewritetable.xml
@@ -29,6 +29,37 @@
<p>Consult <a href="https://github.com/apache/james-project/tree/master/server/app/src/main/resources/recipientrewritetable.xml">recipientrewritetable.xml</a> in GIT to get some examples and hints.</p>
+ <subsection name="Mapping types">
+ <ul>James allow using various mapping types for better expressing the intent of your address rewritting logic:
+ <li><b>Domain mapping</b>: Rewrites the domain of mail addresses. Use it for technical purposes, user will not
+ be allowed to use the source in their FROM address headers. Domain mappings can be managed via the CLI and
+ added via <a href="webadmin.html#Creating_domain_mappings">WebAdmin</a></li>
+ <li><b>Domain aliases</b>: Rewrites the domain of mail addresses. Express the idea that both domain can be used
+ inter-changeably. User will be allowed to use the source in their FROM address headers. Domain aliases can
+ be managed via <a href="webadmin.html#Get_the_list_of_aliases_for_a_domain">WebAdmin</a></li>
+ <li><b>Forwards</b>: Replaces the source address by another one. Vehicles the intent of forwarding incoming mails
+ to other users. Listing the forward source in the forward destinations keeps a local copy. User will not be
+ allowed to use the source in their FROM address headers. Forward can
+ be managed via <a href="webadmin.html#Creating_address_forwards">WebAdmin</a></li>
+ <li><b>Groups</b>: Replaces the source address by another one. Vehicles the intent of a group registration: group
+ address will be swapped by group member addresses (Feature poor mailing list). User will not be
+ allowed to use the source in their FROM address headers. Groups can
+ be managed via <a href="webadmin.html#Creating_address_group">WebAdmin</a></li>
+ <li><b>Aliases</b>: Replaces the source address by another one. Represents user owned mail address, with which
+ he can interact as if it was his main mail address. User will be allowed to use the source in their FROM
+ address headers. Aliases can be managed via <a href="webadmin.html#Creating_address_aliases">WebAdmin</a></li>
+ <li><b>Address mappings</b>: Replaces the source address by another one. Use for technical purposes, this mapping type do
+ not hold specific intent. Prefer using one of the above mapping types... User will not be allowed to use the source
+ in their FROM address headers. Address mappings can be managed via the CLI or via
+ <a href="webadmin.html#Address_Mappings">WebAdmin</a></li>
+ <li><b>Regex mappings</b>: Applies the regex on the supplied address. User will not be allowed to use the source
+ in their FROM address headers. Regex mappings can be managed via the CLI or via
+ <a href="webadmin.html#Creating_regex_mapping">WebAdmin</a></li>
+ <li><b>Error</b>: Throws an error upon processing. User will not be allowed to use the source
+ in their FROM address headers. Errors can be managed via the CLI</li>
+ </ul>
+ </subsection>
+
<subsection name="JPA Recipient Rewrite Table">
<p>The default table for storing James' Recipient Rewrite mappings.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org