How to add a new protocol to Mail Services for JBoss

Overview

Mail Services for JBoss includes a basic set of services for implementing stateful/stateless command protocols such as SMTP, POP, IMAP and more.  The Twiddle protocol extends JBoss's twiddle interface (bin/twiddle.jar and bin/twiddle.sh for an understanding) and provides a basic way to manage JBoss server components.  See TwiddleTool for details on the twiddle tool itself.  This article will use the Twiddle example to explain how you can add your own protocols to mail services.

Server

The ServerMBean requires no alterations when adding a protocol.  It will handle answering the socket and will delegate to a ProtocolMBean.  You can see that the ServerMBean handles things like the port, threading and connection lifespan.

package org.jboss.mail;

import org.jboss.system.ServiceMBean;

/**
 * Service interface for the Server MBean.  Go look at Server.java in this same package if you really 
 * want to know.
 * @author Andrew C. Oliver
 */
public interface ServerMBean extends ServiceMBean {

    /**
     * 
     * @param port number to listen on (25 for SMTP)
     */
    void setPort(int port);
    /**
     * 
     * @return port number we're listening on
     */
    int getPort();
    /**
     * 
     * @param address (almost always "localhost")
     */
    void setAddress(String address);
    /**
     * 
     * @return addres ("localhost")
     */
    String getAddress();
    /**
     * 
     * @param life - like sothsaysers....how long a connection instance will live for
     */
    void setLife(long life);
    /**
     * 
     * @return length which connections are permitted to live for
     */
    long getLife();
    /**
     * 
     * @param timeout between protocol commands...  This is the idle time not the whole connection life.
     * This shouldn't include the time for the command to execute.
     */
    void setTimeout(long timeout);
    /**
     * 
     * @return timeout between protocol commands.
     */
    long getTimeout();
    /**
     * 
     * @param backlog number of requests (max 5 on UNIX) which can be backlogged while we're maxed and 
     * can't assign them... just leave this at 5 and don't mess with it.
     */ 
    void setBacklog(int backlog);
    /**
     * 
     * @return backlog number of requests
     */
    int getBacklog();
    /**
     * 
     * @param protocol name (JMX name usually)
     */
    void setProtocol(String protocol);
    /**
     * 
     * @return protocol name (JMX name usually)
     */
    String getProtocol(); 
    /**
     * 
     * @param poolsize threads available to handle connections (once they're all used in concurrency we run into
     *  the backlog, and those clients are blocked waiting on us...once we hit the backlog max, we refuse connections)
     */
    void setPoolSize(int poolsize);
    /**
     * 
     * @return number of connections that can be handled.
     */
    int getPoolSize();
}

Protocol

In order to implement a protocol, you must implement the ProtocolMBean.  The ProtocolMBean should extend org.jboss.system.ServiceMBean and org.jboss.mail.ServiceProxyFactory.  The associated protocol implementation should impelment the interface as well as extend org.jboss.system.ServiceMBeanSupport.

TwiddleProtocolMBean.java (ProtocolMBean)

package org.jboss.console.twiddle;

import org.jboss.mail.ServiceProxyFactory;
import org.jboss.system.ServiceMBean;

/**
 * TwiddleProtocol is used to manage servers.  Mostly we did this for demonstration purposes.
 *
 * @author Andrew C. Oliver
 */
public interface TwiddleProtocolMBean extends ServiceMBean, ServiceProxyFactory {
}

TwiddleProtocol.java (protocol implementation)

package org.jboss.console.twiddle;

import java.util.HashMap;
import java.util.Map;

import org.jboss.console.twiddle.handlers.TwiddleHandlers;
import org.jboss.mail.ServiceProxy;
import org.jboss.system.ServiceMBeanSupport;

/**
 * TwiddleProtocol implements the Twiddle Protocol for Server.  This is primarily for demonstration purposes.
 * 
 * @author Andrew C. Oliver
 */
public class TwiddleProtocol extends ServiceMBeanSupport implements TwiddleConstants, TwiddleProtocolMBean {

    Map handlers;
    Map properties;
 

    /**
     * constructs TwiddleProtocol with no configuration
     */
    public TwiddleProtocol() {
        handlers = TwiddleHandlers.instance();
        properties = new HashMap();
    }

    public String getName() {
        return "TWIDDLE";
    }

    public ServiceProxy produceServiceProxy() {
        return new TwiddleProtocolInstance(handlers, properties);
    }

    protected void startService() throws Exception {
         
    }

}

Service Proxy

As you can see the protocol must supply a method called "produceServiceProxy" which the ServerMBean can use to delegate.  Some implementators may choose to have the Protocol implement the ServiceProxy interface itself and return "this".  Presently, all protocols include a concept called "ProtocolInstance" which encapsulates the protocol as well as its state or session information.  As implemented above, this would return a new TwiddleProtocolInstance for every user connection.

The service proxy interface itself requires no methods to be implemented.

Protocol Instance

The

Request

Response

Handlers

JMX Configuration

Unit tests