Java Mail API: Getting Started - Java Mail: Understanding the API
(Page 3 of 4 )
Any API can be divided into two categories: core and advanced. The Java Mail API is no exception. The following are the core classes of Java Mail:
- Session
- Authenticator
- Store
- Folder
- Message
- Address
- Transport
Just like the classes of other Java APIs, the factory class pattern is used in all the above classes. It will be clearer when the classes are discussed. I will be discussing the first four classes in this part as they are the "founding" classes of any Mail application.
1. Session:
Session forms the basis of any client server based application, framework or APIs. The Java Mail API is no exception. The Session class defines a basic mail session. To pass values to the Session object, the Properties object could be used. Since all the constructors of this class are private, a sharable object can be obtained by using the method of the same class -- getDefaultInstance(). This method takes two parameters in its parameterized form -- an object of Properties class, and one of the Authenticator class. The Authenticator will be discussed shortly. So, to get an instance of Session class the code is:
Properties props = new Properties();
// fill props with any information
Session session = Session.getDefaultInstance(props, null);
If a shared instance is not what is required, the getInstance() method to get a unique instance looks like this:
Properties props = new Properties();
// fill props with any information
Session session = Session.getInstance(props, null);
The parameter for Authenticator is supplied as null. This can be done to keep the application simple, but it is not recommended.
2. Authenticator:
As in the case of java.net packages, the Mail APIs can take advantage of the Authenticator class. This class provides access to the protected resources via username and password. The resources can be anything ranging from simple files to servers. For Java Mail, the resource is the server. In essence the Authenticator object passes as a parameter to the getInstance()/getDefaultInstance() method, and controls the security aspect of the Session object.
There are two ways to use the Authenticator. First, you can separately subclass the Authenticator and provide its object to the getInstance()/getDefaultInstance() method. The other way is to subclass the Authenticator by the same class that encapsulates the mailing logic. The following is an example of former approach:
Properties props = new Properties();
// fill props with any information
Authenticator auth = new MyAuthenticator();
Session session = Session.getDefaultInstance(props, auth);
To make use of the other approach the code is:
Properties props = new Properties();
// fill props with any information
Session session = Session.getDefaultInstance(props, this);
3. Store:
This class represents a mail storage. To retrieve messages, one must connect to this store. But before that, an object of the Store class must be obtained, which is done like this:
Store store = session.getStore("pop3");
store.connect(host, username, password);
The getStore() method of Session class provides an instance of Store. The parameter is the protocol to be used. It can be either “imap” for IMAP and “pop3” for POP3. Once the Store object has been obtained, the connect() method can be called with hostname/IP, username and password as parameters to connect to the Store. The connect() has a no parameter form. If the Authenticator’s object has been passed to the getInstance()/getDefaultInstance() along with the Properties object containing the hostname, then the no parameter form can be used.
4. Folder:
All the messages belonging to a particular user are placed inside a Folder within the Store. The Folder represents such a folder. As is the case with Store, an object of Folder could be obtained by calling the getFolder() method of the Store class. The getFolder() method takes only one parameter -- the name of the folder to be opened as a string. To open the inbox pass “INBOX” as the parameter. In code:
Folder folder = store.getFolder("INBOX");
folder.open(Folder.READ_ONLY);
Once the instance of Folder has been obtained, calling the open method on that instance will actually open the folder. Once opened, the messages can be retrieved. The open() method accepts one parameter representing the state in which the folder has to be opened. The constants provided in the Folder class can be used to provide the required state. Of the available states the most common are “read only” represented by Folder.READ_ONLY and “read write” represented by Folder.READ_WRITE.
This brings us to the end of this section. By now, as the majority of the core classes have been introduced, it's time to see them in action.
Next: Java Mail: Putting it all together >>
More Java Articles
More By A.P.Rajshekhar
/ 29 
