First, let's see how to register a model MBean using the JMX API directly. In the following Main class, you get the documentReplicator bean from the IoC container and register it as an MBean for management and monitoring. All properties and methods are included in the MBean's management interface.

package com.apress.springrecipes.replicator;
...
import java.lang.management.ManagementFactory;

import javax.management.Descriptor;
import javax.management.JMException;
import javax.management.MBeanServer;
import javax.management.ObjectName;
import javax.management.modelmbean.DescriptorSupport;
import javax.management.modelmbean.InvalidTargetObjectTypeException;
import javax.management.modelmbean.ModelMBeanAttributeInfo;
import javax.management.modelmbean.ModelMBeanInfo;
import javax.management.modelmbean.ModelMBeanInfoSupport;
import javax.management.modelmbean.ModelMBeanOperationInfo;
import javax.management.modelmbean.RequiredModelMBean;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class Main {

    public static void main(String[] args) throws IOException {
        ApplicationContext context =
            new ClassPathXmlApplicationContext("beans-jmx.xml");

        FileReplicator documentReplicator =
            (FileReplicator) context.getBean("documentReplicator");

        try {
            MBeanServer mbeanServer = ManagementFactory.getPlatformMBeanServer();
            ObjectName objectName = new ObjectName("bean:name=documentReplicator");

            RequiredModelMBean mbean = new RequiredModelMBean();
            mbean.setManagedResource(documentReplicator, "objectReference");

            Descriptor srcDirDescriptor = new DescriptorSupport(new String[] {
                    "name=SrcDir", "descriptorType=attribute",
                    "getMethod=getSrcDir", "setMethod=setSrcDir" });
            ModelMBeanAttributeInfo srcDirInfo = new ModelMBeanAttributeInfo(
                    "SrcDir", "java.lang.String", "Source directory",
                    true, true, false, srcDirDescriptor);

            Descriptor destDirDescriptor = new DescriptorSupport(new String[] {
                    "name=DestDir", "descriptorType=attribute",
                    "getMethod=getDestDir", "setMethod=setDestDir" });

ModelMBeanAttributeInfo destDirInfo = new ModelMBeanAttributeInfo(
                    "DestDir", "java.lang.String", "Destination directory",
                    true, true, false, destDirDescriptor);

            ModelMBeanOperationInfo getSrcDirInfo = new ModelMBeanOperationInfo(
                    "Get source directory",
                    FileReplicator.class.getMethod("getSrcDir"));
            ModelMBeanOperationInfo setSrcDirInfo = new ModelMBeanOperationInfo(
                    "Set source directory",
                    FileReplicator.class.getMethod("setSrcDir", String.class));
            ModelMBeanOperationInfo getDestDirInfo = new ModelMBeanOperationInfo(
                    "Get destination directory",
                    FileReplicator.class.getMethod("getDestDir"));
            ModelMBeanOperationInfo setDestDirInfo = new ModelMBeanOperationInfo(
                    "Set destination directory",
                    FileReplicator.class.getMethod("setDestDir", String.class));
            ModelMBeanOperationInfo replicateInfo = new ModelMBeanOperationInfo(
                    "Replicate files",
                    FileReplicator.class.getMethod("replicate"));

            ModelMBeanInfo mbeanInfo = new ModelMBeanInfoSupport(
                    "FileReplicator", "File replicator",
                    new ModelMBeanAttributeInfo[] { srcDirInfo, destDirInfo },
                    null,
                    new ModelMBeanOperationInfo[] { getSrcDirInfo, setSrcDirInfo,
                            getDestDirInfo, setDestDirInfo, replicateInfo },
                    null);
            mbean.setModelMBeanInfo(mbeanInfo);

            mbeanServer.registerMBean(mbean, objectName);
        } catch (JMException e) {
            ...
        } catch (InvalidTargetObjectTypeException e) {
            ...
        } catch (NoSuchMethodException e) {
            ...
        }

        System.in.read();
    }
}

To register an MBean, you need an instance of the interface javax.managment.MBeanServer. In JDK 1.5, you can call the static method ManagementFactory.getPlatformMBeanServer() to locate a platform MBean server. It will create an MBean server if none exists and then register this server instance for future use. Each MBean requires an MBean object name that includes a domain. The preceding MBean is registered under the domain bean with the name documentReplicator.

From the preceding code, you can see that for each MBean attribute and MBean operation, you need to create a ModelMBeanAttributeInfo object and a ModelMBeanOperationInfo object for describing it. After those, you have to create a ModelMBeanInfo object for describing the MBean's management interface by assembling the preceding information. For details about using these classes, you can consult their Javadocs.

Moreover, you have to handle the JMX-specific exceptions when calling the JMX API. These exceptions are checked exceptions that you must handle.

Note that you must prevent your application from terminating before you look inside it with a JMX client tool. Requesting a key from the console using System.in.read() would be a good choice.

Finally, you have to add the VM argument -Dcom.sun.management.jmxremote to enable local monitoring of this application. You should also include all other options for your command, such as the classpath, as necessary.

Java –classpath ... -Dcom.sun.management.jmxremote com.apress.springrecipes.replicator.Main

Now, you can use any JMX client tools to monitor your MBeans locally. The simplest one may be JConsole, which comes with JDK 1.5.

