| 
 |   | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
  |
  +--sunlabs.brazil.template.Template
        |
        +--sunlabs.brazil.email.EmailTemplate
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 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 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 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 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 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).
 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 Filterthe chance to examine the HTTP
 response headers from the wrappedHandler, 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 | 
public EmailTemplate()
| Method Detail | 
public boolean shouldFilter(Request request,
                            MimeHeaders headers)
FilterFilter 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.
shouldFilter in interface Filterrequest - The in-progress HTTP request.headers - The MIME headers generated by the wrapped Handler.
true if this filter would like to examine and
		possibly rewrite the content, false otherwise.
public byte[] filter(Request request,
                     MimeHeaders headers,
                     byte[] content)
FilterHandler.
 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.
filter in interface Filterrequest - The finished HTTP request.headers - The MIME headers generated by the Handler.content - The output from the Handler that this
		Filter may rewrite.
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.public boolean init(RewriteContext hr)
Template
init in interface TemplateInterfaceinit in class Template
public boolean init(Server server,
                    String prefix)
Handler
init in interface Handlerserver - 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.
true if this Handler initialized
		successfully, false otherwise.  If
		false is returned, this Handler
		should not be used.
public boolean respond(Request request)
                throws IOException
Handler
respond in interface Handlerrequest - The Request object that represents the HTTP
		request.
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.
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.
public void tag_forcetimeout(RewriteContext hr)
public void tag_email(RewriteContext hr)
public void tag_folder(RewriteContext hr)
public void tag_message(RewriteContext hr)
public void tag_sendmail(RewriteContext hr)
public void tag_slash_sendmail(RewriteContext hr)
public void tag_part(RewriteContext hr)
public boolean done(RewriteContext hr)
done in interface TemplateInterfacedone in class Template| 
 | Version 2.1, Generated 12/30/04 Copyright (c) 2001-2004, Sun Microsystems. | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||