Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

Use the JavaMail API to Build an IMAP Custom Tag

Use the JavaMail API to Build an IMAP Custom Tag

Don't reinvent the wheel." We've all heard, and perhaps uttered, this maxim many times during our programming careers. ColdFusion MX has introduced new features to help CF developers avoid reinventing the wheel, including tag-based user-defined functions (UDFs) and ColdFusion components (CFCs).

As more CF developers begin to use these features, more code will be available for other developers to download and use. However, code reuse in ColdFusion is not limited to ColdFusion code. Integrating with Java is easier than ever with MX. Since the developer base for Java is large and it has been around much longer than ColdFusion UDFs and CFCs, there is a lot of code already out there that CF developers can use. I discovered this firsthand on a recent project when I didn't think about using existing Java libraries before starting down another path.

This project required me to programmatically access e-mail messages in a subfolder of an e-mail inbox. I couldn't use the CFPOP tag to do this because the protocol implemented by CFPOP - the "Post Office Protocol" - is designed to allow users to download messages from the "inbox" folder only. Another protocol is required to access subfolders - the Internet Message Access Protocol (IMAP).

After discovering that I needed to use IMAP to accomplish my task, I looked for a way to use it with ColdFusion. Unfortunately, since there is no built-in ColdFusion tag that implements IMAP, and I had been looking for an excuse to play around with Java, my first reaction was "Cool! I'll write my own!"

I learned a few IMAP commands and started playing around with the low-level Java networking libraries. Two days and many lines of code later, I had written a marginal IMAP client. Although it mostly worked, it still needed additional functionality and I wasn't at all confident in its stability. I knew there had to be a better way.

JavaMail API
Fortunately, I discovered that there is a much better way - use the JavaMail API. According to Sun's JavaMail Web site (http://java.sun.com/products/javamail), this API "provides a set of abstract classes that model a mail system" including support for IMAP - the same functionality (plus a lot more) that I had been struggling with for two days. Best of all, since it's included in the J2EE platform, on which ColdFusion MX is built, I didn't have to download anything or make any configuration changes to use it. This was the option I should have considered from the start.

Design Goals
Now that I had found a library, I wanted to make it simple to use from ColdFusion. Since I was already comfortable using the CFPOP tag, I decided to encapsulate some of JavaMail's functionality into a custom tag that, as much as possible, provides the same interface as CFPOP. The tag's full code is shown in the code listing. Listing 1 shows the functions that interact with the API.

Listing 2 shows the tag's main logic. For the sake of brevity, the code shown in the listing includes only one of the actions provided by CFPOP's interface - the "GETHEADERONLY" action. This excludes the "GETALL" action, which provides the ability to view a message's contents and attachments, and the "DELETE" action.

The Code
The JavaMail API consists of a bunch of classes that model a mail system. The highest-level class is the "Session" class. The session class allows you to specify properties like "port" and "timeout." To specify properties, first create and set a "Properties" object. The following sets the protocol to IMAP and the port to 143:

obj_Properties =
createObject("Java",
"java.util.Properties");
obj_Properties.init();
obj_Properties.put(
"mail.store.protocol",
"imap");
obj_Properties.put(
"mail.imap.port",
"143");

Now create the session object and pass in the properties object:

cls_Session =
createObject("Java",
"javax.mail.Session");
obj_Session =
cls_Session.getInstance(
obj_Properties);

The session class also provides a method for getting the "store." The store class abstracts the underlying protocol (in this case IMAP) and provides methods for logging into the mailbox.

obj_Store = createObject("Java",
"javax.mail.Store");
obj_Store =
obj_Session.getStore();
obj_Store.connect(
"my_mailserver",
"my_username",
"my_password");

Now you are ready to start accessing folders. The only folder that you can access using POP is the "inbox" folder. With IMAP, you can access subfolders below the inbox. The following code accesses and opens the folder "test," which is a subfolder of "inbox":

obj_Folder =
obj_Store.getFolder("inbox/test");
obj_Folder.open(
obj_Folder.READ_ONLY);

Note that this code opens the folder with read permissions only. This is a good idea if you only want to browse the contents of the folder. If you want to delete, move, or update messages, open the folder with read and write permissions:

obj_Folder.open(
obj_Folder.READ_WRITE);

The next step is to get a list of messages in the folder. With the JavaMail API, this is done by retrieving an array of "Message" objects.

ar_Messages =
obj_Folder.getMessages();

This code returns all messages in the folder. If you only need a subset of the messages, you must pass an array of message numbers to the "getMessages" function. Because I modeled my IMAP tag after the CFPOP tag, I wanted to allow the user to pass a list of message numbers to the tag. This discrepancy was easily remedied by using the built-in "ListToArray" ColdFusion function.

ar_Messages =
obj_Folder.getMessages(
ListToArray("1,2"));

Once you have the messages, you are ready to read the message headers using methods of the "Message" object. The following shows how to access the "subject" and "to addresses" of the first message in the folder (which is located at position 1 of the messages array):