When JConsole starts, you can see a list of JMX-enabled applications on the Local tab of the connection window. After connecting to the replicator application, you can see your documentReplicator MBean under the bean domain. If you want to invoke replicate(), simply click the button "replicate."

To export beans configured in the Spring IoC container as MBeans, you simply declare an MBeanExporter instance and specify the beans to export, with their MBean object names as the keys.

<bean id="mbeanExporter"
    class="org.springframework.jmx.export.MBeanExporter">
    <property name="beans">
        <map>
            <entry key="bean:name=documentReplicator"
                value-ref="documentReplicator" />
        </map>
    </property>
</bean>

The preceding configuration exports the documentReplicator bean as an MBean, under the domain bean and with the name documentReplicator. By default, all public properties are included as attributes and all public methods (with the exception of those from java.lang.Object) are included as operations in the MBean's management interface.

MBeanExporter attempts to locate an MBean server instance and register your MBeans with it implicitly. If your application is running in an environment that provides an MBean server (e.g., most Java EE application servers), MBeanExporter will be able to locate this MBean server instance.

However, in an environment with no MBean server available, you have to create one explicitly using Spring's MBeanServerFactoryBean. To make your application portable to different runtime environments, you should enable the locateExistingServerIfPossible property so that this factory bean will create an MBean server only if none is available.

<bean id="mbeanServer"
        class="org.springframework.jmx.support.MBeanServerFactoryBean">
        <property name="locateExistingServerIfPossible" value="true" />
    </bean>

If, on the other hand, you have multiple MBeans servers running, you need to tell the mbeanServer bean to which server it should bind. You do this by specifying the agentId of the server. To figure out the agentId of a given server, browse to the JMImplementation/MBeanServerDelegate/Attributes/MBeanServerId node of the server you're inspecting in JConsole. There, you'll see the string value. On our local machine, the value is workstation_1253860476443. To enable it, configure the agentId property of the MBeanServer.

<bean id="mbeanServer"
        class="org.springframework.jmx.support.MBeanServerFactoryBean">
        <property name="locateExistingServerIfPossible" value="true" />
        <property name="agentId" value="workstation_1253860476443" />
    </bean>

If you have multiple MBean server instances in your context, you can explicitly specify a specific MBean server for MBeanExporter to export your MBeans to. In this case, MBeanExporter will not locate an MBean server; it will use the specified MBean server instance. This property is for you to specify a particular MBean server when more than one is available.

<beans ...>
    ...
    <bean id="mbeanServer"
        class="org.springframework.jmx.support.MBeanServerFactoryBean">
        <property name="locateExistingServerIfPossible" value="true" />
    </bean>

    <bean id="mbeanExporter"
        class="org.springframework.jmx.export.MBeanExporter">
        ...
        <property name="server" ref="mbeanServer" />
    </bean>
</beans>

The Main class for exporting an MBean can be simplified as shown following. You have to retain the key-requesting statement to prevent your application from terminating.

package com.apress.springrecipes.replicator;
...
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class Main {

    public static void main(String[] args) throws IOException {
        new ClassPathXmlApplicationContext("beans-jmx.xml");
        System.in.read();
    }
}

If you want your MBeans to be accessed remotely, you need to enable a remoting protocol for JMX. JSR-160 defines a standard for JMX remoting through a JMX connector. Spring allows you to create a JMX connector server through ConnectorServerFactoryBean.

By default, ConnectorServerFactoryBean creates and starts a JMX connector server bound to the service URL service:jmx:jmxmp://localhost:9875, which exposes the JMX connector through the JMX Messaging Protocol (JMXMP). However, most JMX implementations, including JDK 1.5's, don't support JMXMP. Therefore, you should choose a widely supported remoting protocol for your JMX connector, such as RMI. To expose your JMX connector through a specific protocol, you just provide the service URL for it.

<beans ...>
    ...
    <bean id="rmiRegistry"
        class="org.springframework.remoting.rmi.RmiRegistryFactoryBean" />

    <bean id="connectorServer"
        class="org.springframework.jmx.support.ConnectorServerFactoryBean"
        depends-on="rmiRegistry">
        <property name="serviceUrl" value=
            "service:jmx:rmi://localhost/jndi/rmi://localhost:1099/replicator" />
    </bean>
</beans>

You specify the preceding URL to bind your JMX connector to an RMI registry listening on port 1099 of localhost. If no RMI registry has been created externally, you should create one by using RmiRegistryFactoryBean. The default port for this registry is 1099, but you can specify another one in its port property. Note that ConnectorServerFactoryBean must create the connector server after the RMI registry is created and ready. You can set the depends-on attribute for this purpose.

Now, your MBeans can be accessed remotely via RMI. When JConsole starts, you can enter the following service URL on the Advanced tab of the connection window.

service:jmx:rmi://localhost/jndi/rmi://localhost:1099/replicator

Recall that, by default, the Spring MBeanExporter exports all public properties of a bean as MBean attributes and all public methods as MBean operations. In fact, you can assemble the management interface of your MBeans using an MBean assembler. The simplest MBean assembler in Spring is MethodNameBasedMBeanInfoAssembler, which allows you to specify the names of the methods to export.

