TeD.org website

MailsterSMTP 1.0.0-M2

Released on 2009-02-10

MailsterSMTP is the result of months of dedicated work briefly resumed here. SubethaSMTP is a SMTP library i discovered after working some time on integrating Dumbster (a basic java SMTP server) into Mailster. It seemed that this library had some qualities that made it a viable alternative to using Dumbster. But i wanted a NIO SMTP server and not a classical socket server with blocking IO. So i did create a patch and integrated it into the 2.x releases of the library as i was invited to join the SubEthaSMTP project team. This patch did enhance some aspects of the library and introduced the use of asynchronous IO by relying on the framework of the Apache Foundation called MINA .

Recently, the project admins of SubEthaSMTP decided to drop the 2.x branch of the library and to go back to a blocking IO API mainly because of the complexity which growed significantly in the core of the library. After many discussions on the mailing list, to understand why they suddenly took such a radical decision, one can see some logic in their thoughts although this decision was mainly motivated by some constraints the project admins did have on their daily use of the library (like using it in J2EE code with container managed transactions).

So i decided to leave the project and to concentratre my efforts on building MailsterSMTP from the ashes of the code i had been the main contributor for almost two years. This new SMTP server library will benefit of being relatively free to break backward compatibility (even if it will be easy to port programs to MailsterSMTP) and to improve many aspects as the ones listed in the changelog below :

Briefly ...

»	Type Java SMTP server
»	Downloads 1.0.0-M2 1.0.0-M1
»	Status Integrated in Mailster 0.9.1
»	Latest Version 1.0.0-M2
»	Technologies Java JDK1.5+, Mina NIO framework
»	License APL v2.0

Changelog

1.0.0-M2

Codename: A new dawn

Added ASF license file.
Added javadoc.
Refactored SMTPServer class to use a configuration object making internals less tied and much cleaner.
Javadoced each configuration option to make clear when their value is read.
The charset and the data deferred size new values will now be reread at each server startup.
Removed the getHelp(..) method from the Command interface.
Command objects now have a direct reference to their CommandHandler.
Reworked starp/stop methods and added a shutdown method to the SMTPServer class thus allowing to restart multiple times the same instance until shutdown is called.
Removed the acceptor thread pool which is not used since the migration to MINA 2.
New empty constructor in SMTPServer class for ease of use.
Added mail trace in the default implementation of the DeliveryHandler.
Improved by 10% large data transfers by preventing unnecessary IoBuffer copies due to auto expanding.
Improved DefaultDeliveryHandler against concurrent modifications of it's deliveries list.
Fixed internal state after the end of a data transfer. This is no more the DeliveryHandler job to reset it's state at the end of the data(...) method because it's resetMessageState() method will be called.
Extracted Delivery and SharedStreamUtils classes from the AbstractDeliveryHandler class to further prevent custom implementations from duplicating existing code.
Added NPE check to the authentication API to prevent a custom factory from returning a null instance.

1.0.0-M1

Codename: The 5th Of November

Migrated to MINA 2.0.0-M4 (was previously using a 1.1.x version)
Big code refactoring to make code easy to lean and understand.
Added junit tests to test new functionnalities.
Removed some unnecessary classes and interfaces that only add complexity to the code.
API cleaning by renaming classes to reflect their real use.
The MessageListener list can now be modified on the fly and changes are immediately available to new connections.
The new MessageDelivery API allows to control how mail messages are delivered without having to 'reinvent the wheel' each time by building on the available and tested code from the AbstractDeliveryHandler class.
Fixed HelpCommand class : prettified help messages, handled DATA_END correctly.
Removed some unnecessary resets of the session state.
Resolved a potential concurrency problem in WiserMessage.getData() method and marked it as deprecated as it is a very bad design idea.
Added a SessionContext to the MessageListener API : it provides the ability to store some private attributes between the execution of the accept and deliver methods while also providing the remote ip and the credential as parameters for these methods.
Fixed EHLO announce of supported AUTH mechanisms.
Fixed error code returned when a TooMuchDataException occurs.
Removed the fake VRFY command which is not part of the default required command set of a SMTP implementation.
Added some adapter classes to reduce code writing on simple applications.
Fixed AuthenticationHandler and LoginValidator interface which raised an incorrect exception.
Fixed a rare threading issue allowing a re authentication immediately after a successfull authentication.
Fixed bad commands handling and error codes messages.

The MessageListener API

click the icon to display/hide Example 1 - A basic server

import java.io.IOException;
import java.io.InputStream;

import org.mailster.smtp.SMTPServer;
import org.mailster.smtp.api.SessionContext;
import org.mailster.smtp.api.TooMuchDataException;
import org.mailster.smtp.api.listener.MessageListenerAdapter;

