Jakarta Apache: MAILER JSP Tag Library
Version 1.0
Table of Contents
Overview
Requirements
Configuration
Tag Summary
Tag Reference
Examples
Javadocs
Revision History
Overview
This custom tag library is used to send e-mail.
E-mail can be sent in three ways. The first way requires the name of the SMTP
host to use. The second requires the name of a JNDI Resource for a JavaMail Session. The third requires the name of a JNDI Resource for a JavaMail MimePartDataSource. Refer to your servlet container documentation to determine which of these three methods you should use. During the creation of an e-mail message, the addresses are checked for the correct format. After the e-mail message has been created the send tag spawns a thread to send the message in the background so that the user does not have to wait for the SMTP host if it is busy.
<!-- Create a message by entering the name of the SMTP host. -->
<!-- The default for this attribute is localhost; for a host other -->
<!-- than localhost supply it's name with the server attribute -->
<!-- as in the example below. The body of the e-mail is supplied in the -->
<!-- message tag. The send tag is necessary to send the message. -->
<mt:mail server="home.net" to="foo@home.net"
from="bar@home.net" subject="mail taglib">
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
<!-- Using a JNDI named JavaMail Session object defined by the -->
<!-- session attribute. -->
<mt:mail session="java:comp/env/session" to="foo@home.net"
from="bar@home.net" subject="mail taglib">
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
<!-- Or using a JNDI named JavaMail MimePartDataSource object -->
<!-- defined by mimeMessage attribute. -->
<mt:mail mimeMessage="java:comp/env/message" to="foo@home.net"
from="bar@home.net" subject="mail taglib">
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
How e-mail is delivered depends on the JavaMail SMTP host settings. The JavaMail SMTP host can be configured by your Servlet Container so that bounced or undeliverable e-mails are returned to the sender by setting the folowing properties.
| Name |
Type |
Description |
| mail.smtp.dsn.notify |
String |
Property determines if the user will be notified of undeliverable mail. Either NEVER, or some combination of SUCCESS, FAILURE, and DELAY (separated by commas). |
| mail.smtp.dsn.ret |
String |
Determines what part of the undeliverable message will be returned in the message to the sender. Either FULL or HDRS. |
| mail.smtp.sendpartial |
boolean |
If set to true, and a message has some valid and some invalid
addresses, send the message anyway, reporting the partial failure with
a SendFailedException. If set to false (the default), the message is
not sent to any of the recipients if there is an invalid recipient
address.
|
This custom tag library requires a servlet container that supports the
JavaServer Pages Specification, version 1.1. JavaMail 1.2
and the JavaBeans Activation Framework should be installed as extensions to your JVM.
Configuration
Follow these steps to configure your web application with this tag library:
To use the tags from this library in your JSP pages, add the following
directive at the top of each page:
<%@ taglib uri="mailer.jar" prefix="mt" %>
where "mt" is the tag name prefix you wish to use for tags
from this library. You can change this value to any prefix you like. The prefix
mt is used in the examples below.
| Mailer Tags |
| mail |
Used to create an e-mail message. |
| message |
Used to set the body of the message. |
| header |
Used to set extra message headers. |
| setto |
Used to set one or more To addresses in the message. |
| addto |
Used to add one address at a time to the list of To addresses. |
| replyto |
Used to set one or more Reply-To addresses in the message. |
| from |
Used to set the From address of the message. |
| setcc |
Used to set one or more Cc addresses in the message. |
| addcc |
Used to add one address at a time to the list of Cc addresses. |
| setbcc |
Used to set one or more Bcc addresses in the message. |
| addbcc |
Used to add one address at a time to the list of Bcc addresses. |
| subject |
Used to set the subject of the message. |
| attach |
Used to add an attachment to an e-mail message.. |
| send |
Used to send the message. |
| error |
Used to get messages explaining errors that occurred in setting any of the addresses. |
| mail |
Availability: version 1.0 |
|
| Used to create an e-mail message. Most attributes set via a tag within the body of this tag will take precedence and override any value that was set as an attribute in this tag. In the case of the three add tags, however, an address set as an attribute will not be overridden, but will be the first address in the list. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
None |
| Attributes |
|
| |
| Name |
Required |
Runtime Expression Evaluation |
| authentication |
No |
No |
| A value of true of false tells the mailer taglib
if the mail server uses authentication. The default value is
false. If the value is set to true and the mail server uses
authentication the user will be prompted for a name and password
before the mail is sent. |
| |
| If none of the following three attributes is given
the tag will default to using localhost as the SMTP host. |
| |
| server |
No |
No |
| This attribute allows you to set the SMTP
host if it is going to be other than localhost. |
| session |
No |
No |
| This attribute allows a message to be created
using a predefined, JNDI named Session object. |
| mimeMessage |
No |
No |
| This attribute allows a message to be created
using a predefined, JNDI named MimePartDataSource. |
|
| |
| The following attributes can be set either as
attributes in the mail tag, or by the corresponding tags within
the body of the mail tag. |
| |
| to |
No |
No |
| The To address of the e-mail. Accepts a
comma separated list of addresses. |
| replyTo |
No |
No |
| The Reply-To address of the e-mail. Accepts
a comma separated list of addresses. |
| from |
No |
No |
| The From address of the e-mail. |
| cc |
No |
No |
| The Carbon Copy address of the e-mail. Accepts
a comma separated list of addresses. |
| bcc |
No |
No |
| The Blind Carbon Copy address of the e-mail.
Accepts a comma separated list of addresses. |
| subject |
No |
No |
| The Subject of the e-mail. |
|
|
| Properties |
None |
| Example |
<!-- Send a basic message: set the to, from, and subject attributes. -->
<!-- The server attribute is not set, therefore the default setting -->
<!-- of localhost will be used for the SMTP host. -->
<mt:mail to="foo@home.net" from="bar@home.net"subject="mail taglib">
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
|
Used to set the body of the message.
Message will appear as it is written, any carriage returns and spaces in the JSP will be present in the delivered message. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
|
| |
| Name |
Required |
Runtime Expression Evaluation |
| type |
No |
No |
| This attribute has two possible values text or html. If text
is selected the body of the message is just plain text (it has no html
tags within it). If html is selected then the body of the message can contain
HTML tags. The default value for this attribute is text. |
|
| Properties |
None |
| Example |
<!-- Send a basic message: set the to, from, and subject attributes. -->
<!-- The type attribute is not used in the message tag, it defaults -->
<!-- to text -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="mail taglib">
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
<!-- Send the same message only this time HTML tags are included in -->
<!-- the body of the message for formatting. -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="mail taglib">
<mt:message type="html">
[body of message containing html formatting]
</mt:message>
<mt:send/>
</mt:mail>
|
|
| header |
Availability: version 1.0 |
|
| Used to set extra headers in the message. See
Documentation for further information on other e-mail headers. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
|
| |
| Name |
Required |
Runtime Expression Evaluation |
| name |
Yes |
No |
| The name of the extra header to be set. |
| value |
No |
No |
| The value of the extra header to be set. This can also be placed in the body of the tag (see example). |
|
| Properties |
None |
| Example |
<!-- Set the header Precedence with the value as an attribute. -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="mail taglib">
<mt:header name="Precedence" value="bulk"/>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
<!-- Set the header Precedence with the value set in the body -->
<!-- of the tag. -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="mail taglib">
<mt:header name="Precedence">bulk</mt:header>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| setto |
Availability: version 1.0 |
|
| Used to set one or more To addresses in the message. Accepts a
comma separated list of addresses. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Set to in the e-mail started with the <mt:mail> -->
<!-- tag, to foo@home.net. -->
<mt:mail from="bar@home.net" subject="mailer taglib">
<mt:setto>foo@home.net</mt:setto>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
<!-- Set to in the e-mail started with the <mt:mail> tag, -->
<!-- to foo@home.net and geo@place.net. -->
<mt:mail from="bar@home.net" subject="mailer taglib">
<mt:setto>foo@home.net,geo@place.net</mt:setto>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| addto |
Availability: version 1.0 |
|
| Used to add one address at a time to the list of To addresses.
|
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Add geo@place.com to the list of to addresses started -->
<!-- in the the <mt:mail> tag. -->
<mt:mail to="foo@home.net" from="bar@home.net"
subject="mailer taglib">
<mt:addto>geo@place.com</mt:addto>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
|
|
| Used to set one or more Reply-To addresses in the message. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Set replyto in the e-mail started with the <mt:mail> -->
<!-- tag, to sax@home.net -->
<mt:mail to="foo@home.net" from="bar@home.net"
subject="mailer taglib">
<mt:replyto>sax@home.net</mt:replyto>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
<!-- Set replyto in the e-mail started with the <mt:mail> -->
<!-- tag, to sax@home.net and cur@blank.com -->
<mt:mail to="foo@home.net" from="bar@home.net"
subject="mailer taglib">
<mt:replyto>sax@home.net,cur@blank.com</mt:replyto>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| from |
Availability: version 1.0 |
|
| Used to set the From address of the message. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Set from in the e-mail started with the <mt:mail> tag, -->
<!-- to bar@home.net -->
<mt:mail>
<mt:setto>foo@home.net</mt:setto>
<mt:from>bar@home.net</mt:from>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| setcc |
Availability: version 1.0 |
|
| Used to set one or more Cc addresses in the message. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Set cc to "ay@home.net,aou@home.net,aei@home.net" -->
<!-- in the e-mail started with the <mt:mail> tag. -->
<mt:mail>
<mt:setto>foo@home.net</mt:setto>
<mt:from>bar@home.net</mt:from>
<mt:setcc>ay@home.net,aou@home.net,aei@home.net</mt:setcc>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| addcc |
Availability: version 1.0 |
|
| Used to add one address at a time to the list of Cc addresses.
|
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the sned tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Add aou@home.net and aei@home.net to the list of cc -->
<!-- addresses started in the <mt:mail> tag. -->
<mt:mail to="foo@home.net" from="bar@home.net"
cc="ay@home.net">
<mt:addcc>aou@home.net</mt:addcc>
<mt:addcc>aei@home.net</mt:addcc>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| setbcc |
Availability: version 1.0 |
|
| Used to set one or more Bcc addresses in the message. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Set bcc to "fur@home.net,fer@home.net,ayd@home.net" -->
<!-- in the e-mail started with the <mt:mail> tag. -->
<mt:mail>
<mt:setto>foo@home.net</mt:setto>
<mt:from>bar@home.net</mt:from>
<mt:setbcc>fur@home.net,ffer@home.net,ayd@home.net</mt:setbcc>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| addbcc |
Availability: version 1.0 |
|
| Used to add one address at a time to the list of Bcc addresses.
|
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Add fer@home.net and ayd@home.net to the list of bcc -->
<!-- addresses started in the <mt:mail> tag. -->
<mt:mail to="foo@home.net" from="bar@home.net"
bcc="fur@home.net">
<mt:addbcc>ffer@home.net</mt:addbcc>
<mt:addbcc>ayd@home.net</mt:addbcc>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| attach |
Availability: version 1.0 |
|
| Used to add an attachment to an e-mail message. It is possible
to add an attachment in one of three ways. First give the name of
the file that is to be added. Second give the URL that points to
the resource that is to be added. Third include the attachment
in the body of the attach tag, in this case it is necessary to
use the type attribute and give the mime type of the attachment.
|
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
|
| |
| Name |
Required |
Runtime Expression Evaluation |
| file |
No |
No |
| The name of the file to be included as an attachment. The name
of the file must be a path or file name realative to the root
directory of the web application. If the value of the file
attribute equals "" (it is left empty) the tag will extract the
name of the file from the body of the tag. |
| url |
No |
No |
| The URL of a resource to be included as an attachment. The URL
must be given as the full url like http://www.somedomain.com. If
the value of the url attribute equals "" (it is left empty) the
url will be extracted from the body of the tag.
|
| type |
No |
No |
| The mime type of the attachment that is included within the body
of the attach tag.. |
|
| Properties |
None |
| Example |
<!-- Add the file mail/duck.gif as an attachment -->
<!-- in the e-mail started with the <mt:mail> tag. -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="test">
<mt:message>[body of message]</mt:message>
<mt:attach file="mail/duck.gif"/>
<mt:send/>
</mt:mail>
<!-- Add the resource named by the following url -->
<!-- http://www.someplace.com/stuff.html as an attachment -->
<!-- in the e-mail started with the <mt:mail> tag. -->
<!-- Name the url in the body of the attach tag. -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="test">
<mt:message>[body of message]</mt:message>
<mt:attach url="">
http://www.someplace.com/stuff.html
</mt:attach>
<mt:send/>
</mt:mail>
<!-- Add the body of the attach tag as an attachment. When the -->
<!-- message comes "This is just a test" will be formatted with -->
<!-- the <h1> tags. -->
<mt:mail to="foo@home.net" from="bar@home.net" subject="test">
<mt:message>[body of message]</mt:message>
<mt:attach type="text/html">
<h1>This is just a test</h1>
</mt:attach>
<mt:send/>
</mt:mail>
|
|
|
|
| Used to set the subject in the message. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must occur before the send tag.
|
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Set subject to "learning about the mail tag library" -->
<!-- in the e-mail started with the <mt:mail> tag. -->
<mt:mail>
<mt:setto>foo@home.net</mt:setto>
<mt:from>bar@home.net</mt:from>
<mt:subject>learning about the mail tag library</mt:subject>
<mt:message>[body of message]</mt:message>
<mt:send/>
</mt:mail>
|
|
| send |
Availability: version 1.0 |
|
| Used to send the message. If an error occured while creating the e-mail message and it cannot be sent, the body of this tag will be output to the browser. It is within the body of this tag where the page author can include an error message if it is desired. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a mail tag.
Must be the last tag nested
within the mail tag. |
| Attributes |
None |
| Properties |
None |
| Example |
<!-- Send a message in which the following "An error has occurred, -->
<!-- please back up and check that the addresses you gave are in -->
<!-- the correct format" will be printed if an error occurs while -->
<!-- trying to put the message together. -->
<mt:mail to="foo@home.net" from="bar@home.net">
<mt:subject>learning about the mail tag library</mt:subject>
<mt:message>[body of message]</mt:message>
<mt:send>
An error has occurred, please back up and check that the
addresses you gave are in the correct format.
</mt:send>
</mt:mail>
|
|
| error |
Availability: version 1.0 |
|
| Used to get messages explaining errors that occurred in setting any of the addresses. |
| |
| Tag Body |
JSP |
| Script Variable |
No |
| Restrictions |
Must be nested within a send tag. |
| Attributes |
| Name |
Required |
Runtime Expression Evaluation |
| id |
Yes |
No |
| Script variable id for use with standard
jsp:getProperty tag |
|
| Properties |
| Name |
Get |
Set |
| error |
Yes |
No |
| The current error in the error list as a string. |
|
| Example |
<!-- Set text to be displayed if an error occurs when creating the -->
<!-- e-mail started with the <mt:mail> tag. The message will use -->
<!-- the error messages from the tag to be more specific as to the -->
<!-- errors encountered. -->
<mt:mail to="foo@home.net" from="bar@home.net">
<mt:subject>learning about the mail tag library</mt:subject>
<mt:message>[body of message]</mt:message>
<mt:send>
The following error(s) have occured:
<mt:error id="err">
<jsp:getProperty name="err" property="error"/>
</mt:error>
</mt:send>
</mt:mail>
|
|
See mail-examples.war for examples that use tags from this custom tag
library.
Java programmers can view the java class documentation for this tag library
as javadocs.
Review the complete revision history of this tag
library.
|