antville/helma
antville/helma
1
1
Fork 0
Code Issues 5 Pull requests 7 Projects Releases 5 Activity Actions

Added jsdoc comment based documentation

Browse source
This commit is contained in:
zumbrunn 2007-02-07 11:51:47 +00:00
parent 00ea378a37
commit 3f7126bfa2
1 changed files with 184 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

185
helma/Mail.js
View file

@ -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.
* <br /><br />
* 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.
* <br /><br />
* 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.
* <br /><br />
* 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.</p>
*
* @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.
* <br /><br />
* The first argument specifies the receipient's
* e-mail address. The optional second argument
* specifies the name of the recipient.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.setFrom("tobi@helma.at", "Tobi Schaefer");</pre>
*
* @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) {
@ -119,6 +160,15 @@ helma.Mail = function(smtp) {
return;
};
/**
* Sets the Reply-To address of an e-mail message.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.setReplyTo("tobi@helma.at");</pre>
*
* @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.
* &nbsp;
* The first argument specifies the receipient's
* e-mail address. The optional second argument
* specifies the name of the recipient.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.setTo("hop@helma.at");</pre>
*
* @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.
* <br /><br />
* The first argument specifies the receipient's
* e-mail address. The optional second argument
* specifies the name of the recipient.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.setTo("hop@helma.at");
* mail.addTo("hopdoc@helma.at");
* mail.addTo("tobi@helma.at", "Tobi Schaefer");</pre>
*
* @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.
* <br /><br />
* The first argument specifies the receipient's
* e-mail address. The optional second argument
* specifies the name of the recipient.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.addBCC("hop@helma.at");
* mail.addBCC("tobi@helma.at", "Tobi Schaefer");</pre>
*
* @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.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.setSubject("Hello, World!");</pre>
*
* @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.
* <br /><br />
* Example:
* <pre>var mail = new helma.Mail();
* mail.setText("Hello, World!");</pre>
*
* @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.
* <br /><br />
* Example:
* <pre>var mail = new Mail();
* mail.addText("Hello, World!");</pre>
*
* @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.
* <br /><br />
* The attachment needs to be either a MIME Object or a java.io.file object.
* <br /><br />
* Use the getURL() function to retrieve a MIME object or wrap a
* java.io.File object around a file of the local file system.
* <br /><br />
* Example:
* <pre>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);
* &nbsp;
* 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();</pre>
*
* @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.
* <br /><br />
* This function sends the message using the SMTP
* server as specified when the Mail object was
* constructed using helma.Mail.
* <br /><br />
* 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.
* <br /><br />
* Example:
* <pre>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();</pre>
*/
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]";
};