public class BasicServer 
{
	public static void main(String[] args) 
	{
		SMTPServer server = new SMTPServer(new MessageListenerAdapter() {
			public void deliver(SessionContext ctx, String from, String recipient,
					InputStream data) throws TooMuchDataException, IOException {
                // TODO Store mail in a memory object, on a file system etc ...
				System.out.println("New message received");
			}
		});

		server.start();
	}
}

click the icon to display/hide Example 2 - A basic server with support for LOGIN and PLAIN authentication mechanisms

import java.io.IOException;
import java.io.InputStream;

import org.mailster.smtp.SMTPServer;
import org.mailster.smtp.api.SessionContext;
import org.mailster.smtp.api.TooMuchDataException;
import org.mailster.smtp.api.listener.MessageListenerAdapter;

import org.mailster.smtp.auth.LoginFailedException;
import org.mailster.smtp.auth.LoginValidator;
import org.mailster.smtp.auth.impl.AllSchemesAuthenticationHandler;

public class AuthAwareServer 
{
	public static void main(String[] args) 
	{
		SMTPServer server = new SMTPServer(new MessageListenerAdapter() {
			public void deliver(SessionContext ctx, String from, String recipient,
					InputStream data) throws TooMuchDataException, IOException {
                // TODO Store mail in a memory object, on a file system etc ...
				System.out.println("New message received");
			}
		});
		
		server.setAuthenticationHandlerFactory(
        		new AllSchemesAuthenticationHandler(new LoginValidator() {
			public void login(String username, String password)
					throws LoginFailedException {
                // TODO check provided credentials against an LDAP, 
                // or a DB table for example ...
				System.out.println("username="+username);
				System.out.println("password="+password);
			}
		}));
		server.start();
	}
}

The new DeliveryHandler API

This new API allows to further control mail delivery behaviour. You can for example : add some logic to test if the specified sender or recipients are allowed ; add some logging to the methods ; deliver each message to each listener or maybe have a listener which will always get a copy of each mail ; store each email in a database etc ...

The AbstractDeliveryHandler base class provide some usefull methods like the getPrivateInputStream(...) which enables each listener to read it's own private stream which is a shared instance of the original one without blocking the other listeners thus providing multhreading improvements. You can also look at the default implementation provided to see how this API can be used.

Example 3 - Using a custom delivery handler

click the icon to display/hide

The server

import java.io.IOException;
import java.io.InputStream;

import org.mailster.smtp.SMTPServer;
import org.mailster.smtp.api.SessionContext;
import org.mailster.smtp.api.TooMuchDataException;
import org.mailster.smtp.api.listener.MessageListenerAdapter;

public class CustomHandlerServer 
{
	public static void main(String[] args) 
	{
		SMTPServer server = new SMTPServer(new MessageListenerAdapter() {
			public void deliver(SessionContext ctx, 
            		String from, String recipient, InputStream data) 
                throws TooMuchDataException, IOException 
            {
				System.out.println("New message received");
			}
		});
		
		server.getDeliveryHandlerFactory().setDeliveryHandlerImplClass(
				CustomDeliveryHandlerImpl.class);
		
		// TODO Optionally you can set an auth factory
		// server.setAuthenticationHandlerFactory(...);
		server.start();
	}
}

The custom delivery implementation

import java.io.IOException;
import java.io.InputStream;

import org.mailster.smtp.api.RejectException;
import org.mailster.smtp.api.TooMuchDataException;
import org.mailster.smtp.api.handler.AbstractDeliveryHandler;
import org.mailster.smtp.api.handler.DeliveryContext;
import org.mailster.smtp.auth.AuthenticationHandler;

public class CustomDeliveryHandlerImpl 
	extends AbstractDeliveryHandler
{
	/**
	 * An instance of this implementation will be created for each 
	 * SMTP session.
	 * 
	 * @param ctx the delivery context
	 * @param authHandler the authentication handler
	 */
	protected CustomDeliveryHandlerImpl(DeliveryContext ctx,
			AuthenticationHandler authHandler) 
	{
		super(ctx, authHandler);
	}

	@Override
	public void data(InputStream data) throws RejectException,
			TooMuchDataException, IOException 
	{
		// TODO This is where mail data is really delivered 
		// to the listeners
        
        // TIP : use the getPrivateInputStream(boolean, InputStream) 
        // method to deliver a private shared InputStream to a listener
	}

	@Override
	public void from(String from) throws RejectException 
    {
		// Called once (unless session is reset). It gives the
		// email address of the sender
	}

	@Override
	public void recipient(String recipient) throws RejectException 
    {
		// Called once for each recipient 		
	}

	@Override
	public void resetMessageState() 
    {
		// TODO Called if SMTP session is reset thus allowing to clean
		// this class state.
	}
}