diff --git a/helma/Mail.js b/helma/Mail.js
index 93e7805e..346b93e9 100644
--- a/helma/Mail.js
+++ b/helma/Mail.js
@@ -6,19 +6,43 @@
* compliance with the License. A copy of the License is available at
* http://adele.helma.org/download/helma/license.txt
*
- * Copyright 1998-2006 Helma Software. All Rights Reserved.
+ * Copyright 1998-2007 Helma Software. All Rights Reserved.
*
* $RCSfile: Mail.js,v $
* $Author: hannes $
- * $Revision: 1.3 $
- * $Date: 2006/06/28 20:06:03 $
+ * $Revision: 1.4 $
+ * $Date: 2006/11/27 12:47:04 $
*/
+/**
+ * Define the global namespace if not existing
+ */
if (!global.helma) {
global.helma = {};
}
+/**
+ * Mail client enabling you to send e-mail via SMTP using Packages.javax.mail.
+ *
+ * A mail client object is created by using the helma.Mail()
+ * constructor. The mail object then can be manipulated and sent
+ * using the methods listed below.
+ *
+ * You will either need to set your mail server via the smtp
+ * property in the app.properties or server.properties file
+ * or pass the hostname of the mail server you want to use as a
+ * parameter to the constructor.
+ *
+ * Note: Make sure that the SMTP server itself is well-configured,
+ * so that it accepts e-mails coming from your server and does
+ * not deny relaying. Best and fastest configuration is of course
+ * if you run your own SMTP server (e.g. postfix) which might be
+ * a bit tricky to set up, however.
+ *
+ * @param {String} smtp as String, the hostname of the mail server
+ * @constructor
+ */
helma.Mail = function(smtp) {
var OK = 0;
var SUBJECT = 10;
@@ -98,8 +122,25 @@ helma.Mail = function(smtp) {
return;
};
+ /**
+ * The status of this Mail object.
+ */
this.status = OK;
-
+
+ /**
+ * Sets the sender of an e-mail message.
+ *
+ * The first argument specifies the receipient's
+ * e-mail address. The optional second argument
+ * specifies the name of the recipient.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.setFrom("tobi@helma.at", "Tobi Schaefer");
+ *
+ * @param {String} addstr as String, sender email address
+ * @param {String} name as String, optional sender name
+ */
this.setFrom = function(addstr, name) {
try {
if (addstr.indexOf("@") < 0) {
@@ -118,7 +159,16 @@ helma.Mail = function(smtp) {
}
return;
};
-
+
+ /**
+ * Sets the Reply-To address of an e-mail message.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.setReplyTo("tobi@helma.at");
+ *
+ * @param {String} addstr as String, the reply-to email address
+ */
this.setReplyTo = function(addstr) {
try {
if (addstr.indexOf("@") < 0) {
@@ -133,6 +183,21 @@ helma.Mail = function(smtp) {
return;
}
+ /**
+ * Sets the recipient of an e-mail message.
+ *
+ * The first argument specifies the receipient's
+ * e-mail address. The optional second argument
+ * specifies the name of the recipient.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.setTo("hop@helma.at");
+ *
+ * @param {String} addstr as String, receipients email address
+ * @param {String} name as String, optional receipients name
+ * @see #addTo
+ */
this.setTo = function(addstr, name) {
try {
addRecipient(addstr, name, Message.RecipientType.TO);
@@ -143,6 +208,23 @@ helma.Mail = function(smtp) {
return;
};
+ /**
+ * Adds a recipient to the address list of an e-mail message.
+ *
+ * The first argument specifies the receipient's
+ * e-mail address. The optional second argument
+ * specifies the name of the recipient.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.setTo("hop@helma.at");
+ * mail.addTo("hopdoc@helma.at");
+ * mail.addTo("tobi@helma.at", "Tobi Schaefer");
+ *
+ * @param {String} addstr as String, receipients email address
+ * @param {String} name as String, optional receipients name
+ * @see setTo
+ */
this.addTo = function(addstr, name) {
try {
addRecipient(addstr, name, Message.RecipientType.TO);
@@ -163,6 +245,21 @@ helma.Mail = function(smtp) {
return;
}
+ /**
+ * Adds a recipient to the list of addresses to get a "blind carbon copy" of an e-mail message.
+ *
+ * The first argument specifies the receipient's
+ * e-mail address. The optional second argument
+ * specifies the name of the recipient.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.addBCC("hop@helma.at");
+ * mail.addBCC("tobi@helma.at", "Tobi Schaefer");
+ *
+ * @param {String} addstr as String, receipients email address
+ * @param {String} name as String, optional receipients name
+ */
this.addBCC = function(addstr, name) {
try {
addRecipient(addstr, name, Message.RecipientType.BCC);
@@ -173,6 +270,15 @@ helma.Mail = function(smtp) {
return;
}
+ /**
+ * Sets the subject of an e-mail message.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.setSubject("Hello, World!");
+ *
+ * @param {String} subject as String, the email subject
+ */
this.setSubject = function(subject) {
if (!subject) {
return;
@@ -186,6 +292,16 @@ helma.Mail = function(smtp) {
return;
};
+ /**
+ * Sets the body text of an e-mail message.
+ *
+ * Example:
+ * var mail = new helma.Mail();
+ * mail.setText("Hello, World!");
+ *
+ * @param {String} text as String, to be appended to the message body
+ * @see #addText
+ */
this.setText = function(text) {
if (text) {
buffer = new java.lang.StringBuffer(text);
@@ -193,6 +309,16 @@ helma.Mail = function(smtp) {
return;
};
+ /**
+ * Appends a string to the body text of an e-mail message.
+ *
+ * Example:
+ * var mail = new Mail();
+ * mail.addText("Hello, World!");
+ *
+ * @param {String} text as String, to be appended to the message body
+ * @see #setText
+ */
this.addText = function(text) {
if (buffer == null) {
buffer = new java.lang.StringBuffer(text);
@@ -202,6 +328,35 @@ helma.Mail = function(smtp) {
return;
};
+ /**
+ * Adds an attachment to an e-mail message.
+ *
+ * The attachment needs to be either a MIME Object or a java.io.file object.
+ *
+ * Use the getURL() function to retrieve a MIME object or wrap a
+ * java.io.File object around a file of the local file system.
+ *
+ * Example:
+ * var file1 = getURL("http://localhost:8080/static/image.gif");
+ * var file2 = getURL("file:////home/snoopy/woodstock.jpg");
+ * var file3 = new java.io.File("/home/snoopy/woodstock.jpg");
+ * var mail = new Mail();
+ * mail.addPart(file1);
+ * mail.addPart(file2);
+ * mail.addPart(file3);
+ *
+ * mail.setFrom("snoopy@doghouse.com");
+ * mail.setTo("woodstock@birdcage.com");
+ * mail.setSubject("Look at this!");
+ * mail.addText("I took a photograph from you. Neat, isn't it? -Snoop");
+ * mail.send();
+ *
+ * @param {fileOrMimeObject} File or Mime object to attach to the email
+ * @param {String} nameString as String, optional name of the attachment
+ * @see global.getUrl
+ * @see mimePart
+ * @see java.io.File
+ */
this.addPart = function(obj, filename) {
try {
if (obj == null) {
@@ -251,6 +406,28 @@ helma.Mail = function(smtp) {
return;
}
+ /**
+ * Sends an e-mail message.
+ *
+ * This function sends the message using the SMTP
+ * server as specified when the Mail object was
+ * constructed using helma.Mail.
+ *
+ * If no smtp hostname was specified when the Mail
+ * object was constructed, the smtp property in either
+ * the app.properties or server.properties file needs
+ * to be set in order for this to work.
+ *
+ * Example:
+ * var mail = new helma.Mail('smtp.example.com');
+ * mail.setTo("watching@michi.tv", "michi");
+ * mail.addCC("franzi@home.at", "franzi");
+ * mail.addBCC("monie@home.at");
+ * mail.setFrom("chef@frischfleisch.at", "Hannes");
+ * mail.setSubject("Registration Conformation");
+ * mail.addText("Thanks for your Registration...");
+ * mail.send();
+ */
this.send = function() {
if (this.status > OK) {
res.debug(errStr + ".send(): Status is " + this.status);
@@ -287,11 +464,13 @@ helma.Mail = function(smtp) {
}
+/** @ignore */
helma.Mail.toString = function() {
return "[helma.Mail]";
};
+/** @ignore */
helma.Mail.prototype.toString = function() {
return "[helma.Mail Object]";
};