You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by qu...@apache.org on 2003/03/10 07:31:46 UTC
cvs commit: jakarta-commons-sandbox/email/xdocs index.xml navigation.xml examples.xml
quintonm 2003/03/09 22:31:46
Added: email/xdocs index.xml navigation.xml examples.xml
Log:
Initial version of the docs for commons-email
Revision Changes Path
1.1 jakarta-commons-sandbox/email/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Home</title>
<author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
<author email="quintonm@apache.org">Quinton McCombs</author>
<revision>$Id: index.xml,v 1.1 2003/03/10 06:31:46 quintonm Exp $</revision>
</properties>
<body>
<section name="Overview">
<p>
This package provides a simplified way to send email than using the
JavaMail API directly. Some of the mail classes that are provided
are as follows:
<ol>
<li>
<b>SimpleEmail</b> - This class is used to send basic text based
emails.
</li>
<li>
<b>MultiPartEmail</b> - This class is used to send multipart
messages. This allows a text message with attachments either
inline or attached.
</li>
<li>
<b>HtmlEmail</b> - This class is used to send HTML formatted emails.
It has all of the capabilities as MultiPartEmail allowing
attachments to be easily added. It also supports embedded images.
</li>
<li>
<b>EmailAttachment</b> - This is a simple container class to allow
for easy handling of attachments. It is for use with
instances of MultiPartEmail and HtmlEmail.
</li>
</ol>
</p>
<p>
See the javadocs for more information on how to use these classes.
</p>
<p>
See the <a href="downloads.html">downloads</a> page for information
on obtaining releases.
</p>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/email/xdocs/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Commons - Email"
href="http://jakarta.apache.org/commons-snadbox/email/">
<title>Commons Email</title>
<!--
Note: Per the .vsl file, "/site" links will be prefixed with "http://jakarta.apache.org/site"
Other links starting with "/" become "./...".
-->
<body>
<menu name="Home">
<item name="Jakarta Commons" href="http://jakarta.apache.org/commons/index.html" />
<item name="Commons Email" href="/index.html" />
</menu>
<menu name="Information">
<item name="API Documentation" href="/apidocs/index.html"/>
<item name="Examples" href="/examples.html"/>
</menu>
<menu name="Project Files">
<item name="Releases" href="/downloads.html"/>
<item name="Source (Browse)" href="http://cvs.apache.org/viewcvs/jakarta-commons/pool/"/>
<item name="Source (CVS)" href="http://jakarta.apache.org/site/cvsindex.html"/>
</menu>
<menu name="Administrivia">
<item name="License" href="http://jakarta.apache.org/commons/license.html"/>
</menu>
</body>
</project>
1.1 jakarta-commons-sandbox/email/xdocs/examples.xml
Index: examples.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Examples</title>
<author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
<author email="quintonm@apache.org">Quinton McCombs</author>
<revision>$Id: examples.xml,v 1.1 2003/03/10 06:31:46 quintonm Exp $</revision>
</properties>
<body>
<section name="A simple text email">
<p>
Our first example will create a basic email message to "John Doe" and
send it through your local mail server.
</p>
<source>
<![CDATA[
SimpleEmail email = new SimpleEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("Test message");
email.setMsg("This is a simple test of commons-email");
email.send();
]]>
</source>
<p>
The call to setHostName("mail.myserver.com") sets the address of the
outgoing SMTP server that will be used to send the message. If this is
not set, the system property "mail.host" will be used.
</p>
</section>
<section name="Sending emails with attachments">
<p>
To add attachments to an email, you will need to use the MultiPartEmail
class. This class works just like SimpleEmail except that it adds
several overloaded attach() methods to add attachments to the email.
You can add an unlimited number of attachments either inline or
attached. The attachments will be MIME encoded.
</p>
<p>
The simpliest way to add the attachments is by using the EmailAttachment
class to reference your attachments.
</p>
<p>
In the following exmaple, we will create an attachment for a picture.
We will then attach the picture to the email and send it.
</p>
<source>
<![CDATA[
// Create the attachment
EmailAttachment attachment = new EmailAttachment();
attachment.setPath("mypictures/john.jpg");
attachment.setDisposition(EmailAttachment.ATTACHMENT);
attachment.setDescription("Picture of John");
attachment.setName("John");
// Create the email message
MultiPartEmail email = new MultiPartEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("The picture");
email.setMsg("Here is the picture you wanted");
// add the attachment
email.attach(attachment);
// send the email
email.send();
]]>
</source>
<p>
You can also use EmailAttachment to reference any valid URL for files
that you do not have locally. When the message is sent, the file will
be downloaded and attached to the message automatically.
</p>
<p>
The next example shows how we could have sent the apache logo
to John instead.
</p>
<source>
<![CDATA[
// Create the attachment
EmailAttachment attachment = new EmailAttachment();
attachment.setURL(new URL("http://www.apache.org/images/asf_logo_wide.gif"));
attachment.setDisposition(EmailAttachment.ATTACHMENT);
attachment.setDescription("Apache logo");
attachment.setName("Apache logo");
// Create the email message
MultiPartEmail email = new MultiPartEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("The logo");
email.setMsg("Here is Apache's logo");
// add the attachment
email.attach(attachment);
// send the email
email.send();
]]>
</source>
</section>
<section name="Sending HTML formatted email">
<p>
Sending HTML formatted email is accomplished by using the HtmlEmail
class. This class works exactly like the MultiPartEmail class with
additional methods to set the html content, alternative text content
if the reciepient does not support HTML email, and add inline images.
</p>
<p>
In this exmaple, we will send an email message with formatted HTML
content with an inline image.
</p>
<source>
<![CDATA[
// Create the email message
HtmlEmail email = new HtmlEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("Test email with inline image");
// embed the image and get the content id
URL url = new URL("http://www.apache.org/images/asf_logo_wide.gif");
String cid = email.embed(url, "Apache logo");
// set the html message
email.setHtmlMsg("<html>The apache logo - <img src=\"cid:"+cid+"\"></html>");
// set the alternative message
email.setTextMsg("Your email client does not support HTML messages");
// send the email
email.send();
]]>
</source>
<p>
First, notice that the call to embed() returns a String. This String
is a randomly generated identifier that must be used to reference
the image in the image tag.
</p>
<p>
Next, there was no call to setMsg() in this example. The method is
still available in HtmlEmail but it should not be used if you will be
using inline images. Instead, the setHtmlMsg() and setTextMsg()
methods were used.
</p>
</section>
<section name="Debugging">
<p>
The JavaMail API supports a debugging option that will can be very
useful if you run into problems. You can activate debugging on any
of the mail classes by calling setDebug(true). The debugging output
will be written to <code>System.out</code>.
</p>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org