Compile with Jakarta 9 and test with Jakarta 10

Also polishes. This ensures our instrumentation is compatible with Jakarta 9 and 10.

Author: shakuzen

Diff for: gradle/libs.versions.toml

@@ -134,7 +134,6 @@ jacksonDatabind = { module = "com.fasterxml.jackson.core:jackson-databind", vers
 jakarta-annotationApi = { module = "jakarta.annotation:jakarta.annotation-api", version = "3.0.0" }
 jakarta-injectApi = { module = "jakarta.inject:jakarta.inject-api", version = "2.0.1" }
 jakarta-jmsApi = { module = "jakarta.jms:jakarta.jms-api", version = "3.0.0" }
-jakarta-mailApi = { module = "jakarta.mail:jakarta.mail-api", version = "2.1.3" }
 jakarta-servletApi = { module = "jakarta.servlet:jakarta.servlet-api", version = "5.0.0" }
 javalin = { module = "io.javalin:javalin", version = "5.6.5" }
 javax-cacheApi = { module = "javax.cache:cache-api", version.ref = "javax-cache" }

Diff for: micrometer-jakarta9/build.gradle

@@ -19,7 +19,8 @@ dependencies {
     api project(":micrometer-observation")
 
     optionalApi 'jakarta.jms:jakarta.jms-api'
-    optionalApi 'jakarta.mail:jakarta.mail-api:2.1.0'
+    // Jakarta 9 version of the Mail API
+    optionalApi 'jakarta.mail:jakarta.mail-api:2.0.1'
 
     testImplementation(libs.archunitJunit5) {
         // avoid transitively pulling in slf4j 2
@@ -29,5 +30,5 @@ dependencies {
     testImplementation libs.mockitoCore5
     testImplementation project(':micrometer-observation-test')
     testImplementation 'org.assertj:assertj-core'
-    testImplementation 'org.eclipse.angus:jakarta.mail:2.0.3'
+    testRuntimeOnly('com.sun.mail:jakarta.mail:2.0.1')
 }

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/DefaultMailSendObservationConvention.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,6 +20,8 @@
 
 /**
  * Default implementation for {@link MailSendObservationConvention}.
+ *
+ * @since 1.15.0
  */
 public class DefaultMailSendObservationConvention implements MailSendObservationConvention {
 

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/InstrumentedTransport.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,23 +16,26 @@
 package io.micrometer.jakarta9.instrument.mail;
 
 import io.micrometer.common.lang.Nullable;
-import io.micrometer.common.util.internal.logging.InternalLogger;
-import io.micrometer.common.util.internal.logging.InternalLoggerFactory;
 import io.micrometer.observation.Observation;
 import io.micrometer.observation.ObservationConvention;
 import io.micrometer.observation.ObservationRegistry;
 import jakarta.mail.*;
 
+/**
+ * Wraps a {@link Transport} so that it is instrumented with a Micrometer
+ * {@link Observation}.
+ *
+ * @since 1.15.0
+ */
 public class InstrumentedTransport extends Transport {
 
-    private static final InternalLogger LOGGER = InternalLoggerFactory.getInstance(InstrumentedTransport.class);
+    private static final DefaultMailSendObservationConvention DEFAULT_CONVENTION = new DefaultMailSendObservationConvention();
 
-    private static final ObservationConvention<MailSendObservationContext> DEFAULT_CONVENTION = new DefaultMailSendObservationConvention();
-
-    private ObservationRegistry observationRegistry;
+    private final ObservationRegistry observationRegistry;
 
     private final Transport delegate;
 
+    @Nullable
     private final String protocol;
 
     @Nullable
@@ -43,14 +46,27 @@ public class InstrumentedTransport extends Transport {
 
     private int port;
 
-    public InstrumentedTransport(Session session, Transport delegate, ObservationRegistry observationRegistry)
-            throws NoSuchProviderException {
+    /**
+     * Create an instrumented transport using the
+     * {@link DefaultMailSendObservationConvention default} {@link ObservationConvention}.
+     * @param session session for the delegate transport
+     * @param delegate transport to instrument
+     * @param observationRegistry registry for the observations
+     */
+    public InstrumentedTransport(Session session, Transport delegate, ObservationRegistry observationRegistry) {
         this(session, delegate, observationRegistry, null);
     }
 
+    /**
+     * Create an instrumented transport with a custom {@link MailSendObservationConvention
+     * convention}.
+     * @param session session for the delegate transport
+     * @param delegate transport to instrument
+     * @param observationRegistry registry for the observations
+     * @param customConvention override the convention to apply to the instrumentation
+     */
     public InstrumentedTransport(Session session, Transport delegate, ObservationRegistry observationRegistry,
-            @Nullable ObservationConvention<MailSendObservationContext> customConvention)
-            throws NoSuchProviderException {
+            @Nullable ObservationConvention<MailSendObservationContext> customConvention) {
         super(session, delegate.getURLName());
         this.protocol = this.url.getProtocol();
         this.delegate = delegate;
@@ -73,7 +89,7 @@ public void sendMessage(Message msg, Address[] addresses) throws MessagingExcept
                 observationRegistry);
 
         observation.start();
-        try (Observation.Scope scope = observation.openScope()) {
+        try (Observation.Scope ignore = observation.openScope()) {
             // the Message-Id is set by the SMTP after sending the message
             this.delegate.sendMessage(msg, addresses);
             observation.highCardinalityKeyValue(MailKeyValues.smtpMessageId(msg));

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/MailKeyValues.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@
 import jakarta.mail.MessagingException;
 import jakarta.mail.Message.RecipientType;
 
-public class MailKeyValues {
+class MailKeyValues {
 
     private static final KeyValue SMTP_MESSAGE_FROM_UNKNOWN = KeyValue
         .of(MailObservationDocumentation.HighCardinalityKeyNames.SMTP_MESSAGE_FROM, "unknown");
@@ -106,13 +106,17 @@ static KeyValue smtpMessageId(Message message) {
     }
 
     static KeyValue serverAddress(MailSendObservationContext context) {
-        return KeyValue.of(LowCardinalityKeyNames.SERVER_ADDRESS,
-                context.getHost() == null ? "unknown" : context.getHost());
+        if (context.getHost() == null) {
+            return SERVER_ADDRESS_UNKNOWN;
+        }
+        return KeyValue.of(LowCardinalityKeyNames.SERVER_ADDRESS, context.getHost());
     }
 
     static KeyValue serverPort(MailSendObservationContext context) {
-        return KeyValue.of(LowCardinalityKeyNames.SERVER_PORT,
-                context.getPort() > 0 ? String.valueOf(context.getPort()) : "unknown");
+        if (context.getPort() <= 0) {
+            return SERVER_PORT_UNKNOWN;
+        }
+        return KeyValue.of(LowCardinalityKeyNames.SERVER_PORT, String.valueOf(context.getPort()));
     }
 
     static KeyValue networkProtocolName(MailSendObservationContext context) {

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/MailObservationDocumentation.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,6 +23,8 @@
 /**
  * Documented {@link io.micrometer.common.KeyValue KeyValues} for the observations on
  * {@link jakarta.mail.Transport send} of mail messages.
+ *
+ * @since 1.15.0
  */
 public enum MailObservationDocumentation implements ObservationDocumentation {
 

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/MailSendObservationContext.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,21 +25,24 @@
  * Context that holds information for observation metadata collection during the
  * {@link MailObservationDocumentation#MAIL_SEND sending of mail messages}.
  * <p>
- * This propagates the tracing information with the message sent by
+ * This propagates metadata with the message sent by
  * {@link Message#setHeader(String, String) setting a message header}.
+ *
+ * @since 1.15.0
  */
 public class MailSendObservationContext extends SenderContext<Message> {
 
     private static final WarnThenDebugLogger logger = new WarnThenDebugLogger(MailSendObservationContext.class);
 
+    @Nullable
     private final String protocol;
 
     @Nullable
     private final String host;
 
     private final int port;
 
-    public MailSendObservationContext(Message msg, String protocol, @Nullable String host, int port) {
+    public MailSendObservationContext(Message msg, @Nullable String protocol, @Nullable String host, int port) {
         super((message, key, value) -> {
             if (message != null) {
                 try {
@@ -56,6 +59,7 @@ public MailSendObservationContext(Message msg, String protocol, @Nullable String
         this.port = port;
     }
 
+    @Nullable
     public String getProtocol() {
         return protocol;
     }

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/MailSendObservationConvention.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,6 +21,8 @@
 /**
  * {@link ObservationConvention} interface for
  * {@link MailObservationDocumentation#MAIL_SEND mail send} operations.
+ *
+ * @since 1.15.0
  */
 public interface MailSendObservationConvention extends ObservationConvention<MailSendObservationContext> {
 

Diff for: micrometer-jakarta9/src/main/java/io/micrometer/jakarta9/instrument/mail/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,6 +16,8 @@
 
 /**
  * Observation instrumentation for Jakarta Mail.
+ *
+ * @since 1.15.0
  */
 @NonNullFields
 @NonNullApi

Diff for: micrometer-jakarta9/src/test/java/io/micrometer/jakarta9/instrument/mail/DefaultMailSendObservationConventionTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

Diff for: micrometer-jakarta9/src/test/java/io/micrometer/jakarta9/instrument/mail/InstrumentedTransportTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -27,63 +27,54 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mockito;
 
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
+/**
+ * Tests for {@link InstrumentedTransport}.
+ */
 class InstrumentedTransportTest {
 
-    private Session session;
+    Session session;
 
-    private MockSMTPTransportListener listener;
+    MockSMTPTransportListener listener = Mockito.mock(MockSMTPTransportListener.class);
 
-    private TestObservationRegistry registry;
+    TestObservationRegistry registry = TestObservationRegistry.create();
 
-    @BeforeEach
-    void setUp() {
-        this.listener = Mockito.mock(MockSMTPTransportListener.class);
-        registry = TestObservationRegistry.create();
+    Transport transport;
 
+    @BeforeEach
+    void setUp() throws NoSuchProviderException {
         // prepare properties for the session
         Properties smtpProperties = new Properties();
         // default use of mock to simplify test
         smtpProperties.put("mail.transport.protocol", "mocksmtp");
 
-        // listen the mock
+        // avoid NPE
         MockSMTPTransport.LISTENER = listener;
 
-        // the class have to open a Session
+        // open a Session
         this.session = Session.getInstance(smtpProperties);
-    }
-
-    @DisplayName("Test mock SMTP transport setup.")
-    @Test
-    void shouldConstructDelegatedTransport() throws NoSuchProviderException {
-        Transport transport = this.session.getTransport("mocksmtp");
-        assertThat(transport).isInstanceOf(MockSMTPTransport.class);
-        verify(listener).onConstructor(this.session, new URLName("mocksmtp:"));
+        transport = new InstrumentedTransport(session, this.session.getTransport("mocksmtp"), this.registry);
     }
 
     @Test
     void shouldDelegateConnect() throws MessagingException {
-        Transport transport = new InstrumentedTransport(session, this.session.getTransport("mocksmtp"), this.registry);
         transport.connect("host", 123, "user", "password");
         verify(listener).onConnect("host", 123, "user", "password");
     }
 
     @Test
     void shouldDelegateClose() throws MessagingException {
-        Transport transport = new InstrumentedTransport(session, this.session.getTransport("mocksmtp"), this.registry);
         transport.close();
         verify(listener).onClose();
     }
 
     @Test
     void shouldDelegateSendMessageEvenIfObservationRegistryIsNotInstalled() throws MessagingException {
-        Transport transport = new InstrumentedTransport(session, this.session.getTransport("mocksmtp"), this.registry);
         Message msg = new MimeMessage(this.session);
         Address[] to = new Address[0];
         transport.sendMessage(msg, to);
@@ -92,7 +83,6 @@ void shouldDelegateSendMessageEvenIfObservationRegistryIsNotInstalled() throws M
 
     @Test
     void shouldDelegateSendMessageIfObservationRegistryIsInstalled() throws MessagingException {
-        Transport transport = new InstrumentedTransport(session, this.session.getTransport("mocksmtp"), this.registry);
         Message msg = new MimeMessage(this.session);
         Address[] to = new Address[0];
         transport.sendMessage(msg, to);
@@ -107,7 +97,6 @@ void shouldCreateObservationWhenSendMessageIsCalled() throws MessagingException
             message.setHeader("Message-Id", "message-id");
             return true;
         });
-        Transport transport = new InstrumentedTransport(session, this.session.getTransport("mocksmtp"), this.registry);
         Message msg = new MimeMessage(this.session);
         msg.setSubject("Hello world");
         Address[] to = new Address[0];
@@ -119,17 +108,17 @@ void shouldCreateObservationWhenSendMessageIsCalled() throws MessagingException
         transport.sendMessage(msg, to);
 
         // assert
-        assertThat(registry).hasAnObservation(observationContextAssert -> {
-            observationContextAssert.hasNameEqualTo("mail.send");
-            observationContextAssert.hasHighCardinalityKeyValue("smtp.message.id", "message-id");
-            observationContextAssert.hasHighCardinalityKeyValue("smtp.message.subject", "Hello world");
-            observationContextAssert.hasHighCardinalityKeyValue("smtp.message.to", "[email protected]");
-            observationContextAssert.hasHighCardinalityKeyValue("smtp.message.from", "[email protected]");
-
-            observationContextAssert.hasLowCardinalityKeyValue("server.address", "example.com");
-            observationContextAssert.hasLowCardinalityKeyValue("server.port", "123");
-            observationContextAssert.hasLowCardinalityKeyValue("network.protocol.name", "mocksmtp");
-        });
+        assertThat(registry).hasObservationWithNameEqualTo("mail.send")
+            .that()
+            .hasBeenStarted()
+            .hasBeenStopped()
+            .hasHighCardinalityKeyValue("smtp.message.id", "message-id")
+            .hasHighCardinalityKeyValue("smtp.message.subject", "Hello world")
+            .hasHighCardinalityKeyValue("smtp.message.to", "[email protected]")
+            .hasHighCardinalityKeyValue("smtp.message.from", "from@example.com")
+            .hasLowCardinalityKeyValue("server.address", "example.com")
+            .hasLowCardinalityKeyValue("server.port", "123")
+            .hasLowCardinalityKeyValue("network.protocol.name", "mocksmtp");
     }
 
 }

Diff for: micrometer-jakarta9/src/test/java/io/micrometer/jakarta9/instrument/mail/MailObservationDocumentationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2023 VMware, Inc.
+ * Copyright 2025 VMware, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.