David Wallace Croft
Senior Intelligent Systems Engineer
Special Projects Division, Information Technology
Analytic Services, Inc. (ANSER)
croftd@nexos.anser.org
1998-01-25
The JavaMail API is currently in flux. Recent additions and changes have been made as recently as less than 3 weeks ago.
Discrepancies exist between the specification, javadocs, and implementation classes. You may have to regenerate the javadocs or use the javap utility.
The provided implementations in the beta from Sun currently only support SMTP (with MIME) and IMAP. NNTP and POP3 are not provided at this time to the best of my knowledge.
Many of the classes in the javax.mail.* hierarchy are redundant to classes that will become a standard part of the Java 1.2 core API. There will then be package name shifts and, most likely, incompatible changes.
Some of the functionality relies upon another emerging API, the JavaBeans Activation Framework. These classes are currently included with the beta JavaMail implementation for your convenience.
The JavaMail API allows you to instantly add the ability to manipulate e-mail and newsgroup messages to your Java applications with negligible programming effort.
The API allows for complete and correct (debugged) underlying implementations for all of the detailed multiple standards that govern these operations. Specifically, this includes Internet standards embodied in the numerous RFCs (Requests For Comments) and the interfaces to various proprietary mailing systems.
The API allows for hands-off extensibility. As new MIME-types and standards emerge, your applications will not break as this is abstracted away by the layering of the API over the implementation.
You no longer have to write your own classes for these functions and ship them with your application to the customer.
You no longer have to learn yet another unique third-party or in-house class library for dealing with e-mail or newsgroups.
Having recently written my own Java classes for e-mail and newsgroup manipulation, I can appreciate these points.
| The JavaMail API represents a standardized, extensible platform for communicating, presenting, and manipulating all current and future Multimedia Internet Mail Extension (MIME) types. |
A brief description of the key classes is presented. Relative to the number of new classes in the JavaMail API, this is a small sampling.
An abstract class encompassing the commonalities of all messages such as a sender and recipients.
Non-standard message meta-information (headers) can be added using name-value pairs.
Messages are lightweight: they are "filled on demand" whenever the access methods (getter and setter) are called.
Your standard Internet message with support for inserting an unlimited number of multiple MIME body part attachments.
Ready to use.
An abstract class which allows you to manipulate hierarchial stores of varying implementations using a layered approach.
Flags for common "folder" status information such as newsgroup subscription options and new message count.
Folders can contain Messages and sub-Folders.
Folders can be created, deleted, expunged, etc., etc.
Event listeners can detect changes such as the arrival of new mail.
An abstract class representing an object database of Messages.
Includes methods to open and close connections to the Store.
Store event listeners can be added and removed.
A final class which defines a connection to a Store.
Includes authentication options.
An abstract class with information and functionality for the protocol used by a Session connection to a Store.
Examples: SMTP, IMAP, NNTP, POP3, etc.
Extensible with the installation of new classes.
Allows for fallback to default protocol implementations.
Events inform listeners of failures and successes such as disconnections.
Allows for boolean criteria search on major fields such as message subject, addresses, dates, body text, etc.
Search field classes extend the SearchTerm class and are used with common AND, OR, and NOT classes through interface methods.
Specific implementations can provide for a variety of optimized search and match algorithms.
Store and Search may have other applications outside of manipulating messages. Example: running queries against a search engine.
The JavaBeans Activation Framework (JAF) is an emerging standard for runtime extensibility.
It allows a client to determine at runtime how a content type can be manipulated by the user (edit, view, print, etc.).
Associates with each MIME type a customized JavaBean that uses the JAF DataHandler class.
As new MIME types for video, audio, images, and 3D worlds emerge, the user will be able to use his old mail browser to view and interact with them by the simple installation of a new Bean.
The available Beans are currently limited: text and images. A likely near-term future candidate is a Bean for text/html. Other implementations will be provided by third-party vendors or will need to be created by the developer.
Access to mail and newsgroup servers can be controlled by a username and password authentication process. Once the user is verified, all user applications in the same virtual machine can automatically become recognized at the option of the developer.
A future version of the JavaMail API will provide support for digitally signed and encrypted messages.
Security features will rely heavily upon Java 1.2 security features.
The JavaMail API comes with the source code for numerous examples.
Here is another example, fairly simple, for you that has been sucessfully compiled and tested.
package ORG.anser.it.spd.croft.net.mail;
import java.util.Properties;
import javax.mail.*;
import javax.mail.internet.*;
/*********************************************************************
* <P>
* Relies upon the JavaMail API.
* <P>
* @author
* <A HREF="http://www.alumni.caltech.edu/~croft">David W. Croft</A>
* @version
* 1998-01-20
*********************************************************************/
public final class SMTPMail {
//////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////
public static final String TEST_HOST = "nexos.anser.org";
public static final String TEST_FROM = "croftd@nexos.anser.org";
public static final String TEST_TO = "croftd@nexos.anser.org";
public static final String TEST_SUBJECT = "SMTPMail Test";
public static final String TEST_MESSAGE = "This is a test.";
//////////////////////////////////////////////////////////////////////
/*********************************************************************
* Command line arguments: host, from, to, subject, message.
* Will use TEST constants if arguments are not provided.
*********************************************************************/
public static final void main ( String [ ] args )
throws AddressException, MessagingException
//////////////////////////////////////////////////////////////////////
{
String host = ( args.length < 1 ? TEST_HOST : args [ 0 ] );
String from = ( args.length < 2 ? TEST_FROM : args [ 1 ] );
String to = ( args.length < 3 ? TEST_TO : args [ 2 ] );
String subject = ( args.length < 4 ? TEST_SUBJECT : args [ 3 ] );
String message = ( args.length < 5 ? TEST_MESSAGE : args [ 4 ] );
send ( host, from, to, subject, message );
}
public static void send (
String mail_server_host,
String email_from,
String email_to,
String subject,
String message )
throws AddressException, MessagingException
//////////////////////////////////////////////////////////////////////
{
send (
mail_server_host,
( Authenticator ) null,
new InternetAddress [ ] { new InternetAddress ( email_from ) },
new InternetAddress [ ] { new InternetAddress ( email_to ) },
( InternetAddress [ ] ) null,
( InternetAddress [ ] ) null,
subject,
message );
}
public static void send (
String mail_server_host,
Authenticator authenticator,
InternetAddress [ ] addresses_from,
InternetAddress [ ] addresses_to,
InternetAddress [ ] addresses_cc,
InternetAddress [ ] addresses_bcc,
String subject,
String message )
throws MessagingException
//////////////////////////////////////////////////////////////////////
{
Properties properties = new Properties ( );
properties.put ( "mail.smtp.host", mail_server_host );
MimeMessage msg = new MimeMessage (
Session.getInstance ( properties, authenticator ) );
msg.addFrom ( addresses_from );
msg.setRecipients ( Message.RecipientType.TO , addresses_to );
msg.setRecipients ( Message.RecipientType.CC , addresses_cc );
msg.setRecipients ( Message.RecipientType.BCC, addresses_bcc );
msg.setSubject ( subject );
msg.setText ( message );
Transport.send ( msg );
}
private SMTPMail ( ) { }
//////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////
}
This is an example of what is received. Depending on the mail reader client used, the user may not see all of this.
Received: from nexos (nexos.anser.org [199.75.44.25])
by access2.mountain.net (8.8.7/8.8.5) with SMTP id CAA11302
for ; Tue, 20 Jan 1998 02:47:24 -0500 (EST)
From: croftd@nexos.anser.org
Received: from croft.mountain.net by nexos (SMI-8.6/SMI-SVR4)
id CAA08015; Tue, 20 Jan 1998 02:49:15 -0500
Date: Tue, 20 Jan 1998 02:49:15 -0500
Message-Id: <199801200749.CAA08015@nexos>
To: croftd@nexos.anser.org
Subject: SMTPMail Test
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
X-UIDL: 2f7efb090bea9661a7358ce162bffe15
X-Mozilla-Status: 8001
This is a test.
An extended example of how to attach an HTML web page to an e-mail message is also available.
JavaMail
The home for the specification (86 pages of clear,
concise, must-read material), a downloadable implementation,
and the API javadoc.
JavaBeans Activation Framework
JAF (project name Glasgow) is currently in development.
SMTPMail.java
A compiled and tested class which can send e-mail messages with
web page attachments.
http://www.alumni.caltech.edu/~croft/research/java/mail/
David Wallace Croft,
croftd@nexos.anser.org
© 1998 Analytic Services, Inc. (ANSER)
Posted 1998-01-20.