Author: keith Date: Sat Jul 12 05:40:43 2008 New Revision: 19170 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=19170
Log: Adding documentation Modified: trunk/mashup/java/modules/hostobjects/src/org/wso2/mashup/hostobjects/email/Email.java Modified: trunk/mashup/java/modules/hostobjects/src/org/wso2/mashup/hostobjects/email/Email.java URL: http://wso2.org/svn/browse/wso2/trunk/mashup/java/modules/hostobjects/src/org/wso2/mashup/hostobjects/email/Email.java?rev=19170&r1=19169&r2=19170&view=diff ============================================================================== --- trunk/mashup/java/modules/hostobjects/src/org/wso2/mashup/hostobjects/email/Email.java (original) +++ trunk/mashup/java/modules/hostobjects/src/org/wso2/mashup/hostobjects/email/Email.java Sat Jul 12 05:40:43 2008 @@ -48,6 +48,49 @@ import java.io.IOException; import java.util.Properties; +/** + * <p/> + * The Email host object allows users to send out email from their mashups. It helps notify users + * of certain events and acts as a bridge between mashups and users. + * <p/> + * Notes: + * <p/> + * The constructor of the Emal object can be called with or without user credentials. If its called with credentials + * they are used to authenticate the user. If the function is called without credentials the details + * are taken from the server.xml found under conf directory where the mashup server is located. + * So if you wish to keep the credentials in server.xml please update it with the needed usernames + * and passwords. The section that corresponds to this is as follows. + * + * <p> + * <!--Used to configure your default email account that will be used to send emails from mashups using the Email host Object--> + * <EmailConfig> + * <host>smtp.gmail.com</host> + * <port>25</port> + * <username>[EMAIL PROTECTED]</username> + * <password>password</password> + * </EmailConfig> + * <p/> + * </p> + * <p/> + * <pre> + * eg: + * <p/> + * function sendEmail(){ + * var email = new Email("host", "port", "username", "password"); + * var file = new File("temp.txt"); + * email.from = "[EMAIL PROTECTED]"; + * email.to = "[EMAIL PROTECTED]"; // alternatively message.to can be a array of strings. Same goes for cc and bcc + * email.cc = "[EMAIL PROTECTED]"; + * email.bcc = "[EMAIL PROTECTED]"; + * email.subject = "WSO2 Mashup server 1.0 Released"; + * email.addAttachement(file, "temp.txt"); // Optionally can add attachements, it has a variable number of arguments. each argument can be a File hostObject or a string representing a file. + * email.text = "WSO2 Mashup server 1.0 was Released on 28th January 2008"; + * email.send(); + * } + * <p/> + * </pre> + * </p> + */ public class Email extends ScriptableObject { private Properties properties; @@ -67,6 +110,30 @@ return "Email"; } + /** + * <p> + * The Email Object has three different constructors. Choose one depending on your configuration + * and your needs. + * + * 1. The first constructor takes no parameters and uses configuration information specified in the + * server.xml. Using a configuration such as this is useful if you want to use a default email + * account to send out mail from your mashups. It also reduces the hassle of having to key in + * the configuration details each time you need a new email object. + * + * var email = new Email(); + * + * 2. The second constructor, unlike the first, requires the user to provide the configuration + * details each time he creates a new email object. The benefit is that no server configuration + * is needed and you can use diffent accounts when ever you need. The configuration details + * should be given as follows: + * + * var email = new Email("smtp.gmail.com", "25", "[EMAIL PROTECTED]", "password"); // host, port, username, password + * + * 3. The third is a slight variant of the second. It does not require a port to be specified: + * + * var email = new Email("smtp.gmail.com", "[EMAIL PROTECTED]", "password"); // host, username, password + * </p> + */ public static Scriptable jsConstructor(Context cx, Object[] args, Function ctorObj, boolean inNewExpr) throws IOException { @@ -128,6 +195,12 @@ properties.put(key, value); } + /** + * <p>The from address to appear in the email</p> + * <pre> + * email.from = "[EMAIL PROTECTED]"; + * </pre> + */ public void jsSet_from(String from) throws MessagingException { message.setFrom(new InternetAddress(from)); } @@ -150,6 +223,19 @@ return to; } + /** + * <p>The to address that the mail is sent to</p> + * <pre> + * email.to = "[EMAIL PROTECTED]"; + * + * OR + * + * var to = new Array(); + * to[0] = "[EMAIL PROTECTED]"; + * to[1] = "[EMAIL PROTECTED]"; + * email.to = to; + * </pre> + */ public void jsSet_to(Object toObject) throws MessagingException, MashupFault { addRecipients(Message.RecipientType.TO, toObject); } @@ -163,6 +249,19 @@ return cc; } + /** + * <p>The cc address that the mail is sent to</p> + * <pre> + * email.cc = "[EMAIL PROTECTED]"; + * + * OR + * + * var cc = new Array(); + * cc[0] = "[EMAIL PROTECTED]"; + * cc[1] = "[EMAIL PROTECTED]"; + * email.cc = cc; + * </pre> + */ public void jsSet_cc(Object ccObject) throws MessagingException, MashupFault { addRecipients(Message.RecipientType.CC, ccObject); } @@ -176,10 +275,29 @@ return bcc; } + /** + * <p>The bcc address that the mail is sent to</p> + * <pre> + * email.bcc = "[EMAIL PROTECTED]"; + * + * OR + * + * var bcc = new Array(); + * bcc[0] = "[EMAIL PROTECTED]"; + * bcc[1] = "[EMAIL PROTECTED]"; + * email.bcc = bcc; + * </pre> + */ public void jsSet_bcc(Object bccObject) throws MessagingException, MashupFault { addRecipients(Message.RecipientType.BCC, bccObject); } + /** + * <p>The subject of the mail been sent</p> + * <pre> + * email.subject = "WSO2 Mashup server 1.0 Released"; + * </pre> + */ public void jsSet_subject(String subject) throws MessagingException { message.setSubject(subject); } @@ -188,6 +306,12 @@ return message.getSubject(); } + /** + * <p>The body text of the mail been sent</p> + * <pre> + * email.text = "WSO2 Mashup server 1.0 was Released on 28th January 2008"; + * </pre> + */ public void jsSet_text(String text) throws MessagingException { this.text = text; BodyPart messageBodyPart = new MimeBodyPart(); @@ -199,6 +323,14 @@ return text; } + /** + * <p>The body of the email to be sent. This function can be used to send HTML mail.</p> + * <pre> + * email.html = "<h1>WSO2 Mashup server 1.0 was Released on 28th January 2008</h1>"; // Setthing the HTML content as a String + * OR + * email.html = <h1>WSO2 Mashup server 1.0 was Released on 28th January 2008</h1>; // Setting the HTML content as an XML object + * </pre> + */ public void jsSet_html(Object html) throws MessagingException, IOException { if (html instanceof String) { this.html = (String) html; @@ -226,26 +358,31 @@ return html; } + /** + * <p>Send the mail out</p> + * <pre> + * email.send() + * </pre> + */ public void jsFunction_send() throws MessagingException { message.setContent(multipart); Transport.send(message); } - /** - * @deprecated - * @param cx - * @param thisObj - * @param arguments - * @param funObj - * @throws MashupFault - * @throws MessagingException - */ public static void jsFunction_addAttachement(Context cx, Scriptable thisObj, Object[] arguments, Function funObj) throws MashupFault, MessagingException { Email.jsFunction_addAttachment(cx, thisObj, arguments,funObj); } + /** + * <p>Add attachments to the mail been sent. This function has a variable number of arguments, + * each argument can be a File hostObject or a string representing a file.</p> + * <pre> + * var file = new File("temp.txt"); // A file exists at temp.txt + * email.addAttachement(file, "temp.txt"); + * </pre> + */ public static void jsFunction_addAttachment(Context cx, Scriptable thisObj, Object[] arguments, Function funObj) throws MashupFault, MessagingException { _______________________________________________ Mashup-dev mailing list [email protected] http://wso2.org/cgi-bin/mailman/listinfo/mashup-dev