// Get the received date
str_Subject =
ar_Messages[1].getSubject();

// Get the to addresses
cls_RecipientType =
CreateObject("Java",
"javax.mail.Message$RecipientType");
ar_To =
ar_Messages[1].getRecipients(
cls_RecipientType.TO);
lst_ToAddresses =
arrayToList(ar_To);

Note that the "getRecipients" method of the "Message" object returns an array of addresses since an e-mail message can be addressed to more than one person. This is also true when getting the "from", "reply-to", "CC", and "BCC" addresses. Also note the dollar sign ($) syntax used to invoke the "RecipientType" class. RecipientType is an "inner class" of the "Message" class. Although you can access inner classes in Java code by using dot notation (e.g., "Message.RecipientType"), this doesn't work in ColdFusion code.

Now that you have read the messages, the next step is to delete the unwanted ones. To do this, you set the "deleted" flag of the message and then call the folder object's "expunge" method:

cls_Flag =
CreateObject("Java",
"javax.mail.Flags$Flag");
ar_Messages[1].setFlag(
cls_Flag.DELETED,
true);
arguments.obj_Folder.expunge();

Where to Go from Here
The code presented here only scratches the surface of the functionality provided by IMAP. Most obviously, it lacks the ability to read message contents and attachments. Another useful feature would allow users to retrieve a listing of subfolders. If you are interested in adding these or other features, check out the JavaMail tutorial at http://developer.java.sun.com/developer/ onlineTraining/JavaMail/contents.html and the API specification at http://java.sun.com/products/ javamail/1.3/docs/javadocs/index.html.

Summary
With the release of MX, ColdFusion developers have more options for code reuse, including native access to a wide array of predeveloped Java software. Sometimes, especially for developers who don't have extensive Java experience, using existing Java libraries is not always the most obvious option. However, in ColdFusion MX, it can be a very worthwhile option to consider. It certainly is one that I strongly recommend the next time you start a project and think "Cool, I'll just write it myself..."

More Stories By Christian Thompson

Christian Thompson is a certified advanced Macromedia ColdFusion MX developer. He is a senior software engineer for Inserso, a technology consulting firm headquartered in Annandale, VA, where he has specialized in ColdFusion application development for over two years.

Comments (4) View Comments

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


Most Recent Comments
Christian Thompson 05/27/03 10:53:00 AM EDT

As it is, the tag does not allow you to connect with NNTP servers. With a little configuration (getting and setting up an NNTP provider), though, JavaMail does. Once you got this set up, you would have create a tag similar to CF_IMAP that performs the necessary actions. I have included a link that talks a little about accessing NNTP servers with JavaMail.

Craig Rosenblum 05/26/03 11:17:00 PM EDT

Does this allow us to do nntp reading and posting?

Christian Thompson 05/12/03 02:25:00 PM EDT

According to the documentation, BlueDragon's CFIMAP implements the following actions: list folders, list messages, mark message as read, delete message, move message, delete folder, and move folder. Since the tag presented in this article currently only lists messages, you would need to add the rest of the functions. The good news is that they are all implemented in JavaMail. You would just need to write the CF code to call the functions.

Abraham 05/08/03 12:24:00 PM EDT

Nice article.

I'm planning to write a email app and want IMAP support.

I've been playing with BlueDragon lately, which offers a tag called CFIMAP. Would it take much extra code to get the same functionality?

