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

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. Replace the JavaMail dependency JAR with the Jakarta Mail JAR in META-INF/lib.
   1. Ensure the Jakarta Mail JAR is included within the plug-in. The library that contains the classes used in the plug-in should always be included so that the plug-in uses the same version of the library regardless of which version of Appian it runs in. See here for more details.
      
4. Update the build path to remove the JavaMail library JAR and add the Jakarta Mail 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. In the Libraries tab, click Add JARs…
   5. Select the Jakarta Mail JAR file in the project.
   6. Select the existing JavaMail library and click Remove.
      
5. 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.
6. 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>).
7. 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: May 2022