Collaboration API Documentation

com.filenet.bso.api.collaboration
Class EmailNotification

java.lang.Object
  |
  +--com.filenet.bso.api.collaboration.EmailNotification

public class EmailNotification
extends java.lang.Object

The EmailNotification class allows template-controlled email messages to be sent to a number of recipients. The message can be customized according to the language, country and time zone of each recipient.

The following code describes how an email message may be issued:

      // set up parameters for template

      HashMap params = new HashMap();
      params.put("doc", doc);
      params.put("folder", folder);
      params.put("time", time());

      EmailNotification en = new EmailNotification(store, teamspace, null);
      // set the To and Cc recipients

      en.addToRecipient(new InternetAddress(user1.email), user1.locale, user1.timeZone);
      en.addToRecipient(new InternetAddress(user2.email), user2.locale, user2.timeZone);

      en.addCcRecipient(new InternetAddress(user3.email), user3.locale, user3.timeZone);

      // send the email

      en.send("mytemplate", params, new InternetAddress(fromuser.email), fromuser.displayName,
              null);
 

This example assumes email address and other basic information (such as the fromuser's display name) have been established.

Locale and time zone information are not required; if not provided, the server's locale and time zone are used.

Normally, the locale affects which localized template file is selected. While the locale and the time zone affect some formatting, certain installations may all be in the same locale and time zone, or the template might be written in such a way that this is not significant.

For efficiency, this class automatically groups recipients by locale information and provides a means of issuing multiple email messages with a single send method call.

Note: A single message is issued to a recipient who appears more than once in either the "To" or "CC" (carbon copy) lists (provided each appearance indicates the same locale and time zone). However, if the same recipient is added just once to the "To" list and once to the "CC" list, two messages are issued.


Constructor Summary
EmailNotification(com.filenet.wcm.api.ObjectStore store, Teamspace teamspace, java.lang.String applicationID)
          Construct EmailNotification instances with a teamspace that will be used to queue message(s) to be asynchronously sent by the Collaboration Engine.
EmailNotification(com.filenet.wcm.api.ObjectStore store, filenet.vw.api.VWSession vwSession, java.lang.String applicationID)
          Construct EmailNotification instances with a VWSession that will be used to send the email out immediately.
 
Method Summary
 void addCcRecipient(javax.mail.internet.InternetAddress address)
          Add a new recipient "CC" (carbon copy) address to the list of recipients for this notification.
 void addCcRecipient(javax.mail.internet.InternetAddress address, java.util.Locale locale, java.util.TimeZone timeZone)
          Add a new recipient "CC" (carbon copy) address to the list of recipients for this notification.
 void addToRecipient(javax.mail.internet.InternetAddress address)
          Add a new recipient "To" address to the list of recipients for this notification.
 void addToRecipient(javax.mail.internet.InternetAddress address, java.util.Locale locale, java.util.TimeZone timeZone)
          Add a new recipient "To" address to the list of recipients for this notification.
 void clearRecipients()
          Clear the list of recipients and allow this instance of EmailNotification to be reused.
 java.lang.String getApplicationID()
          Return the current application ID.
 java.lang.String getEmailHost()
          Return the email host.
 boolean getIsDebug()
          Return true if debugging mode is currently set.
static void logMail(javax.mail.internet.MimeMessage msg)
          Log the mail message.
 void send(int templateCode, java.util.Map parameters, javax.mail.internet.InternetAddress from, java.lang.String fromName, java.lang.String subject)
          Send the notification using a template code reference.
 void send(java.lang.String templateName, java.util.Map parameters, javax.mail.internet.InternetAddress from, java.lang.String fromName, java.lang.String subject)
          Send the notification using a named template.
 void setApplicationID(java.lang.String applicationID)
          Set the application ID, which is used to look up the correct template and to find localized versions of the same application to enable locale lookups.
 void setIsDebug(boolean isDebug)
          Set or clear debugging mode.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EmailNotification

public EmailNotification(com.filenet.wcm.api.ObjectStore store,
                         Teamspace teamspace,
                         java.lang.String applicationID)
Construct EmailNotification instances with a teamspace that will be used to queue message(s) to be asynchronously sent by the Collaboration Engine.
Parameters:
store - The object store in which collaboration email information can be found.
teamspace - The teamspace with which this message is associated. This is used when queuing the message for asynchronous sending by the Collaboration Engine.
applicationID - The name of the application. This is also used to locate localized versions of the application. If null, the current application ID of the teamspace is used.

EmailNotification

public EmailNotification(com.filenet.wcm.api.ObjectStore store,
                         filenet.vw.api.VWSession vwSession,
                         java.lang.String applicationID)
Construct EmailNotification instances with a VWSession that will be used to send the email out immediately. This should only be used by the Collaboration Engine code.
Parameters:
store - The object store where collaboration email information can be found
vwSession - A valid VWSession, which will be used to connect to the email server.
applicationID - The name of the application. This is also used to locate localized versions of the application. If null, the application ID of the object store's JavaAPI session is used.
Method Detail

getEmailHost

public java.lang.String getEmailHost()
Return the email host. This value is only valid after at least one message has been sent.
Returns:
The value used for the email host.

getApplicationID

public java.lang.String getApplicationID()
Return the current application ID.
Returns:
The application ID.

setApplicationID

public void setApplicationID(java.lang.String applicationID)
Set the application ID, which is used to look up the correct template and to find localized versions of the same application to enable locale lookups. This also gets the group of this appID, as well as the default time zone. If the appID is null, the appID of the object store's JavaAPI session is used instead.
Parameters:
applicationID - The new application ID to use.

getIsDebug

public boolean getIsDebug()
Return true if debugging mode is currently set.
Returns:
true if in debugging mode, false otherwise.

setIsDebug

public void setIsDebug(boolean isDebug)
Set or clear debugging mode.
Parameters:
isDebug - If true, debugging mode is set; false resets it.

addToRecipient

public void addToRecipient(javax.mail.internet.InternetAddress address)
Add a new recipient "To" address to the list of recipients for this notification. The locale and time zone for this recipient are assumed to be the same as those on the server. This method may be called as often as needed for multiple "To" recipients.
Parameters:
address - The address of the recipient.

addToRecipient

public void addToRecipient(javax.mail.internet.InternetAddress address,
                           java.util.Locale locale,
                           java.util.TimeZone timeZone)
Add a new recipient "To" address to the list of recipients for this notification. The locale and time zone for this recipient are also specified. This method may be called as often as needed for multiple "To" recipients.
Parameters:
address - The address of the recipient.
locale - The locale (language and country) of the recipient. This is used to select the template for the correct locale and affects some formatting to customize the message for the recipient.
timeZone - The time zone of the recipient. This is used in time/date formatting to customize the message for the recipient.

addCcRecipient

public void addCcRecipient(javax.mail.internet.InternetAddress address)
Add a new recipient "CC" (carbon copy) address to the list of recipients for this notification. The locale and time zone for this recipient are assumed to be the same as those on the server. This method may be called as often as needed for multiple "CC" recipients.
Parameters:
address - The address of the recipient.

addCcRecipient

public void addCcRecipient(javax.mail.internet.InternetAddress address,
                           java.util.Locale locale,
                           java.util.TimeZone timeZone)
Add a new recipient "CC" (carbon copy) address to the list of recipients for this notification. The locale and time zone for this recipient are also specified. This method may be called as often as needed for multiple "CC" recipients.
Parameters:
address - The address of the recipient.
locale - The locale (language and country) of the recipient. This is used to select the template for the correct locale and affects some formatting to customize the message for the recipient.
timeZone - The time zone of the recipient. This is used in time/date formatting to customize the message for the recipient.

clearRecipients

public void clearRecipients()
Clear the list of recipients and allow this instance of EmailNotification to be reused.

send

public void send(int templateCode,
                 java.util.Map parameters,
                 javax.mail.internet.InternetAddress from,
                 java.lang.String fromName,
                 java.lang.String subject)
          throws TemplateException
Send the notification using a template code reference. This sends a separate, customized notification for each batch of recipients in the same locale and time zone. Prior to calling this method, you should call addToRecipient and addCcRecipient as many times as necessary for all recipients of this notification.
Parameters:
templateCode - The code of the template to use. The actual template name is retrieved from a map in the configuration.
parameters - The named parameters to use in template substitutions. May be null.
from - The email address of the sender. May be null.
fromName - The display name of the sender. May be null.
subject - The default subject line of this notification (if a subject is not provided by the template). May be null if the template provides a subject.

send

public void send(java.lang.String templateName,
                 java.util.Map parameters,
                 javax.mail.internet.InternetAddress from,
                 java.lang.String fromName,
                 java.lang.String subject)
          throws TemplateException
Send the notification using a named template. This sends a separate, customized notification for each batch of recipients in the same locale and time zone. Prior to calling this method, you should call addToRecipient and addCcRecipient as many times as necessary for all recipients of this notification.
Parameters:
templateName - The name of the template to use.
parameters - The named parameters to use in template substitutions. May be null.
from - The email address of the sender. May be null.
fromName - The display name of the sender. May be null.
subject - The default subject line of this notification (if a subject is not provided by the template). May be null if the template provides a subject.

logMail

public static void logMail(javax.mail.internet.MimeMessage msg)
Log the mail message. This will log the message and is meant to be used internally.
Parameters:
msg - the mail message

Collaboration API Documentation

Copyright © 2002 - 2004 FileNet Corporation. All rights reserved.