Package org.dspace.core

Class Email

  • public class Email
extends Object
    Class representing an e-mail message. The send() method causes the assembled message to be formatted and sent.

    Typical use: 

     Email email = Email.getEmail(path);
 email.addRecipient("foo@bar.com");
 email.addArgument("John");
 email.addArgument("On the Testing of DSpace");
 email.send();
    path is the filesystem path of an email template, typically in ${dspace.dir}/config/emails/ and can include the subject -- see below. Templates are processed by Apache Velocity. They may contain VTL directives and property placeholders.

    addArgument(string) adds a property to the params array in the Velocity context, which can be used to replace placeholder tokens in the message. These arguments are indexed by number in the order they were added to the message.

    The DSpace configuration properties are also available to templates as the array config, indexed by name. Example: ${config.get('dspace.name')}

    Recipients and attachments may be added as needed. See addRecipient(java.lang.String), addAttachment(java.io.File,java.lang.String), and addAttachment(java.io.InputStream,java.lang.String,java.lang.String).

    Headers such as Subject may be supplied by the template, by defining them using the VTL directive #set(). Only headers named in the DSpace configuration array property mail.message.headers will be added.

    Example: 

    
     ## This is a comment line which is stripped
     ##
     ## Parameters:   {0}  is a person's name
     ##               {1}  is the name of a submission
     ##
     #set($subject = 'Example e-mail')

     Dear ${params[0]},

     Thank you for sending us your submission "${params[1]}".

     --
     The ${config.get('dspace.name')} Team

    If the example code above was used to send this mail, the resulting mail would have the subject Example e-mail and the body would be: 

    

     Dear John,

     Thank you for sending us your submission "On the Testing of DSpace".

     --
     The DSpace Team

    There are two ways to load a message body. One can create an instance of Email and call setContent(java.lang.String,java.lang.String) on it, passing the body as a String. Or one can use the static factory method getEmail(java.lang.String) to load a file by its complete filesystem path. In either case the text will be loaded into a Velocity template.

    Author:
    Robert Tansley, Jim Downing - added attachment handling code, Adan Roman Ruiz at arvo.es - added inputstream attachment handling code

    • Constructor Detail

      • Email

        public Email()
        Create a new email message.

    • Method Detail

      • addRecipient

        public void addRecipient​(String email)
        Add a recipient.
        Parameters:
        email - the recipient's email address

      • setContent

        public void setContent​(String name,
                       String content)
        Set the content of the message. Setting this also "resets" the message formatting - addArgument will start over. Comments and any "Subject:" line must be stripped.
        Parameters:
        name - a name for this message body
        content - the content of the message

      • setSubject

        public void setSubject​(String s)
        Set the subject of the message.
        Parameters:
        s - the subject of the message

      • setReplyTo

        public void setReplyTo​(String email)
        Set the reply-to email address.
        Parameters:
        email - the reply-to email address

      • addArgument

        public void addArgument​(Object arg)
        Fill out the next argument in the template.
        Parameters:
        arg - the value for the next argument

      • addAttachment

        public void addAttachment​(File f,
                          String name)
        Add an attachment bodypart to the message from an external file.
        Parameters:
        f - reference to a file to be attached.
        name - a name for the resulting bodypart in the message's MIME structure.

      • addAttachment

        public void addAttachment​(InputStream is,
                          String name,
                          String mimetype)
        Add an attachment bodypart to the message from a byte stream.
        Parameters:
        is - the content of this stream will become the content of the bodypart.
        name - a name for the resulting bodypart in the message's MIME structure.
        mimetype - the MIME type of the resulting bodypart, such as "text/pdf". If null it will default to "application/octet-stream", which is MIME for "unknown format".

      • setCharset

        public void setCharset​(String cs)
        Set the character set of the message.
        Parameters:
        cs - the name of a character set, such as "UTF-8" or "EUC-JP".

      • reset

        public void reset()
        "Reset" the message. Clears the arguments, attachments and recipients, but leaves the subject and content intact.

      • send

        public void send()
          throws javax.mail.MessagingException,
                 IOException
        Sends the email. If the template defines a Velocity context property named among the values of DSpace configuration property mail.message.headers then that name and its value will be added to the message's headers.

        "subject" is treated specially: if setSubject() has not been called, the value of any "subject" property will be used as if setSubject had been called with that value. Thus a template may define its subject, but the caller may override it.

        Throws:
        javax.mail.MessagingException - if there was a problem sending the mail.
        IOException - if IO error

      • getEmail

        public static Email getEmail​(String emailFile)
                      throws IOException
        Get the VTL template for an email message. The message is suitable for inserting values using Apache Velocity.

        Note that everything is stored here, so that only send() throws a MessagingException.

        Parameters:
        emailFile - full name for the email template, for example "/dspace/config/emails/register".
        Returns:
        the email object, configured with subject and body.
        Throws:
        IOException - if IO error if the template couldn't be found, or there was some other error reading the template

      • main

        public static void main​(String[] args)
        Test method to send an email to check email server settings
        Parameters:
        args - command line arguments. The first is the path to an email template file; the rest are the positional arguments for the template. If there are no arguments, a short, plain test message is sent.