Author: keith Date: Fri Jan 25 00:14:08 2008 New Revision: 12872 Log:
Adding IM Host Object documentation Added: trunk/mashup/java/xdocs/imhostobject.html Added: trunk/mashup/java/xdocs/imhostobject.html ============================================================================== --- (empty file) +++ trunk/mashup/java/xdocs/imhostobject.html Fri Jan 25 00:14:08 2008 @@ -0,0 +1,277 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + + <meta http-equiv="content-type" content=""> + <title>IM Host Object</title> + + + <link href="styles.css" rel="stylesheet" type="text/css" media="all"> + +</head> + + +<body> + +<div id="main-content"> +<h1>IM Host Object</h1> + +<h3>1.0 Introduction</h3> + +<p>The IM object allows users to send out Instant Messages from +there +mashups. It helps you notify users of certain events and acts +as a brigde between mashups and users. Supported IM protocols are MSN, +AIM, ICQ, Jabber and Yahoo.</p> + +<p>Note : The Mashup Server does not ship the library used by the +yahoo protocol. If you wish to use the Yahoo protocol, please download +the <a href="https://sourceforge.net/project/showfiles.php?group_id=76691";>ymsg +(Yahoo Instant Messager and Chat protocols)</a> library from and +add it to the lib directory of the Mashup Server. Please note that this +would need a restart of the server.</p> + +<h3>1.1 Example</h3> + +<div class="code">function IMExample(){ +<br> + + var im = new IM("msn"); +<br> + + im.login(<a class="moz-txt-link-rfc2396E" href="mailto:[EMAIL PROTECTED]">"[EMAIL PROTECTED]"</a>,"password"); +<br> + + im.sendMessage(<a class="moz-txt-link-rfc2396E" href="mailto:[EMAIL PROTECTED]">"[EMAIL PROTECTED]"</a>,"Hi, +This was sent from the WSO2 Mashup Server!"); +<br> + + im.disconnect();<br> + +} +</div> + +<h3>2.0 IM Object</h3> + +<h4>2.1 IM Object Constructor +</h4> + +<p>The IM Object which has a single constructor taken in the +protocol to be used as an argument to it. Supported values are "msn", +"aim", "icq", "jabber" and "yahoo".</p> + +<h4>2.2 IM login method</h4> + +<p>The login method of the IM object takes two different forms. +It allows the user to specify account details in the server.xml in +which case you dont have to parse any arguments into the login method, +or it allow the user to specify the account details each and everytime +the login method is called.</p> + +<ol> + + <li> + <p>In the first instance the login method takes no parameters +and uses account information specified in the server.xml. Using a +configuration such as this is usefull if you want to use a IM account +to send out Instant Messages from your mashups. It also reduces the +hassle of having to key in the account details each time you need +a new im object.</p> + + <div class="code">var im = new IM("msn");<br> + +im.login();</div> + + <br> + + The configuration in the server.xml should be in the +following form (The default server.xml has some prepopulated dummy +values. Please update them as required.)<br> + + <div style="margin-left: 40px;"><br> + + </div> + + <div class="code"> + <!--Used to onfigure default IM accounts. If no login creadentials are given to the login method, the login details will be taken from here.--><br> + <IMConfig><br> + <!--Account details of the Yahoo account that will be used to send IMs--><br> + <Yahoo><br> + <username>username</username><br> + <password>password</password><br> + </Yahoo><br> + <!--Account details of the MSN account that will be used to send IMs--><br> + <MSN><br> + <username>username</username><br> + <password>password</password><br> + </MSN><br> + <!--Account details of the AIM account that will be used to send IMs--><br> + <AIM><br> + <username>username</username><br> + <password>password</password><br> + </AIM><br> + <!--Account details of the ICQ account that will be used to send IMs--><br> + <ICQ><br> + <username>username</username><br> + <password>password</password><br> + </ICQ><br> + <!--Account details of the Jabber account that will be used to send IMs--><br> + <Jabber><br> + <username>[EMAIL PROTECTED]</username><br> + <password>password</password><br> + </Jabber><br> + </IMConfig></div> + + <p>Note: Changed to the +server.xml requires a server restart.</p> + + </li> + + <li> + <p>The second instance unlike the first requires the user +to provide the account details each time he invokes the login function. The plus point is that no server configuration is +needed and you can use diffent accounts when ever you need. The +configuration details should be given as follws,<br> + + </p> + + <div class="code">var im = new IM("msn"); + <br> + +im.login(<a class="moz-txt-link-rfc2396E" href="mailto:[EMAIL PROTECTED]">"[EMAIL PROTECTED]"</a>,"password"); + </div> + + <p>Note : If the configuration +details are given in the server.xml and the user uses the above method, +the details given by the user when invoking the login method gets +precedence.</p> + + </li> +</ol> + +<br> + +<h4>2.2 API Documentation</h4> + +<br> + +<table style="text-align: left;" border="1" cellpadding="2" cellspacing="2"> + + <tbody> + + <tr> + + <td>Member</td> + + <td>Description</td> + + </tr> + + <tr> + + <td><b>void login(</b>)</td> + + <td>The accound details pertaining to the protocol is taken from +the server.xml and those credentials are used to log the user into the +IM server.<br> + <span style="font-style: italic;"> im.login();</span></td> + + </tr> + + <tr> + + <td><b>void login</b><span style="font-weight: bold;">(String username, String password)</span></td> + + <td>Uses the username and password as credentials to log the user +into the IM server. When the jabber protocol is used the username +should be of the form [EMAIL PROTECTED]<br> + <span style="font-style: italic;"> im.login(username, password);</span></td> + + </tr> + + <tr> + + <td><span style="font-weight: bold;">void sendMessage(String to, String message)</span></td> + + <td>Sends the IM to the specified user.<br> + <span style="font-style: italic;"> + im.sendMessage(</span><a style="font-style: italic;" class="moz-txt-link-rfc2396E" href="mailto:[EMAIL PROTECTED]">"[EMAIL PROTECTED]"</a><span style="font-style: italic;">,"Hi, +This was sent from the WSO2 Mashup Server!");</span> + </td> + + </tr> + + <tr> + + <td><span style="font-weight: bold;">void disconnect()</span></td> + + <td>Logs the user out of the IM server.<br> +Note: The AIM and ICQ protocols does not allow users to log in and out +frequently. In such a situation these two protocols block the user for +a breif time (Around 10 Minutes).<br> + <span style="font-style: italic;"> im.disconnect();</span></td> + + </tr> + + + + + + + </tbody> +</table> + +<br> + +<h3>3.0 Using the IM object in conjection with the session object</h3> + <br> +If you expect your mashup to send out IMs frequestly it may not be +optimal to login each time you need to send a message. Such situations +can be combated by using the IM object in conjunction with the session +object. The following is an example of such a usage.<br> +<br> + + +<div class="code">this.scope="application";<br> +function login(){<br> + var im = new IM("msn");<br> + im.login("[EMAIL PROTECTED]","password");<br> + session.put("im", im);<br> +}<br> +<br> +sendMessage.outputType="string";<br> +function sendMessage(){<br> + var im = session.get("im");<br> + if (im != null) { <br> + +im.sendMessage("[EMAIL PROTECTED]","Hi, This was sent from the WSO2 +Mashup Server!");<br> + return "Message succesfullt sent";<br> + }<br> + return "Message not sent";<br> +}<br> +<br> +function disconnect(){<br> + var im = session.get("im");<br> + if (im != null) { <br> + im.disconnect();<br> + }<br> +} +</div> +<h3>4.0 References<br> + +</h3> + +<ul> + + <li><a href="apidocs/org/wso2/mashup/hostobjects/im/IM.html">JavaDoc +for the IM host Object</a></li> + +</ul> + +</div> + +<p>� WSO2 Inc.</p> + +</body> +</html> _______________________________________________ Mashup-dev mailing list [email protected] http://www.wso2.org/cgi-bin/mailman/listinfo/mashup-dev