<beans ...>
    ...
    <bean id="mbeanExporter"
        class="org.springframework.jmx.export.MBeanExporter">
        ...
        <property name="assembler" ref="assembler" />
    </bean>

    <bean id="assembler" class="org.springframework.jmx.export.assembler.
        MethodNameBasedMBeanInfoAssembler">
        <property name="managedMethods">
            <list>
                <value>getSrcDir</value>
                <value>setSrcDir</value>
                <value>getDestDir</value>
                <value>setDestDir</value>
                <value>replicate</value>
            </list>
        </property>
    </bean>
</beans>

Another MBean assembler is InterfaceBasedMBeanInfoAssembler, which exports all methods defined in the interfaces you specified.

<bean id="assembler" class="org.springframework.jmx.export.assembler.
InterfaceBasedMBeanInfoAssembler">
    <property name="managedInterfaces">
        <list>
            <value>com.apress.springrecipes.replicator.FileReplicator</value>
        </list>
    </property>
</bean>

Spring also provides MetadataMBeanInfoAssembler to assemble an MBean's management interface based on the metadata in the bean class. It supports two types of metadata: JDK annotations and Apache Commons Attributes (behind the scenes, this is accomplished using a strategy interface JmxAttributeSource). For a bean class annotated with JDK annotations, you specify an AnnotationJmxAttributeSource instance as the attribute source of MetadataMBeanInfoAssembler.

<bean id="assembler" class="org.springframework.jmx.export.assembler.

    MetadataMBeanInfoAssembler">
    <property name="attributeSource">
        <bean class="org.springframework.jmx.export.annotation.AnnotationJmxAttributeSource" />
    </property>
</bean>

Then, you annotate your bean class and methods with the annotations @ManagedResource, @ManagedAttribute, and @ManagedOperation for MetadataMBeanInfoAssembler to assemble the management interface for this bean. The annotations are easily interpreted. They expose the element that they annotate. If you have a JavaBeans-compliant property, JMX will use the term attribute. Classes themselves are referred to as resources. In JMX, methods will be called operations. Knowing that, it's easy to see what the following code does:

package com.apress.springrecipes.replicator;
...
import org.springframework.jmx.export.annotation.ManagedAttribute;
import org.springframework.jmx.export.annotation.ManagedOperation;
import org.springframework.jmx.export.annotation.ManagedResource;

@ManagedResource(description = "File replicator")
public class FileReplicatorImpl implements FileReplicator {
    ...
    @ManagedAttribute(description = "Get source directory")
    public String getSrcDir() {
        ...
    }

    @ManagedAttribute(description = "Set source directory")
    public void setSrcDir(String srcDir) {
        ...
    }

    @ManagedAttribute(description = "Get destination directory")
    public String getDestDir() {
        ...
    }

    @ManagedAttribute(description = "Set destination directory")
    public void setDestDir(String destDir) {
        ...
    }

        ...

    @ManagedOperation(description = "Replicate files")
    public synchronized void replicate() throws IOException {
        ...
    }
}

In addition to exporting a bean explicitly with MBeanExporter, you can simply configure its subclass AnnotationMBeanExporter to auto-detect MBeans from beans declared in the IoC container. You needn't configure an MBean assembler for this exporter, because it uses MetadataMBeanInfoAssembler with AnnotationJmxAttributeSource by default. You can delete the previous beans and assembler properties for this exporter.

<bean id="mbeanExporter"
    class="org.springframework.jmx.export.annotation.AnnotationMBeanExporter">
    ...
</bean>

AnnotationMBeanExporter detects any beans configured in the IoC container with the @ManagedResource annotation and exports them as MBeans. By default, this exporter exports a bean to the domain whose name is the same as its package name. Also, it uses the bean's name in the IoC container as its MBean name, and the bean's short class name as its type. So your documentReplicator bean will be exported under the following MBean object name:

com.apress.springrecipes.replicator:name=documentReplicator,
type=FileReplicatorImpl

If you don't want to use the package name as the domain name, you can set the default domain for this exporter.

<bean id="mbeanExporter"
    class="org.springframework.jmx.export.annotation.AnnotationMBeanExporter">
    ...
    <property name="defaultDomain" value="bean" />
</bean>

After setting the default domain to bean, the documentReplicator bean will be exported under the following MBean object name:

bean:name=documentReplicator,type=FileReplicatorImpl

Moreover, you can specify a bean's MBean object name in the objectName attribute of the @ManagedResource annotation. For example, you can export your file copier as an MBean by annotating it with the following annotations:

package com.apress.springrecipes.replicator;
...
import org.springframework.jmx.export.annotation.ManagedOperation;
import org.springframework.jmx.export.annotation.ManagedOperationParameter;
import org.springframework.jmx.export.annotation.ManagedOperationParameters;
import org.springframework.jmx.export.annotation.ManagedResource;

@ManagedResource(
    objectName = "bean:name=fileCopier,type=FileCopierImpl",
    description = "File Copier")
public class FileCopierImpl implements FileCopier {

