[sling-org-apache-sling-commons-messaging-mail] 02/02: add configuration examples and dependencies

[ol...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

olli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-commons-messaging-mail.git

commit 395d16416a5a35d9e632e6b0ceaae2bc5d06872f
Author: Oliver Lietz <ol...@apache.org>
AuthorDate: Wed May 19 11:18:41 2021 +0200

    add configuration examples and dependencies
---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 45 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 89a0cb9..1b9943b 100644
--- a/README.md
+++ b/README.md
@@ -8,12 +8,47 @@ This module is part of the [Apache Sling](https://sling.apache.org) project.
 
 This module provides a simple layer on top of [Jakarta Mail](https://eclipse-ee4j.github.io/mail/) 2.0 (package `jakarta.mail`) including a message builder and a service to send mails via SMTPS.
 
-* Mail Service: sends MIME messages.
+* Mail Service: sends MIME messages
 * Message Builder: builds plain text and HTML messages with attachments and inline images 
 * Message ID Provider: allows overwriting default message IDs by custom ones
 
 
-## Example
+## Examples
+
+### Configuration
+
+
+#### MailService
+
+Example factory configuration ([`SimpleMailServiceConfiguration`](https://github.com/apache/sling-org-apache-sling-commons-messaging-mail/blob/master/src/main/java/org/apache/sling/commons/messaging/mail/internal/SimpleMailServiceConfiguration.java)) for [`SimpleMailService`](https://github.com/apache/sling-org-apache-sling-commons-messaging-mail/blob/master/src/main/java/org/apache/sling/commons/messaging/mail/internal/SimpleMailService.java):
+
+```
+{
+  "mail.smtps.from": "envelope-from@example.org",
+  "mail.smtps.host": "smtp.example.org",
+  "mail.smtps.port": 465,
+  "username": "SMTP-USERNAME-PLAIN",
+  "password": "SMTP-PASSWORD-ENCRYPTED",
+  "messageIdProvider.target": "(names=hostname)"
+}
+```
+
+#### Optional MessageIdProvider
+
+Example factory configuration ([`SimpleMessageIdProviderConfiguration`](https://github.com/apache/sling-org-apache-sling-commons-messaging-mail/blob/master/src/main/java/org/apache/sling/commons/messaging/mail/internal/SimpleMessageIdProviderConfiguration.java)) for optional [`SimpleMessageIdProvider`](https://github.com/apache/sling-org-apache-sling-commons-messaging-mail/blob/master/src/main/java/org/apache/sling/commons/messaging/mail/internal/SimpleMessageIdProvider.java):
+
+```
+{
+  "names": [
+    "hostname"
+  ],
+  "host": "author.cms.example.org"
+}
+```
+
+### Usage
+
+Create a multipart MIME message with an attachment (`filename`: `song.flac`) where the HTML part contains an inline image (`cid`: `ska`) and send it:
 
 ```
     @Reference
@@ -32,13 +67,19 @@ This module provides a simple layer on top of [Jakarta Mail](https://eclipse-ee4
         .subject(subject)
         .text(text)
         .html(html)
-        .attachment(attachment, "image/png", "attachment.png")
-        .inline(inline, "image/png", "inline")
+        .attachment(attachment, "audio/flac", "song.flac")
+        .inline(inline, "image/png", "ska")
         .build();
 
     mailService.sendMessage(message);
 ```
 
+## Dependencies
+
+* [Sling Commons Messaging](https://github.com/apache/sling-org-apache-sling-commons-messaging) (API)
+* [Sling Commons Crypto](https://github.com/apache/sling-org-apache-sling-commons-crypto) (for decrypting encrypted SMTP passwords)
+* [Sling Commons Threads](https://github.com/apache/sling-org-apache-sling-commons-threads)
+* [Jakarta Mail 2.0](https://jakarta.ee/specifications/mail/2.0/) and [Jakarta Activation 2.0](https://jakarta.ee/specifications/activation/2.0/) (*OSGified*, e.g. `org.apache.servicemix.specs.activation-api-2.0.1`)
 
 ## Integration Tests