From 3f7126bfa24f5c0935d01b4b69f6bba5f0e30d61 Mon Sep 17 00:00:00 2001 From: zumbrunn Date: Wed, 7 Feb 2007 11:51:47 +0000 Subject: [PATCH] Added jsdoc comment based documentation --- helma/Mail.js | 189 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 184 insertions(+), 5 deletions(-) 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]"; };