    @ManagedOperation(
        description = "Copy file from source directory to destination directory")
    @ManagedOperationParameters( {
        @ManagedOperationParameter(
            name = "srcDir", description = "Source directory"),
        @ManagedOperationParameter(
            name = "destDir", description = "Destination directory"),
        @ManagedOperationParameter(
            name = "filename", description = "File to copy") })
    public void copyFile(String srcDir, String destDir, String filename)
            throws IOException {
        ...
    }
}

However, specifying the object name in this way works only for classes that you're going to create a single instance of in the IoC container (e.g., file copier), not for classes that you may create multiple instances of (e.g., file replicator). This is because you can only specify a single object name for a class. As a result, you shouldn't try and run the same server multiple times without changing the names.

You can simply declare a <context:mbean-export> element in your bean configuration file, instead of the AnnotationMBeanExporter declaration, which you can omit.

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.springframework.org/schema/context
        http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <context:mbean-export server="mbeanServer" default-domain="bean" />
    ...
</beans>

You can specify an MBean server and a default domain name for this element through the server and default-domain attributes. However, you won't be able to set other MBean exporter properties such as notification listener mappings. Whenever you have to set these properties, you need to declare an AnnotationMBeanExporter instance explicitly.

The Spring IoC container supports the beans that are going to be exported as MBeans to publish JMX notifications. These beans must implement the NotificationPublisherAware interface (as you might implement ApplicationContextAware to receive a reference to the current bean's containing ApplicatonContext instance) to get access to NotificationPublisher so that they can publish notifications.

package com.apress.springrecipes.replicator;
...
import javax.management.Notification;

import org.springframework.jmx.export.notification.NotificationPublisher;
import org.springframework.jmx.export.notification.NotificationPublisherAware;

@ManagedResource(description = "File replicator")
public class FileReplicatorImpl implements FileReplicator,
        NotificationPublisherAware {
    ...
    private int sequenceNumber;
    private NotificationPublisher notificationPublisher;

    public void setNotificationPublisher(
            NotificationPublisher notificationPublisher) {
        this.notificationPublisher = notificationPublisher;
    }
  @ManagedOperation(description = "Replicate files")
    public void replicate() throws IOException {
        notificationPublisher.sendNotification(
                new Notification("replication.start", this, sequenceNumber));
        ...

notificationPublisher.sendNotification(
                new Notification("replication.complete", this, sequenceNumber));
        sequenceNumber++;
    }
}

In this file replicator, you send a JMX notification whenever a replication starts or completes. The notification is visible both in the standard output in the console as well as in the Notifications node for your service in JConsole. To see them, you must click Subscribe. Then, invoke the replicate() method, and you'll see two new notifications arrive, much like your e-mail's inbox. The first argument in the Notification constructor is the notification type, while the second is the notification source. Each notification requires a sequence number. You can use the same sequence for a notification pair to keep track of them.

Now, let's create a notification listener to listen to JMX notifications. Because a listener will be notified of many different types of notifications, such as javax.management.AttributeChangeNotification when an MBean's attribute has changed, you have to filter those notifications that you are interested in handling.

package com.apress.springrecipes.replicator;

import javax.management.Notification;
import javax.management.NotificationListener;

public class ReplicationNotificationListener implements NotificationListener {

    public void handleNotification(Notification notification, Object handback) {
        if (notification.getType().startsWith("replication")) {
            System.out.println(
                    notification.getSource() + " " +
                    notification.getType() + " #" +
                    notification.getSequenceNumber());
        }
    }
}

Then, you can register this notification listener with your MBean exporter to listen to notifications emitted from certain MBeans.

<bean id="mbeanExporter"
    class="org.springframework.jmx.export.annotation.AnnotationMBeanExporter">
    <property name="defaultDomain" value="bean" />
    <property name="notificationListenerMappings">
        <map>
            <entry key="bean:name=documentReplicator,type=FileReplicatorImpl">
                <bean class="com.apress.springrecipes.replicator.

                 ReplicationNotificationListener" />
            </entry>
        </map>
    </property>
</bean>

A JMX client requires an MBean server connection to access MBeans running on a remote MBean server. Spring provides org.springframework.jmx.support.MBeanServerConnectionFactoryBean for you to create a connection to a remote JSR-160–enabled MBean server declaratively. You only have to provide the service URL for it to locate the MBean server. Now let's declare this factory bean in your client bean configuration file (e.g., beans-jmx-client.xml).

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

<bean id="mbeanServerConnection"
        class="org.springframework.jmx.support.MBeanServerConnectionFactoryBean">
        <property name="serviceUrl" value=
            "service:jmx:rmi://localhost/jndi/rmi://localhost:1099/replicator" />
    </bean>
</beans>

With the MBean server connection created by this factory bean, you can access and operate the MBeans running on this server. For example, you can query and update an MBean's attributes through the getAttribute() and setAttribute() methods, giving the MBean's object name and attribute name. You can also invoke an MBean's operations by using the invoke() method.

package com.apress.springrecipes.replicator;

import javax.management.Attribute;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class Client {

    public static void main(String[] args) throws Exception {
        ApplicationContext context =
            new ClassPathXmlApplicationContext("beans-jmx-client.xml");

        MBeanServerConnection mbeanServerConnection =
            (MBeanServerConnection) context.getBean("mbeanServerConnection");

        ObjectName mbeanName = new ObjectName(
                "bean:name=documentReplicator,type=FileReplicatorImpl");

        String srcDir = (String) mbeanServerConnection.getAttribute(
                mbeanName, "SrcDir");

        mbeanServerConnection.setAttribute(
                mbeanName, new Attribute("DestDir", srcDir + "_1"));

        mbeanServerConnection.invoke(
                mbeanName, "replicate", new Object[] {}, new String[] {});
    }
}

Suppose that you've created the following JMX notification listener, which listens to file replication notifications:

package com.apress.springrecipes.replicator;

import javax.management.Notification;
import javax.management.NotificationListener;

public class ReplicationNotificationListener implements NotificationListener {

    public void handleNotification(Notification notification, Object handback) {
        if (notification.getType().startsWith("replication")) {
            System.out.println(
                    notification.getSource() + " " +
                    notification.getType() + " #" +
                    notification.getSequenceNumber());
        }
    }
}

You can register this notification listener to the MBean server connection to listen to notifications emitted from this MBean server.

package com.apress.springrecipes.replicator;
...
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;

public class Client {

    public static void main(String[] args) throws Exception {
        ...
        MBeanServerConnection mbeanServerConnection =
            (MBeanServerConnection) context.getBean("mbeanServerConnection");

        ObjectName mbeanName = new ObjectName(
                "bean:name=documentReplicator,type=FileReplicatorImpl");

        mbeanServerConnection.addNotificationListener(
                mbeanName, new ReplicationNotificationListener(), null, null);
        ...
    }
}

After you run this, check JConsole again under the Notifications node. You'll see the same two notifications as before and an interesting, new notification of type jmx.attribute.change.

Another approach that Spring offers for remote MBean access is through MBeanProxy, which can be created by MBeanProxyFactoryBean.

<beans ...>
    <bean id="mbeanServerConnection"
        class="org.springframework.jmx.support.MBeanServerConnectionFactoryBean">
        <property name="serviceUrl" value=
            "service:jmx:rmi://localhost/jndi/rmi://localhost:1099/replicator" />
    </bean>

    <bean id="fileReplicatorProxy"
        class="org.springframework.jmx.access.MBeanProxyFactoryBean">
        <property name="server" ref="mbeanServerConnection" />
        <property name="objectName"
            value="bean:name=documentReplicator,type=FileReplicatorImpl" />
        <property name="proxyInterface"
            value="com.apress.springrecipes.replicator.FileReplicator" />
    </bean>
</beans>

You need to specify the object name and the server connection for the MBean you are going to proxy. The most important is the proxy interface, whose local method calls will be translated into remote MBean calls behind the scenes.

Now, you can operate the remote MBean through this proxy as if it were a local bean. The preceding MBean operations invoked on the MBean server connection directly can be simplified as follows:

package com.apress.springrecipes.replicator;
...
public class Client {

    public static void main(String[] args) throws Exception {
        ...
        FileReplicator fileReplicatorProxy =
            (FileReplicator) context.getBean("fileReplicatorProxy");

        String srcDir = fileReplicatorProxy.getSrcDir();
        fileReplicatorProxy.setDestDir(srcDir + "_1");
        fileReplicatorProxy.replicate();
    }
}

Now, let's take a look at how to send e-mail using the JavaMail API. You can implement the ErrorNotifier interface to send e-mail notifications in case of errors.

<dependency>
   <groupId>javax.mail</groupId>
   <artifactId>mail</artifactId>
   <version>1.4</version>
 </dependency>

package com.apress.springrecipes.replicator;

import java.util.Properties;

import javax.mail.Message;
import javax.mail.MessagingException;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public class EmailErrorNotifier implements ErrorNotifier {

    public void notifyCopyError(String srcDir, String destDir, String filename) {
        Properties props = new Properties();
        props.put("mail.smtp.host", "localhost");
        props.put("mail.smtp.port", "25");
        props.put("mail.smtp.username", "system");
        props.put("mail.smtp.password", "12345");
        Session session = Session.getDefaultInstance(props, null);
        try {
            Message message = new MimeMessage(session);
            message.setFrom(new InternetAddress("system@localhost"));
            message.setRecipients(Message.RecipientType.TO,
                    InternetAddress.parse("admin@localhost"));
            message.setSubject("File Copy Error");
            message.setText(
                "Dear Administrator,

" +
                "An error occurred when copying the following file :
" +
                "Source directory : " + srcDir + "
" +
                "Destination directory : " + destDir + "
" +
                "Filename : " + filename);
            Transport.send(message);
        } catch (MessagingException e) {
            throw new RuntimeException(e);
        }
    }
}

You first open a mail session connecting to an SMTP server by defining the properties. Then, you create a message from this session for constructing your e-mail. After that, you send the e-mail by making a call to Transport.send(). When dealing with the JavaMail API, you have to handle the checked exception MessagingException. Note that all these classes, interfaces, and exceptions are defined by JavaMail.

Next, declare an instance of EmailErrorNotifier in the Spring IoC container for sending e-mail notifications in case of file replication errors.

<bean id="errorNotifier"
    class="com.apress.springrecipes.replicator.EmailErrorNotifier" />

You can write the following Main class to test EmailErrorNotifier. After running it, you can configure your e-mail application to receive the e-mail from your James Server via POP3.

package com.apress.springrecipes.replicator;

import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class Main {

    public static void main(String[] args) {
        ApplicationContext context =
            new ClassPathXmlApplicationContext("beans.xml");

        ErrorNotifier errorNotifier =
            (ErrorNotifier) context.getBean("errorNotifier");
        errorNotifier.notifyCopyError(
            "c:/documents", "d:/documents", "spring.doc");
    }
}

Now, let's look at how to send e-mail with the help of Spring's MailSender interface, which can send SimpleMailMessage in its send() method. With this interface, your code is no longer JavaMail specific, and now it's easier to test.

package com.apress.springrecipes.replicator;

import org.springframework.mail.MailSender;
import org.springframework.mail.SimpleMailMessage;

public class EmailErrorNotifier implements ErrorNotifier {

    private MailSender mailSender;

    public void setMailSender(MailSender mailSender) {
        this.mailSender = mailSender;
    }

    public void notifyCopyError(String srcDir, String destDir, String filename) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom("system@localhost");
        message.setTo("admin@localhost");
        message.setSubject("File Copy Error");
        message.setText(
                "Dear Administrator,

" +
                "An error occurred when copying the following file :
" +
                "Source directory : " + srcDir + "
" +
                "Destination directory : " + destDir + "
" +
                "Filename : " + filename);
        mailSender.send(message);
    }
}

