Package org.dspace.core

Class Email

java.lang.Object
org.dspace.core.Email
public class Email extends Object
Builder 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(java.lang.Object) 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 Details

    • Email

      public Email()
      Create a new email message.

  • Method Details

    • 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. If null, a zero-length string is substituted.

    • 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 jakarta.mail.MessagingException, IOException
      Sends the email. If sending is disabled then the assembled message is logged instead.
      Throws:
      jakarta.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.