@ThingsExpo Stories
The 21st International Cloud Expo has announced that its Call for Papers is open. Cloud Expo, to be held October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA, brings together Cloud Computing, Big Data, Internet of Things, DevOps, Digital Transformation, Machine Learning and WebRTC to one location. With cloud computing driving a higher percentage of enterprise IT budgets every year, it becomes increasingly important to plant your flag in this fast-expanding busin...
SYS-CON Events announced today that Hitachi Data Systems, a wholly owned subsidiary of Hitachi LTD., will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City. Hitachi Data Systems (HDS) will be featuring the Hitachi Content Platform (HCP) portfolio. This is the industry’s only offering that allows organizations to bring together object storage, file sync and share, cloud storage gateways, and sophisticated search and...
SYS-CON Events announced today that delaPlex will exhibit at SYS-CON's @CloudExpo, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. delaPlex pioneered Software Development as a Service (SDaaS), which provides scalable resources to build, test, and deploy software. It’s a fast and more reliable way to develop a new product or expand your in-house team.
SYS-CON Events announced today that Progress, a global leader in application development, has been named “Bronze Sponsor” of SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Enterprises today are rapidly adopting the cloud, while continuing to retain business-critical/sensitive data inside the firewall. This is creating two separate data silos – one inside the firewall and the other outside the firewall. Cloud ISVs oft...
SYS-CON Events announced today that Peak 10, Inc., a national IT infrastructure and cloud services provider, will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Peak 10 provides reliable, tailored data center and network services, cloud and managed services. Its solutions are designed to scale and adapt to customers’ changing business needs, enabling them to lower costs, improve performance and focus intern...
SYS-CON Events announced today that Cloud Academy will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Cloud Academy is the industry’s most innovative, vendor-neutral cloud technology training platform. Cloud Academy provides continuous learning solutions for individuals and enterprise teams for Amazon Web Services, Microsoft Azure, Google Cloud Platform, and the most popular cloud computing technologies. Ge...
Existing Big Data solutions are mainly focused on the discovery and analysis of data. The solutions are scalable and highly available but tedious when swapping in and swapping out occurs in disarray and thrashing takes place. The resolution for thrashing through machine learning algorithms and support nomenclature is through simple techniques. Organizations that have been collecting large customer data are increasingly seeing the need to use the data for swapping in and out and thrashing occurs ...
SYS-CON Events announced today that Interoute has been named “Bronze Sponsor” of SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Interoute is the owner operator of Europe's largest network and a global cloud services platform, which encompasses over 70,000 km of lit fiber, 15 data centers, 17 virtual data centers and 33 colocation centers, with connections to 195 additional partner data centers. Our full-service Unifie...
SYS-CON Events announced today that Fusion, a leading provider of cloud services, will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Fusion, a leading provider of integrated cloud solutions to small, medium and large businesses, is the industry’s single source for the cloud. Fusion’s advanced, proprietary cloud service platform enables the integration of leading edge solutions in the cloud, including cloud...
DevOps is often described as a combination of technology and culture. Without both, DevOps isn't complete. However, applying the culture to outdated technology is a recipe for disaster; as response times grow and connections between teams are delayed by technology, the culture will die. A Nutanix Enterprise Cloud has many benefits that provide the needed base for a true DevOps paradigm.
SYS-CON Events announced today that WineSOFT will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Based in Seoul and Irvine, WineSOFT is an innovative software house focusing on internet infrastructure solutions. The venture started as a bootstrap start-up in 2010 by focusing on making the internet faster and more powerful. WineSOFT’s knowledge is based on the expertise of TCP/IP, VPN, SSL, peer-to-peer, mob...
SYS-CON Events announced today that DivvyCloud will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. DivvyCloud software enables organizations to achieve their cloud computing goals by simplifying and automating security, compliance and cost optimization of public and private cloud infrastructure. Using DivvyCloud, customers can leverage programmatic Bots to identify and remediate common cloud problems in rea...
Detecting internal user threats in the Big Data eco-system is challenging and cumbersome. Many organizations monitor internal usage of the Big Data eco-system using a set of alerts. This is not a scalable process given the increase in the number of alerts with the accelerating growth in data volume and user base. Organizations are increasingly leveraging machine learning to monitor only those data elements that are sensitive and critical, autonomously establish monitoring policies, and to detect...
SYS-CON Events announced today that HTBase will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. HTBase (Gartner 2016 Cool Vendor) delivers a Composable IT infrastructure solution architected for agility and increased efficiency. It turns compute, storage, and fabric into fluid pools of resources that are easily composed and re-composed to meet each application’s needs. With HTBase, companies can quickly prov...
SYS-CON Events announced today that Linux Academy, the foremost online Linux and cloud training platform and community, will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Linux Academy was founded on the belief that providing high-quality, in-depth training should be available at an affordable price. Industry leaders in quality training, provided services, and student certification passes, its goal is to c...
SYS-CON Events announced today that Systena America will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Systena Group has been in business for various software development and verification in Japan, US, ASEAN, and China by utilizing the knowledge we gained from all types of device development for various industries including smartphones (Android/iOS), wireless communication, security technology and IoT serv...
SYS-CON Events announced today that CollabNet, a global leader in enterprise software development, release automation and DevOps solutions, will be a Bronze Sponsor of SYS-CON's 20th International Cloud Expo®, taking place from June 6-8, 2017, at the Javits Center in New York City, NY. CollabNet offers a broad range of solutions with the mission of helping modern organizations deliver quality software at speed. The company’s latest innovation, the DevOps Lifecycle Manager (DLM), supports Value S...
SYS-CON Events announced today that Infranics will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Since 2000, Infranics has developed SysMaster Suite, which is required for the stable and efficient management of ICT infrastructure. The ICT management solution developed and provided by Infranics continues to add intelligence to the ICT infrastructure through the IMC (Infra Management Cycle) based on mathemat...
SYS-CON Events announced today that SoftLayer, an IBM Company, has been named “Gold Sponsor” of SYS-CON's 18th Cloud Expo, which will take place on June 7-9, 2016, at the Javits Center in New York, New York. SoftLayer, an IBM Company, provides cloud infrastructure as a service from a growing number of data centers and network points of presence around the world. SoftLayer’s customers range from Web startups to global enterprises.
SYS-CON Events announced today that Loom Systems will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Founded in 2015, Loom Systems delivers an advanced AI solution to predict and prevent problems in the digital business. Loom stands alone in the industry as an AI analysis platform requiring no prior math knowledge from operators, leveraging the existing staff to succeed in the digital era. With offices in S...