Next, you have to configure a MailSender implementation in the bean configuration file and inject it into EmailErrorNotifier. In Spring, the unique implementation of this interface is JavaMailSenderImpl, which uses JavaMail to send e-mail.

<beans ...>
    ...
    <bean id="mailSender"
        class="org.springframework.mail.javamail.JavaMailSenderImpl">
        <property name="host" value="localhost" />
        <property name="port" value="25" />
        <property name="username" value="system" />
        <property name="password" value="12345" />
    </bean>

    <bean id="errorNotifier"
        class="com.apress.springrecipes.replicator.EmailErrorNotifier">
        <property name="mailSender" ref="mailSender" />
    </bean>
</beans>

The default port used by JavaMailSenderImpl is the standard SMTP port 25, so if your e-mail server listens on this port for SMTP, you can simply omit this property. Also, if your SMTP server doesn't require user authentication, you needn't set the username and password.

If you have a JavaMail session configured in your Java EE application server, you can first look it up with the help of JndiObjectFactoryBean.

<bean id="mailSession"
    class="org.springframework.jndi.JndiObjectFactoryBean">
    <property name="jndiName" value="mail/Session" />
</bean>

Or you can look up a JavaMail session through the <jee:jndi-lookup> element if you are using Spring 2.0 or later.

<jee:jndi-lookup id="mailSession" jndi-name="mail/Session" />

