sunlabs.brazil.email
Class EmailTemplate

java.lang.Object
  sunlabs.brazil.template.Template
      sunlabs.brazil.email.EmailTemplate (view source)

All Implemented Interfaces:

Filter, Handler, TemplateInterface

public class EmailTemplate
extends Template
implements Filter

The EmailTemplate takes an HTML document with embedded "Email" markup tags in it and evaluates those special tags to produce resulting properties that allow email reading/composing functionality to be embedded within the document.

The email functionality is implemented using four tags:

• <email>
• <folder>
• <message>
• <sendmail>

The <email> tag handles 'state control'. The <folder> tag provides a means to manipulate mail folders. The <message> tag provides viewing capabilities for email messages. The <sendmail> tag allows outgoing messages to be sent via SMTP. There is an additional tag (<forcetimeout>) that is used mainly for debugging.

<email> TAG

The <email> tag provides 'state control' for the connection to the email server. It handles opening and closing the connection, as well as providing authentication parameters to the server. The general format of the <email> tag is as follows:

 <email server=servername user=username password=userpassword 
  action=[open,close] onError="somefile.html" connhandle=xyz>

The connhandle parameter is optional, and is used to be able to identify a unique server connection if more than one <email> tag is present in an HTML page (for example, an email client that connects to more than one email server to retrieve messages). The connhandle parameter is also used as the prefix for properties returned from this and all of the email tags. See PropsTemplate for more information on the <property> tag. If no connhandle is present, the properties returned are prefixed with the identifier used for the EmailTemplate in the configuration file. The string prefix will be used throughout this document to refer to this prepended string.

Note that although server, user, and password are not listed as optional, they can be left out after their first use. For example, after performing an action=open command, the connection to the server can be closed with the following command:

 <email action=close>
 

The onError parameter is also optional, but if present, will give a location that the HTML client expects to be redirected to in case of a fatal error within the processing for this tag. In an error condition, this parameter does an implicit abort on all further processing of the HTML page.

<folder> TAG

The <folder> tag provides functionality necessary to manipulate email folders. It allows for the selection of a particular folder, listing of all folders within a folder directory, as well as for other utility functions. The general format of the <folder> tag is as follows:

 <folder dir=/xyz foldername=[INBOX,anyfoldername] 
  action=[list,purge,msgcount,create,delete] onError="somefile.html" 
  connhandle=xyz>

The onError parameter is optional, but if present, will give a location that the HTML client expects to be redirected to in case of a fatal error within the processing for this tag. In an error condition, this parameter does an implicit abort on all further processing of the HTML page.

The connhandle parameter is also optional, and its use is specified in the documentation for the <email> tag.

The dir parameter is used to establish a base directory where a user's email folders reside. For example, on some UNIX systems, this is /home/username/Mail.

The foldername parameter is used to specify a foldername to operate on for the various operations (except action=list).

The action=list operation will create a list all mail folders within the directory specified by dir. This list is returned in property: prefix.folders - where each folder is delimited by the delim character, which defaults to "/". An optional glob attribute restircts the folders to those matching the glob pattern.

The action=msgcount operation returns the total count of messages and the count of new messages in the selected folder in the following properties:

prefix.totalmsgcount
prefix.newmsgcount

This operation works on either a specified folder name (if provided), or the last selected folder.

The action=create operation creates a new folder with the name given. The name of the folder is required, but the dir parameter is optional. If not specified, the current default directory will be used as the root location of the new folder.

The action=delete operation deletes the named folder. The name of the folder is required, but the dir parameter is optional. If not given, the tag assumes that the folder to be deleted is located in the default directory.

<message> TAG

The <message> tag is the workhorse of the Brazil email suite. It provides the ability to get message header listings, and to retrieve/delete/refile individual messages and their attachments. The general format of the <message> tag is as follows:

 <message action=[getheaders,getnewheaders,getmsg,deletemsg,undeletemsg,refilemsg] 
  startmsg=nnn msglimit=nnn msgnum="n n n" headerlist="From, To, Date"
  foldername=xyz refilefolder=xyz onError="somefile.html" connhandle=xyz>

