KB-2215 How to update a custom plug-in using the JavaMail library to use the Jakarta Mail library

Purpose

In Appian 22.3, the mail library available for use in custom plug-ins has been updated from JavaMail (javax.mail) to Jakarta Mail (jakarta.mail). Custom plug-ins that reference the JavaMail library will need to be updated to use the Jakarta Mail library to continue to work in Appian 22.3.

This article outlines how to update a custom plug-in to use the Jakarta Mail library, which requires that import statements in each java class that reference the javax.mail and javax.activation packages to be updated to reference the jakarta.mail and jakarta.activation packages respectively.

Instructions - Gradle

In the project build.gradle file:

1. Ensure that any javax.mail and javax.activation dependencies are removed.
2. Add the jakarta.mail and jakarta.activation dependencies as compileOnly dependencies.

   1. dependencies {
      // .... other project dependencies ....
      
      compileOnly 'com.sun.mail:jakarta.mail:2.0.1'
      compileOnly 'com.sun.activation:jakarta.activation:2.0.1'
      
      }

Instructions - Maven

In the project pom.xml file:

1. Ensure that any javax.mail and javax.activation dependencies are removed.
2. Add the jakarta.mail and jakarta.activation dependencies as system scoped dependencies.

   1. <dependencies>
          <!-- .... other project dependencies .... -->
          <dependency>
              <groupId>com.sun.mail</groupId>
              <artifactId>jakarta.mail</artifactId>
              <version>2.0.1</version>
              <scope>system</scope>
          </dependency>
          <dependency>
              <groupId>com.sun.activation</groupId>
              <artifactId>jakarta.activation</artifactId>
              <version>2.0.1</version>
              <scope>system</scope>
          </dependency>
      </dependencies>

Instructions - Eclipse IDE

Below are example steps for updating a plug-in project in Eclipse.

1. Open the existing plug-in project in Eclipse.
   
2. Ensure the project builds successfully.
   1. Right click the project and click Export…
   2. Select the JAR file option as the Export destination.
   3. In the Resources to export dialog, clear the .classpath and .project selections as these files are used exclusively by Eclipse.
   4. Select a destination directory for the export.
   5. Click Finish.
3. Download the Jakarta Mail and Jakarta Activation JARs
   1. Download the Jakarta Mail JAR at: https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/2.0.1/jakarta.mail-2.0.1.jar
   2. Download the Jakarta Activation JAR at: https://repo1.maven.org/maven2/com/sun/activation/jakarta.activation/2.0.1/jakarta.activation-2.0.1.jar
   3. Save these JARs locally in a location outside of the plugin project for use later.
4. Remove the JavaMail dependency JAR in META-INF/lib.
   1. Delete the existing javax.mail and/or javax.activation JARs present in META-INF/lib.
5. Update the build path to remove the JavaMail library JAR
   1. Update the Java Build Path to include any new JAR files; otherwise, the project will not build.
   2. Right click the project and select Properties.
   3. In the Package Explorer (left navigation), click Java Build Path.
   4. Select the existing JavaMail libraries and click Remove.
6. Add the Jakarta JARs as external dependencies to the project
   1. Right-click the project. Click Properties.
   2. In the left navigation, select Java Build Path.
   3. Select the Libraries tab. Click the Add External JARs… button.
   4. Add the Jakarta Mail JAR as an external dependency and click OK.
      1. <LOCATION_SAVED_EARLIER>/jakarta.mail-2.0.1.jar
   5. Click the Add External JARs… button. Add the Jakarta Activation JAR as an external dependency and click OK.
      1. <LOCATION_SAVED_EARLIER>/jakarta.activation-2.0.1.jar
7. Update any Java classes that reference the javax.mail or javax.activation packages to use the jakarta.mail and jakarta.activation packages respectively. The Jakarta Mail library implements the same classes as the JavaMail library because Jakarta is the updated version of this library.
   1. Example class using javax.mail:
      

      package com.appiancorp.plugins.example.mail;
      
      
      
      import java.util.Date;
      
      import java.util.Properties;
      
      
      
      import javax.mail.Authenticator;
      
      import javax.mail.Message;
      
      import javax.mail.PasswordAuthentication;
      
      import javax.mail.Session;
      
      import javax.mail.Transport;
      
      import javax.mail.internet.InternetAddress;
      
      import javax.mail.internet.MimeMessage;
      
      
      
      import org.apache.log4j.Logger;

   2. Example class updated to use jakarta.mail:
      

      package com.appiancorp.plugins.example.mail;
      
      
      
      import java.util.Date;
      
      import java.util.Properties;
      
      
      
      import jakarta.mail.Authenticator;
      
      import jakarta.mail.Message;
      
      import jakarta.mail.PasswordAuthentication;
      
      import jakarta.mail.Session;
      
      import jakarta.mail.Transport;
      
      import jakarta.mail.internet.InternetAddress;
      
      import jakarta.mail.internet.MimeMessage;
      
      
      
      import org.apache.log4j.Logger;
      
      

   3. The updated classes and methods from the Jakarta Mail library will typically implement the same parameters and logic as the JavaMail equivalents. However, there may be some differences that will require updates to the plug-in beyond the update of the package naming alone.
8. Increment the plug-in version in appian-plugin.xml.
   1. In order to differentiate this latest version of the plug-in from the existing release that implements the JavaMail library, increment the plug-in version within appian-plugin.xml.
   2. As this is a change beyond a simple revision, the minor or major version of the plug-in can be incremented (e.g. <version>1.0.1</version> to <version>1.1.0</version>).
9. Ensure the updated plug-in builds successfully.
   1. Right click the project and click Export…
   2. Select the JAR file option as the Export destination.
   3. In the Resources to export dialog, clear the .classpath and .project selections as these files are used exclusively by Eclipse.
   4. Select the _admin/plugins folder of the installation directory for the export destination (this directory is created during application server startup).
   5. Click Finish.

Affected Versions

This article applies to Appian 22.3 and later.

Last Reviewed: September 2022