You can inject the JavaMail session into JavaMailSenderImpl for its use. In this case, you no longer need to set the host, port, username, or password.

<bean id="mailSender"
    class="org.springframework.mail.javamail.JavaMailSenderImpl">
    <property name="session" ref="mailSession" />
</bean>

Constructing an e-mail message from scratch in the method body is not efficient, because you have to hard-code the e-mail properties. Also, you may have difficulty in writing the e-mail text in terms of Java strings. You can consider defining an e-mail message template in the bean configuration file and construct a new e-mail message from it.

<beans ...>
    ...
    <bean id="copyErrorMailMessage"
        class="org.springframework.mail.SimpleMailMessage">
        <property name="from" value="system@localhost" />
        <property name="to" value="admin@localhost" />
        <property name="subject" value="File Copy Error" />
        <property name="text">
            <value>
<![CDATA[
Dear Administrator,

An error occurred when copying the following file :
Source directory : %s
Destination directory : %s
Filename : %s
]]>
            </value>
        </property>
    </bean>

    <bean id="errorNotifier"
        class="com.apress.springrecipes.replicator.EmailErrorNotifier">
        <property name="mailSender" ref="mailSender" />
        <property name="copyErrorMailMessage" ref="copyErrorMailMessage" />
    </bean>
</beans>

Note that in the preceding message text, you include the placeholders %s, which will be replaced by message parameters through String.format(). Of course, you can also use a powerful templating language such as Velocity or FreeMarker to generate the message text according to a template. It's also a good practice to separate mail message templates from bean configuration files.

Each time you send e-mail, you can construct a new SimpleMailMessage instance from this injected template. Then you can generate the message text using String.format() to replace the %s placeholders with your message parameters.

package com.apress.springrecipes.replicator;
...
import org.springframework.mail.SimpleMailMessage;

public class EmailErrorNotifier implements ErrorNotifier {
    ...
    private SimpleMailMessage copyErrorMailMessage;

    public void setCopyErrorMailMessage(SimpleMailMessage copyErrorMailMessage) {
        this.copyErrorMailMessage = copyErrorMailMessage;
    }

public void notifyCopyError(String srcDir, String destDir, String filename) {
        SimpleMailMessage message = new SimpleMailMessage(copyErrorMailMessage);
        message.setText(String.format(
                copyErrorMailMessage.getText(), srcDir, destDir, filename));
        mailSender.send(message);
    }
}

