This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-commons-messaging-mail.git
The following commit(s) were added to refs/heads/master by this push:
new e3e6ab5 docs: update AGENTS.md and README.md with Jakarta/OSGi and
test details (#4)
e3e6ab5 is described below
commit e3e6ab5922797a42630a4830b46b327ecc25a1d1
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 17:58:45 2026 +0200
docs: update AGENTS.md and README.md with Jakarta/OSGi and test details (#4)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 9 +++++----
README.md | 30 ++++++++++++++++++++++--------
2 files changed, 27 insertions(+), 12 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 2bd7bf2..a3058ed 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,11 +1,11 @@
# Project overview
-Apache Sling Commons Messaging Mail is an OSGi bundle that provides a
`MailService` API for sending MIME messages over SMTPS. It exposes three public
service interfaces (`MailService`, `MessageBuilder`, `MessageIdProvider`) and
ships concrete implementations (`SimpleMailService`, `SimpleMessageBuilder`,
`SimpleMessageIdProvider`) as OSGi Declarative Services components. The bundle
depends on `sling.commons.messaging`, `sling.commons.crypto` (for password
decryption), and `sling.commons.t [...]
+Apache Sling Commons Messaging Mail is an OSGi bundle that provides a
`MailService` API for sending MIME messages over SMTPS. It exposes three public
service interfaces (`MailService`, `MessageBuilder`, `MessageIdProvider`) and
ships concrete implementations (`SimpleMailService`, `SimpleMessageBuilder`,
`SimpleMessageIdProvider`) as OSGi Declarative Services components. The bundle
depends on `sling.commons.messaging`, `sling.commons.crypto` (for password
decryption), and `sling.commons.t [...]
# Core commands
```bash
-# Build and run all checks (Checkstyle, PMD, SpotBugs) + unit tests
+# Build and run all checks (Checkstyle, PMD, SpotBugs) + unit and integration
tests
mvn clean verify
# Skip integration tests (faster local iteration)
@@ -77,11 +77,12 @@ src/
# Development patterns & constraints
-- **Java 17**, OSGi R7. All source and target set via `sling.java.version=17`.
+- **Java 17**, OSGi R7. All source and target set via `sling.java.version=17`;
CI also validates on Java 21.
- **OSGi DS annotations only** — use
`org.osgi.service.component.annotations.*`. Never use Felix SCR annotations.
- `SimpleMailService` is a **factory component** (`@Designate(factory=true)`).
Multiple instances can be registered with different SMTP servers.
- All `@Reference` fields that can change at runtime are declared `volatile`
with `DYNAMIC` policy and `GREEDY` option.
- Password stored encrypted; always decrypt via `CryptoService.decrypt()` —
never store plaintext passwords.
+- Jakarta APIs are consumed in OSGi-compatible form (`jakarta.mail-api` and
ServiceMix Activation API).
- Public API interfaces carry `@ProviderType` — do not add default methods
without a version bump.
- Nullability: annotate with `@NotNull`/`@Nullable` from
`org.jetbrains.annotations`.
- Every source file must have the Apache 2.0 license header.
`apache-rat-plugin` enforces this at build time.
@@ -101,6 +102,7 @@ src/
- Unit tests live in `src/test/java/.../mail/internal/` and are named
`*Test.java`.
- Integration tests live in `src/test/java/.../mail/it/tests/` and are named
`*IT.java`. They run inside a real OSGi framework (Apache Felix) provisioned by
Pax Exam.
- GreenMail provides a local mock SMTP server for integration tests — no
external mail server required.
+- Integration tests can also run against an external SMTP server via
`-Dsling.test.mail.smtps.server.external=true` and related `sling.test.mail.*`
system properties.
- Test resources (templates, images, encrypted password) are in
`src/test/resources/`.
- Coverage is not enforced by a specific threshold; rely on code review.
@@ -118,4 +120,3 @@ src/
<!-- sling-security-default:start -->
The threat model for this project is
https://github.com/apache/sling/blob/master/docs/threat-model.md .
<!-- sling-security-default:end -->
-
diff --git a/README.md b/README.md
index 4cd5294..64a0543 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-It provides a simple layer on top of [Jakarta
Mail](https://eclipse-ee4j.github.io/mail/) 2.0 (package `jakarta.mail`),
including:
+It provides a simple layer on top of [Jakarta
Mail](https://eclipse-ee4j.github.io/mail/) (package `jakarta.mail`) for
asynchronous SMTP-over-SSL/TLS message delivery, including:
* **Mail Service**: sends MIME messages asynchronously
(`CompletableFuture<Void>`)
* **Message Builder**: builds plain text and HTML messages with attachments
and inline images
@@ -17,7 +17,7 @@ The project is built with Java 17 and validated in CI with
Java 17 and Java 21.
## Build and Test
```bash
-# Build and run all checks (Checkstyle, PMD, SpotBugs) + unit tests
+# Build and run all checks (Checkstyle, PMD, SpotBugs) + unit and integration
tests
mvn clean verify
# Skip integration tests (faster local iteration)
@@ -34,6 +34,15 @@ mvn failsafe:integration-test failsafe:verify
# Run a single integration test class
mvn failsafe:integration-test -Dit.test=SimpleMailServiceIT
+
+# Run Checkstyle only
+mvn checkstyle:check
+
+# Run PMD only
+mvn pmd:check
+
+# Run SpotBugs only
+mvn spotbugs:check
```
## Examples
@@ -46,12 +55,17 @@ Example factory configuration
([`SimpleMailServiceConfiguration`](https://github
```
{
- "mail.smtps.from": "[email protected]",
- "mail.smtps.host": "smtp.example.org",
- "mail.smtps.port": 465,
+ "names": ["default"],
+ "threadpool_name": "default",
+ "mail_smtps_ssl_checkserveridentity": true,
+ "mail_smtps_from": "[email protected]",
+ "mail_smtps_host": "smtp.example.org",
+ "mail_smtps_port": 465,
"username": "SMTP-USERNAME-PLAIN",
"password": "SMTP-PASSWORD-ENCRYPTED",
- "messageIdProvider.target": "(names=hostname)"
+ "messageIdProvider_target": "(names=hostname)",
+ "connectionListeners_target": "(is=used)",
+ "transportListeners_target": "(is=used)"
}
```
@@ -100,8 +114,8 @@ mailService.sendMessage(message);
* [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)
(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/)
(OSGi-compatible APIs used by the bundle)
+* [Sling Commons
Threads](https://github.com/apache/sling-org-apache-sling-commons-threads)
(asynchronous dispatch)
+* [Jakarta Mail 2.0](https://jakarta.ee/specifications/mail/2.0/) and
[ServiceMix Jakarta Activation API
2.0.1](https://mvnrepository.com/artifact/org.apache.servicemix.specs/org.apache.servicemix.specs.activation-api-2.0.1)
(OSGi-compatible APIs used by the bundle)
## Integration Tests
