Alan Williamson

MailCatcher - Configuration

While MailCatcher can be run in either standalone or embedded mode, the configuration is the same for both modes.  Configuration is done via a properties file, or Property Java Object.

Standalone Mode

	% java -jar mailcatcher.jar config.ini

Embedded Mode:

	Properties prop = new java.util.Properties();
	:
	MailCatcher mailcatcher = new MailCatcher( prop );

The configuration is controlled via key/valued pairs that setup various elements of the system.  The majority of settings have default values and you need not worry about most of them.

Runtime Settings

The following parameters are available for setting the main MailCatcher characteristics.

	# _____________________________________ 
	# The IP address you wish to bind to.
	# Defaults to all IPs
	# mailcatcher.bindaddress=

	# _____________________________________
	# The port you want to listen on.  If running this under linux then
	# you will need to be root to listen on ports < 1024
	# Defaults to Port25
	# mailcatcher.port=

	# _____________________________________
	# Where do you want the log file to be created
	# Defaults to the "./mailcatcher.log" 
	# mailcatcher.logfile=

	# _____________________________________ 
	# How many connections do you want to handle at once. 
	# Defaults to 20 
	# mailcatcher.maxconnections=

	# _____________________________________ 
	# Where do you want incoming mail to be spooled to? 
	# Defaults to the "./spool_in" 
	# mailcatcher.spooldir=
	
	# _____________________________________ 
	# Where do you want outgoing mail to be spooled to? 
	# Defaults to the "./spool" 
	# mailcatcher.deliveryqueue=

	# _____________________________________ 
	# What is the postmasters email address? 
	# Defaults to the "root@localhost" 
	# mailcatcher.postmaster=

	# _____________________________________ 
	# How many concurrent delivery agents do you want to run? 
	# Defaults to 5 
	# mailcatcher.spoolagents=
	
	# _____________________________________ 
	# How many times should we attempt to deliver a message before giving up 
	# Defaults to 3 
	# mailcatcher.spoolretries=

	# _____________________________________
	# How many minutes between each retry should we wait before trying again? 
	# Defaults to 4hours 
	# mailcatcher.spoolretrytimeout=
	
	# _____________________________________ 
	# What is the name of this host that the SMTP layer will report? 
	# Defaults to "localhost" 
	# mailcatcher.localhost= 

MailCatcher will not attempt to consume too much memory.  For example, while it is accepting an email from a remote host, and it goes over 64,000 bytes then the in-memory buffer is cleared, and all that email is then paged out to disk in real-time as the email is accepted.  As soon as that email is finished processing and has gone through all the mailets and matchers, it is removed from memory and disk.

Mailet Configuration

When a mail arrives to MailCatcher, the mail is passed onto the default or root chain for processing.  A chain is a series of matchers/mailets that process the mail in a given order.  You can have as many chains, matchers/mailets as you wish.  MailCatcher imposes no limit.  The only condition is that at least the root chain is available for processing the initial email.  You define the chain by specifying a list of matchers that make up that chain.  This is denoted by a comma-separated list.

	spoolchain.name=root,mychain

For each chain, you then define the list of matchers that make up that chains processing.  This is also a comma-separated list of named matchers.

	spoolchain.root.matchers=matcher1,matcher2
	spoolchain.mychain.matchers=matcher3,matcher4

Now that you have defined the chain and the order, you now must provide details for each of your matchers.  This allows you to quickly change the order of processing with minimal hassle.  Each matcher block needs to know the matcher class and the mailet that will be run should that matcher return recipients.   You do this using a matcher block.

	matcher.matcher1=org.spikesource.mailcatcher.matchers.All
	matcher.matcher1.condition=someCondition
	matcher.matcher1.mailet=org.spikesource.mailcatcher.mailet.BasicMailet
	matcher.matcher1.mailetparams=q=w,e=r,t=y

The first line is the fully qualified class name of the matcher class.  This class must implement the Matcher interface.  You can pass in some additional information to this class using the .condition parameter.  If this matcher is successful then the mailet described in matcher.[name].mailet has its service(..) method invoked.  Again, you can pass in parameters to this class instance using comma-separated key/value pairs.

As of release 0.9 of MailCatcher, the org.spikesource.mailcatcher.matchers.All is the only matcher that is shipped and this simply returns all recipients.

When processing an email inside a service(..) method, you can move the email to another chain by calling the Mail.setState( chainName ) method and returning.  This will then cause the email to transverse the named chained running through their matchers and mailets.  This functionality is very powerful allowing you to create sophiscated mail flows with minimal code.

Related Stories

• Grizzly 1.7 Released - Shows just what Java is made of
• JavaFX - Sun javax.swing's and misses once again
• New release: MailCatcher the alternative Mailet Container
• About Alan Williamson

 

Comments (2)

Add Comment