So far, the SimpleMailMessage class you used can send only a simple plain text e-mail message. To send e-mail that contains HTML content, inline images, or attachments, you have to construct and send a MIME message instead. MIME is supported by JavaMail through the javax.mail.internet.MimeMessage class.

First of all, you have to use the JavaMailSender interface instead of its parent interface MailSender. The JavaMailSenderImpl instance you injected does implement this interface, so you needn't modify your bean configurations. The following notifier sends Spring's bean configuration file as an e-mail attachment to the administrator:

package com.apress.springrecipes.replicator;

import javax.mail.MessagingException;
import javax.mail.internet.MimeMessage;

import org.springframework.core.io.ClassPathResource;
import org.springframework.mail.MailParseException;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.MimeMessageHelper;

public class EmailErrorNotifier implements ErrorNotifier {

    private JavaMailSender mailSender;
    private SimpleMailMessage copyErrorMailMessage;

    public void setMailSender(JavaMailSender mailSender) {
        this.mailSender = mailSender;
    }

    public void setCopyErrorMailMessage(SimpleMailMessage copyErrorMailMessage) {
        this.copyErrorMailMessage = copyErrorMailMessage;
    }

    public void notifyCopyError(String srcDir, String destDir, String filename) {
        MimeMessage message = mailSender.createMimeMessage();
        try {
            MimeMessageHelper helper = new MimeMessageHelper(message, true);
            helper.setFrom(copyErrorMailMessage.getFrom());
            helper.setTo(copyErrorMailMessage.getTo());

helper.setSubject(copyErrorMailMessage.getSubject());
            helper.setText(String.format(
                    copyErrorMailMessage.getText(), srcDir, destDir, filename));

            ClassPathResource config = new ClassPathResource("beans.xml");
            helper.addAttachment("beans.xml", config);
        } catch (MessagingException e) {
            throw new MailParseException(e);
        }
        mailSender.send(message);
    }
}

Unlike SimpleMailMessage, the MimeMessage class is defined by JavaMail, so you can only instantiate it by calling mailSender.createMimeMessage(). Spring provides the helper class MimeMessageHelper to simplify the operations of MimeMessage. It allows you to add an attachment from a Spring Resource object. However, the operations of this helper class still throw JavaMail's MessagingException. You have to convert this exception into Spring's mail runtime exception for consistency.

Spring offers another method for you to construct a MIME message, which is through implementing the MimeMessagePreparator interface.

package com.apress.springrecipes.replicator;
...
import javax.mail.internet.MimeMessage;

import org.springframework.mail.javamail.MimeMessagePreparator;

public class EmailErrorNotifier implements ErrorNotifier {
    ...
    public void notifyCopyError(
            final String srcDir, final String destDir, final String filename) {
        MimeMessagePreparator preparator = new MimeMessagePreparator() {

            public void prepare(MimeMessage mimeMessage) throws Exception {
                MimeMessageHelper helper =
                    new MimeMessageHelper(mimeMessage, true);
                helper.setFrom(copyErrorMailMessage.getFrom());
                helper.setTo(copyErrorMailMessage.getTo());
                helper.setSubject(copyErrorMailMessage.getSubject());
                helper.setText(String.format(
                    copyErrorMailMessage.getText(), srcDir, destDir, filename));

                ClassPathResource config = new ClassPathResource("beans.xml");
                helper.addAttachment("beans.xml", config);
            }
        };
        mailSender.send(preparator);
    }
}

In the prepare() method, you can prepare the MimeMessage object, which is precreated for JavaMailSender. If there's any exception thrown, it will be converted into Spring's mail runtime exception automatically.

To use Quartz for scheduling, first create your job by implementing the Job interface. For example, the following job executes the replicate() method of a file replicator, retrieved from the job data map through the JobExecutionContext object that's passed in.

<dependency>
   <groupId>org.opensymphony.quartz</groupId>
   <artifactId>quartz</artifactId>
   <version>1.6.1</version>
 </dependency>

package com.apress.springrecipes.replicator;
...
import org.quartz.Job;
import org.quartz.JobExecutionContext;
import org.quartz.JobExecutionException;

public class FileReplicationJob implements Job {

    public void execute(JobExecutionContext context)
            throws JobExecutionException {
        Map dataMap = context.getJobDetail().getJobDataMap();
        FileReplicator fileReplicator =
            (FileReplicator) dataMap.get("fileReplicator");
        try {
            fileReplicator.replicate();
        } catch (IOException e) {
            throw new JobExecutionException(e);
        }
    }
}

After creating the job, you configure and schedule it with the Quartz API. For instance, the following scheduler runs your file replication job every 60 seconds with a 5-second delay for the first time of execution:

package com.apress.springrecipes.replicator;
...
import org.quartz.JobDetail;
import org.quartz.Scheduler;
import org.quartz.SimpleTrigger;
import org.quartz.impl.StdSchedulerFactory;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class Main {

    public static void main(String[] args) throws Exception {
        ApplicationContext context =
            new ClassPathXmlApplicationContext("beans.xml");

        FileReplicator documentReplicator =
            (FileReplicator) context.getBean("documentReplicator");

        JobDetail job = new JobDetail();
        job.setName("documentReplicationJob");
        job.setJobClass(FileReplicationJob.class);
        Map dataMap = job.getJobDataMap();
        dataMap.put("fileReplicator", documentReplicator);

SimpleTrigger trigger = new SimpleTrigger();
        trigger.setName("documentReplicationJob");
        trigger.setStartTime(new Date(System.currentTimeMillis() + 5000));
        trigger.setRepeatCount(SimpleTrigger.REPEAT_INDEFINITELY);
        trigger.setRepeatInterval(60000);

        Scheduler scheduler = new StdSchedulerFactory().getScheduler();
        scheduler.start();
        scheduler.scheduleJob(job, trigger);
    }
}

