You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by bt...@apache.org on 2022/05/23 02:47:37 UTC
[james-project] 08/10: JAMES-3769 Document search overrides
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 3a480ab8b386c12bba149897332fb6b873a9cd52
Author: Benoit Tellier <bt...@linagora.com>
AuthorDate: Thu May 12 13:20:36 2022 +0700
JAMES-3769 Document search overrides
---
.../sample-configuration/elasticsearch.properties | 2 +-
.../ROOT/pages/configure/elasticsearch.adoc | 28 +++++++++++++++++++++
.../sample-configuration/elasticsearch.properties | 2 +-
src/site/xdoc/server/config-elasticsearch.xml | 29 ++++++++++++++++++++++
4 files changed, 59 insertions(+), 2 deletions(-)
diff --git a/server/apps/cassandra-app/sample-configuration/elasticsearch.properties b/server/apps/cassandra-app/sample-configuration/elasticsearch.properties
index 9c2033c4fb..e21c4bae0d 100644
--- a/server/apps/cassandra-app/sample-configuration/elasticsearch.properties
+++ b/server/apps/cassandra-app/sample-configuration/elasticsearch.properties
@@ -89,7 +89,7 @@ elasticsearch.metrics.reports.index=james-metrics
#
# Possible values are:
# - `org.apache.james.mailbox.cassandra.search.AllSearchOverride` Some IMAP clients uses SEARCH ALL to fully list messages in
-# a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from am IMAP perspective
+# a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from an IMAP perspective
# is considered an optimisation as less data is transmitted compared to a FETCH command. Resolving such requests against
# Cassandra is enabled by this search override and likely desirable.
# - `org.apache.james.mailbox.cassandra.search.UidSearchOverride`. Same as above but restricted by ranges.
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/elasticsearch.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/elasticsearch.adoc
index 6d3c1fd6cb..2570351be9 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/elasticsearch.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/elasticsearch.adoc
@@ -208,3 +208,31 @@ You can configure to use which HostNameVerifier in the client.
accept_any_hostname: accept any host (not recommended).
|===
+
+== Search overrides
+
+*Search overrides* allow resolution of predefined search queries against alternative sources of data
+and allow bypassing ElasticSearch. This is useful to handle most resynchronisation queries that
+are simple enough to be resolved against Cassandra.
+
+Possible values are:
+ - `org.apache.james.mailbox.cassandra.search.AllSearchOverride` Some IMAP clients uses SEARCH ALL to fully list messages in
+ a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from an IMAP perspective
+ is considered an optimisation as less data is transmitted compared to a FETCH command. Resolving such requests against
+ Cassandra is enabled by this search override and likely desirable.
+ - `org.apache.james.mailbox.cassandra.search.UidSearchOverride`. Same as above but restricted by ranges.
+ - `org.apache.james.mailbox.cassandra.search.DeletedSearchOverride`. Find deleted messages by looking up in the relevant Cassandra
+ table.
+ - `org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride`. Same as above but limited by ranges.
+ - `org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride`. List non deleted messages in a given range.
+ Lists all messages and filters out deleted message thus this is based on the following heuristic: most messages are not marked as deleted.
+ - `org.apache.james.mailbox.cassandra.search.UnseenSearchOverride`. List unseen messages in the corresponding cassandra projection.
+
+Please note that custom overrides can be defined here. `elasticsearch.search.overrides` allow specifying search overrides and is a
+coma separated list of search override FQDNs. Default to none.
+
+EG:
+
+----
+elasticsearch.search.overrides=org.apache.james.mailbox.cassandra.search.AllSearchOverride,org.apache.james.mailbox.cassandra.search.DeletedSearchOverride, org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.UidSearchOverride,org.apache.james.mailbox.cassandra.search.UnseenSearchOverride
+----
\ No newline at end of file
diff --git a/server/apps/distributed-app/sample-configuration/elasticsearch.properties b/server/apps/distributed-app/sample-configuration/elasticsearch.properties
index 871812b8ca..99d325756c 100644
--- a/server/apps/distributed-app/sample-configuration/elasticsearch.properties
+++ b/server/apps/distributed-app/sample-configuration/elasticsearch.properties
@@ -88,7 +88,7 @@ elasticsearch.metrics.reports.index=james-metrics
#
# Possible values are:
# - `org.apache.james.mailbox.cassandra.search.AllSearchOverride` Some IMAP clients uses SEARCH ALL to fully list messages in
-# a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from am IMAP perspective
+# a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from an IMAP perspective
# is considered an optimisation as less data is transmitted compared to a FETCH command. Resolving such requests against
# Cassandra is enabled by this search override and likely desirable.
# - `org.apache.james.mailbox.cassandra.search.UidSearchOverride`. Same as above but restricted by ranges.
diff --git a/src/site/xdoc/server/config-elasticsearch.xml b/src/site/xdoc/server/config-elasticsearch.xml
index c3bd3276cd..17d232eb04 100644
--- a/src/site/xdoc/server/config-elasticsearch.xml
+++ b/src/site/xdoc/server/config-elasticsearch.xml
@@ -289,6 +289,35 @@
</dd>
</dl>
</section>
+ <section name="Search overrides">
+
+ <p><b>Search overrides</b> allow resolution of predefined search queries against alternative sources of data
+ and allow bypassing ElasticSearch. This is useful to handle most resynchronisation queries that
+ are simple enough to be resolved against Cassandra.</p>
+
+ <ul>Possible values are:<br/>
+ <li><pre>org.apache.james.mailbox.cassandra.search.AllSearchOverride</pre> Some IMAP clients uses SEARCH ALL to fully list messages in
+ a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from an IMAP perspective
+ is considered an optimisation as less data is transmitted compared to a FETCH command. Resolving such requests against
+ Cassandra is enabled by this search override and likely desirable.</li>
+ <li><pre>org.apache.james.mailbox.cassandra.search.UidSearchOverride</pre>. Same as above but restricted by ranges.</li>
+ <li><pre>org.apache.james.mailbox.cassandra.search.DeletedSearchOverride</pre>. Find deleted messages by looking up in the relevant Cassandra
+ table.</li>
+ <li><pre>org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride</pre>. Same as above but limited by ranges.
+ <li><pre>org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride</pre>. List non deleted messages in a given range.</li>
+ Lists all messages and filters out deleted message thus this is based on the following heuristic: most messages are not marked as deleted.</li>
+ <li><pre>org.apache.james.mailbox.cassandra.search.UnseenSearchOverride</pre>. List unseen messages in the corresponding cassandra projection.</li>
+ </ul>
+
+ <p>
+ Please note that custom overrides can be defined here. <pre>elasticsearch.search.overrides</pre> allow specifying search overrides and is a
+ coma separated list of search override FQDNs. Default to none.
+ </p>
+
+ <p>EG:</p>
+
+ <pre><code>elasticsearch.search.overrides=org.apache.james.mailbox.cassandra.search.AllSearchOverride,org.apache.james.mailbox.cassandra.search.DeletedSearchOverride, org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.UidSearchOverride,org.apache.james.mailbox.cassandra.search.UnseenSearchOverride</code></pre>
+ </section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org