DRAFT: Migrating a Custom Plugin using the JavaMail library to the Jakarta Mail library

Please note that Appian 22.3+ uses the Jakarta Mail library. Appian versions prior to this use the JavaMail library.

Appian is deprecating the use of the JavaMail (javax.mail) library in Appian 22.2 for replacement with the modern Jakarta Mail (jakarta.mail) library in Appian 22.3.

The Jakarta Mail library is a set of abstract APIs that model a mail system. (Jakarta Mail was previously known as JavaMail before migration into the Apache Foundation.) The library provides a platform independent and protocol independent framework to build Java technology based email client applications.

For many of the custom plugins implementing the JavaMail library, the update to use the Jakarta Mail library requires the update of the import statements in each java class to move from the use of ‘javax.mail’ to the ‘jakarta.mail’ package and the ‘javax.activation’ to the ‘jakarta.activation’ package in order to use the new library appropriately.

Steps:

1. Open your existing plugin project in Eclipse.
   
2. Ensure the current code base compiles successfully.
   1. Right click your project and click Export….
   2. Select the JAR file option as the Export destination.
   3. On 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. (If your plugin is not importing a self-contained dependency JAR and is using a dependency inherited from the Appian product, please ensure you include the Jakarta Mail JAR within your plugin. You should always include the library that contains the classes used in your plug-in so that the plug-in uses the same version of the library regardless of which version of Appian it runs in. See: https://docs.appian.com/suite/help/latest/Custom_Plug-in_Packages.html)
      
4. Update the build path to remove the JavaMail library JAR and add the Jakarta Mail library JAR.
   1. Update your Java Build Path to include any new JAR files; otherwise, Eclipse won't compile.
   2. Right click the project and select Properties.
   3. In the Package Explorer (left navigation) click Java Build Path.
   4. On the Libraries tab, click Add JARs….
   5. Select the Jakarta Mail JAR file in your project.
   6. Select the existing JavaMail library and click Remove.
      
5. Update Java classes to use the jakarta.mail and jakarta.activation packages.
   1. The Jakarta Mail library implements the same classes as the JavaMail library because Jakarta is the updated version of this same library. As such, we need to update the classes in the project to use the ‘jakarta.mail’ package instead of the ‘javax.mail’ package and the ‘jakarta.activation’ package instead of the ‘javax.activation’ package.
   2. Example class using javax.mail:

      1. 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;

   3. Example class updated to use jakarta.mail:

      1. 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;
         
         

   4. (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 your plugin code base beyond the update of the package naming alone.)
6. Increment the plugin version in appian-plugin.xml.
   1. In order to differentiate this latest version of your plugin from the existing release that implements the JavaMail library, you should increment the version of this plugin within the appian-plugin.xml file.
      1. Example current version:
         1. <version>1.0.1</version>
      2. Example new version:
         1. <version>1.1.0</version>
   2. (As this is a change beyond a simple revision, you may wish to increment the minor or major version of the plugin.)
7. Ensure the updated code base compiles successfully.
   1. Right click your project and click Export….
   2. Select the JAR file option as the Export destination.
   3. On 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 your installation directory for your export destination. - This directory is created during application server startup.
   5. Click Finish.