In the Main class, you first configure the job details for your file replication job in a JobDetail object and prepare job data in its jobDataMap property. Next, you create a SimpleTrigger object to configure the scheduling properties. Finally, you create a scheduler to run your job using this trigger.

Quartz supports two types of triggers: SimpleTrigger and CronTrigger. SimpleTrigger allows you to set trigger properties such as start time, end time, repeat interval, and repeat count. CronTrigger accepts a Unix cron expression for you to specify the times to run your job. For example, you can replace the preceding SimpleTrigger with the following CronTrigger to run your job at 17:30 every day:

CronTrigger trigger = new CronTrigger();
trigger.setName("documentReplicationJob");
trigger.setCronExpression("0 30 17 * * ?");

A cron expression is made up of seven fields (the last field is optional), separated by spaces. Table 18-1 shows the field description for a cron expression.

Each part of a cron expression can be assigned a specific value (e.g. 3), a range (e.g. 1–5), a list (e.g. 1,3,5), a wildcard (* matches all values), or a question mark (? is used in either of the "Day of month" and "Day of week" fields for matching one of these fields but not both). For more information on the cron expressions supported by CronTrigger, refer to its Javadoc http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html).

When using Quartz, you can create a job by implementing the Job interface and retrieve job data from the job data map through JobExecutionContext. To decouple your job class from the Quartz API, Spring provides QuartzJobBean, which you can extend to retrieve job data through setter methods. QuartzJobBean converts the job data map into properties and injects them via the setter methods.

package com.apress.springrecipes.replicator;
...
import org.quartz.JobExecutionContext;
import org.quartz.JobExecutionException;
import org.springframework.scheduling.quartz.QuartzJobBean;

public class FileReplicationJob extends QuartzJobBean {

    private FileReplicator fileReplicator;

    public void setFileReplicator(FileReplicator fileReplicator) {
        this.fileReplicator = fileReplicator;
    }

    protected void executeInternal(JobExecutionContext context)
            throws JobExecutionException {
        try {
            fileReplicator.replicate();
        } catch (IOException e) {
            throw new JobExecutionException(e);
        }
    }
}

Then, you can configure a Quartz JobDetail object in Spring's bean configuration file through JobDetailBean. By default, Spring uses this bean's name as the job name. You can modify it by setting the name property.

<bean name="documentReplicationJob"
    class="org.springframework.scheduling.quartz.JobDetailBean">
    <property name="jobClass"
        value="com.apress.springrecipes.replicator.FileReplicationJob" />
    <property name="jobDataAsMap">
        <map>
            <entry key="fileReplicator" value-ref="documentReplicator" />
        </map>
    </property>
</bean>

Spring also offers MethodInvokingJobDetailFactoryBean for you to define a job that executes a single method of a particular object. This saves you the trouble of creating a job class. You can use the following job detail to replace the previous:

<bean id="documentReplicationJob" class="org.springframework.

    scheduling.quartz.MethodInvokingJobDetailFactoryBean">
    <property name="targetObject" ref="documentReplicator" />
    <property name="targetMethod" value="replicate" />
</bean>

You can configure a Quartz SimpleTrigger object in Spring's bean configuration file through SimpleTriggerBean, which requires a reference to a JobDetail object. This bean provides common default values for certain trigger properties, such as using the bean name as the job name and setting indefinite repeat count.

<bean id="documentReplicationTrigger"
    class="org.springframework.scheduling.quartz.SimpleTriggerBean">
    <property name="jobDetail" ref="documentReplicationJob" />
    <property name="repeatInterval" value="60000" />
    <property name="startDelay" value="5000" />
</bean>

You can also configure a Quartz CronTrigger object in the bean configuration file through CronTriggerBean.

<bean id="documentReplicationTrigger"
    class="org.springframework.scheduling.quartz.CronTriggerBean">
    <property name="jobDetail" ref="documentReplicationJob" />
    <property name="cronExpression" value=" 0 * * * * ? " />
</bean>

Finally, you can configure a SchedulerFactoryBean instance to create a Scheduler object for running your trigger. You can specify multiple triggers in this factory bean.

<bean class="org.springframework.scheduling.quartz.SchedulerFactoryBean">
    <property name="triggers">
        <list>
            <ref bean="documentReplicationTrigger" />
           <!--    other triggers you have may be included here -->
        </list>
    </property>
</bean>

Now, you can simply start your scheduler with the following Main class. In this way, you don't require a single line of code for scheduling jobs.

package com.apress.springrecipes.replicator;

import org.springframework.context.support.ClassPathXmlApplicationContext;

public class Main {

    public static void main(String[] args) throws Exception {
        new ClassPathXmlApplicationContext("beans.xml");
    }
}