The onError parameter is optional, but if present, will give a location that the HTML client expects to be redirected to in case of a fatal error within the processing for this tag. In an error condition, this parameter does an implicit abort on all further processing of the HTML page.

The connhandle parameter is also optional, and its use is specified in the documentation for the <email> tag.

The foldername parameter is required for all operations, so that multiple open folders can be supported in seperate browser windows.

The action=getheaders operation uses the headerlist parameter to determine which header values to retrieve for each message. The header names in this list are case-sensitive. If headerlist isn't present, ALL headers will be retrieved. This operation takes the optional parameters msglimit and/or startmsg. If msglimit is specified without startmsg, the headers returned will be the last msglimit number.

The action=getnewheaders operation takes all of the same parameters as the action=getheaders operation, except msglimit, and returns values in the same properties listed below. As its name suggests, however, it only returns header information for the newly arrived messages in the folder.

The header listing information is returned in the following properties:

prefix.n.msgnum - where 'n' = 1,2,3... (this is the msg number as defined by the mail server)

prefix.n.msgstatus (this is either a 'U' for unread, an 'N' for new, a 'R' for read, or a 'D' for deleted)

prefix.n.Headername - where 'Headername' = one of the header names returned or one of those within the headerlist parameter (for example prefix.1.From)

prefix.n.Headername.n - where 'Headername' = one of the header names returned or one of those within the headerlist parameter and 'n' = msg number. (This format is only returned for headers that occur multiple times in an email message with unique values (such as 'Received'). Also returned in this case is a property named: prefix.n.Headername.count which contains the enumerated count of the multivalue header.

prefix.n.[To,From,Cc] - This is a special case property that returns a comma seperated list of rfc822 style (user@domain) addresses for the particular header (To,From,Cc) that is used to name the property.

prefix.n.[To,From,Cc].address.n - This is a special case property that is returned for headers that are used for addresses (To,From,Cc). This property contains the rfc822 'user@domain' portion of the header. Since it is a multivalue header, (like Received), it also has a count portion (the last 'n') representing an enumeration of which address it was in the header (e.g. '0 1 2').

prefix.n.[To,From,Cc].personal.n - This is a special case property that corresponds to the 'address' property above. It contains the 'Joe A. User' portion of the address. It is also a multivalue property like address. Also returned in these cases is a property named: prefix.n.To.count which contains the enumerated count of the multivalue header (To,From,Cc).

prefix.n.Date - This is a special case property that returns the message sent date as a string representation.

prefix.n.Datestamp - This is a special case property that returns the message sent date as a string representation of the number of seconds elapsed since the epoch (Jan 1, 1970). This is useful in providing additional formatting via the Brazil DateTemplate.

Both of the above properties are returned for every 'Date' header requested in the action=getheaders operation.

prefix.n.msgindex (this contains a list of the msg numbers - for example '1 2 3 4 ...' - this is useful in iterating over the properties returned here with the BSLTemplate <foreach> tag)

The action=getmsg operation requires the msgnum parameter and returns the following properties:

prefix.msgnum (contains the message number)

prefix.n.Headername - where 'Headername' = one of the names within the headerlist parameter and 'n' represents the msgnum (multi-value headers like 'Received' are handled in the same manner as described above for action=getheaders).

prefix.n.body (contains the text of the email msg (if available))

prefix.n.msgmimetype (contains the string that specifies what MIME type the message is - useful for deciding if you'll need to convert plaintext to HTML before displaying it)

prefix.n.j.partname - where 'n' is the msgnum, and 'j' is a part number (for multipart messages/attachments) (this contains the text string name of the multipart attachment)

prefix.n.j.parturl - where 'n' is the msgnum, and 'j' is a part number (for multipart messages/attachments) (this contains the URL that is needed to retrieve the multipart attachment - this URL can be used in an <href> or <form> tag)

prefix.n.partcount (this contains a list of the part numbers and is useful for iterating over the parts properties with the BSLTemplate <foreach> tag)

The action=deletemsg and action=undeletemsg operations requires the msgnum parameter, which can contain either a single message number or a space seperated list (e.g. '1 2 3 4') of numbers.

The action=refilemsg operation requires the msgnum and refilefolder parameters. The value of refilefolder is a relative path from the dir parameter value provided in the <folder> tag. The msgnum parameter here can also accept a space seperated list (as in the action=deletemsg tag).

<sendmail> TAG

The <sendmail> tag provides the ability to send outgoing email messages using the SMTP protocol. The simplest form of the <sendmail> tag is as follows:

 <sendmail to=user@domain cc=user@domain bcc=user@domain from=user@domain subject="test subject" 
  body="msg text" onError="somefile.html" connhandle=xyz>

This form of the tag provides basic functionality (no attachments) to send simple messages. The complete form of the tag is as follows:

 <sendmail to=user@domain cc=user@domain from=user@domain subject="test subject" 
  body="msg text" onError="somefile.html" connhandle=xyz>
     <part body=partdata name=bodypartfilename encoding=none|qp|base64
      content-type=mimetype>
     <part ....>
 </sendmail>
 

This form of the tag allows attachments to be added to outgoing messages (via the <part> tag. The <part> tag requires parameters for the actual data for each part, a filename (optional), an encoding type and a content-type (optional).

The onError parameter is optional, but if present, will give a location that the HTML client expects to be redirected to in case of a fatal error within the processing for this tag. In an error condition, this parameter does an implicit abort on all further processing of the HTML page.

The connhandle parameter is also optional, and its use is specified in the documentation for the <email> tag.

The cc parameter is also optional.

The from, subject, and body parameters should all be set to their respective values.

In the event of an error during an attempt to send a message (as denoted by a 'mailError' property being set (see Error Handling)), the following property will be set:

prefix.sendmailerror - contains the specific reason that the sending of this message failed.

<forcetimeout> TAG

This tag provides the ability to 'force' a timeout of the connection to the email server. It is generally only used for debugging purposes. The complete form of the tag is as follows:

 <forcetimeout connhandle=xyz>
 

The connhandle parameter is also optional, and its use is specified in the documentation for the <email> tag.

After this tag is processed, calls to any of the other tags will result in errors being generated (see Error Handling below).

Error Handling

In the case of a fatal error (one that requires re-authentication with the email server) during any email operation, the following property is set (unless you used the per tag 'onError' parameter for error handling):

prefix.fatalMailError - this contains a string with the error message returned from the email server.

Some non-fatal errors may be returned during the processing of any of the tags and these are returned in the following property (note that these are returned regardless of the existence of the 'onError' parameter in a particular tag):

prefix.mailError - this contains a string with the non-fatal error message returned from the email server.

Field Summary

Fields inherited from class sunlabs.brazil.template.Template

debug

Constructor Summary

EmailTemplate()

Method Summary

boolean	done(RewriteContext hr) If we run off the end of the page, but there is email pending to be sent, send it anyway.
byte[]	filter(Request request, MimeHeaders headers, byte[] content) Filters the content generated by the wrapped Handler.
boolean	init(RewriteContext hr) Called before this template processes any tags.
boolean	init(Server server, String prefix) Initializes the handler.
boolean	respond(Request request) Responds to an HTTP request.
boolean	shouldFilter(Request request, MimeHeaders headers) Gives this Filter the chance to examine the HTTP response headers from the wrapped Handler, before the content has been retrieved.
void	tag_email(RewriteContext hr) Handles the <email> tag.
void	tag_folder(RewriteContext hr) Handles the <folder> tag.
void	tag_forcetimeout(RewriteContext hr) The <forcetimeout> tag will cause an immediate timeout of the connection to the email server.
void	tag_message(RewriteContext hr) Handles the <message> tag.
void	tag_part(RewriteContext hr) Handles the <part> tag.
void	tag_sendmail(RewriteContext hr) Handles the <sendmail> tag.
void	tag_slash_sendmail(RewriteContext hr) Handles the </sendmail> tag.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EmailTemplate

public EmailTemplate()

Method Detail

shouldFilter

public boolean shouldFilter(Request request,
                            MimeHeaders headers)

Description copied from interface: Filter

Gives this Filter the chance to examine the HTTP response headers from the wrapped Handler, before the content has been retrieved.

If this Filter does want to examine and possibly rewrite the content, it should return true; once the content is available, the filter method will be invoked. For instance, if this Filter is only interested in rewriting "text/html" pages, it should return false if the "Content-Type" is "image/jpeg". If all filters return false for the shouldFilter method, the FilterHandler can switch to a more effient mechanism of delivering content to the client.

The MIME headers may also be modified by this Filter, for instance, to change the "Content-Type" of a web page. The "Content-Length" will automatically be computed.

Specified by:

shouldFilter in interface Filter

Parameters:

request - The in-progress HTTP request.

headers - The MIME headers generated by the wrapped Handler.

Returns:

true if this filter would like to examine and possibly rewrite the content, false otherwise.

filter

public byte[] filter(Request request,
                     MimeHeaders headers,
                     byte[] content)

Description copied from interface: Filter

Filters the content generated by the wrapped Handler. The content may be arbitrarily rewritten by this method.

The MIME headers may also be modified by this Filter, for instance, to change the "Content-Type" of a web page. The "Content-Length" will automatically be computed by the FilterHandler.

Specified by:

filter in interface Filter

Parameters:

request - The finished HTTP request.

headers - The MIME headers generated by the Handler.

content - The output from the Handler that this Filter may rewrite.

Returns:

The rewritten content. The Filter may return the original content unchanged. The Filter may return null to indicate that the FilterHandler should stop processing the request and should not return any content to the client.

init

public boolean init(RewriteContext hr)

Description copied from class: Template

Called before this template processes any tags.

Specified by:

init in interface TemplateInterface

Overrides:

init in class Template

init

public boolean init(Server server,
                    String prefix)

Description copied from interface: Handler

Initializes the handler.

Specified by:

init in interface Handler

Parameters:

server - The HTTP server that created this Handler. Typical Handlers will use Server.props to obtain run-time configuration information.

prefix - The handlers name. The string this Handler may prepend to all of the keys that it uses to extract configuration information from Server.props. This is set (by the Server and ChainHandler) to help avoid configuration parameter namespace collisions.

Returns:

true if this Handler initialized successfully, false otherwise. If false is returned, this Handler should not be used.

respond

public boolean respond(Request request)
                throws IOException

Description copied from interface: Handler

Responds to an HTTP request.

Specified by:

respond in interface Handler

Parameters:

request - The Request object that represents the HTTP request.

Returns:

true if the request was handled. A request was handled if a response was supplied to the client, typically by calling Request.sendResponse() or Request.sendError.

Throws:

IOException - if there was an I/O error while sending the response to the client. Typically, in that case, the Server will (try to) send an error message to the client and then close the client's connection.

The IOException should not be used to silently ignore problems such as being unable to access some server-side resource (for example getting a FileNotFoundException due to not being able to open a file). In that case, the Handler's duty is to turn that IOException into a HTTP response indicating, in this case, that a file could not be found.

tag_forcetimeout

public void tag_forcetimeout(RewriteContext hr)

The <forcetimeout> tag will cause an immediate timeout of the connection to the email server. This tag is mainly intended for debugging.

tag_email

public void tag_email(RewriteContext hr)

Handles the <email> tag.

tag_folder

public void tag_folder(RewriteContext hr)

Handles the <folder> tag.

tag_message

public void tag_message(RewriteContext hr)

Handles the <message> tag.

tag_sendmail

public void tag_sendmail(RewriteContext hr)

Handles the <sendmail> tag.

tag_slash_sendmail

public void tag_slash_sendmail(RewriteContext hr)

Handles the </sendmail> tag.

tag_part

public void tag_part(RewriteContext hr)

Handles the <part> tag.

done

public boolean done(RewriteContext hr)

If we run off the end of the page, but there is email pending to be sent, send it anyway. Also, check to see if we have pending message refiles that need to happen.

Specified by:

done in interface TemplateInterface

Overrides:

done in class Template