IM Host Object

1.0 Introduction

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.

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 ymsg (Yahoo Instant Messager and Chat protocols) library from and add it to the lib directory of the Mashup Server. Please note that this would need a restart of the server.

1.1 Example

function IMExample(){
    var im = new IM("msn");
    im.login("username@hotmail.com","password");
    im.sendMessage("sendTo@hotmail.com","Hi, This was sent from the WSO2 Mashup Server!");
    im.disconnect();
}

2.0 IM Object

2.1 IM Object Constructor

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".

2.2 IM login method

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.

  1. 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.

    var im = new IM("msn");
    im.login();

     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.)

        <!--Used to onfigure default IM accounts. If no login creadentials are given to the login method, the login details will be taken from here.-->
        <IMConfig>
            <!--Account details of the Yahoo account that will be used to send IMs-->
            <Yahoo>
                <username>username</username>
                <password>password</password>
            </Yahoo>
            <!--Account details of the MSN account that will be used to send IMs-->
            <MSN>
                <username>username</username>
                <password>password</password>
            </MSN>
            <!--Account details of the AIM account that will be used to send IMs-->
            <AIM>
                <username>username</username>
                <password>password</password>
            </AIM>
            <!--Account details of the ICQ account that will be used to send IMs-->
            <ICQ>
                <username>username</username>
                <password>password</password>
            </ICQ>
            <!--Account details of the Jabber account that will be used to send IMs-->
            <Jabber>
                <username>username@jabberServer</username>
                <password>password</password>
            </Jabber>
        </IMConfig>

    Note: Changed to the server.xml requires a server restart.

  2. 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,

    var im = new IM("msn");
    im.login("username@hotmail.com","password");

    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.


2.2 API Documentation


Member Description
void login() 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.
    im.login();
void login(String username, String password) 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 username@jabberServer.
    im.login(username, password);
void sendMessage(String to, String message) Sends the IM to the specified user.
    im.sendMessage("sendTo@hotmail.com","Hi, This was sent from the WSO2 Mashup Server!");
void disconnect() Logs the user out of the IM server.
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).
    im.disconnect();

3.0 Using the IM object in conjection with the session object

   
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.

this.scope="application";
function login(){
  var im = new IM("msn");
  im.login("username@hotmail.com","password");
  session.put("im", im);
}

sendMessage.outputType="string";
function sendMessage(){
    var im = session.get("im");
    if (im != null) {       
        im.sendMessage("sendTo@hotmail.com","Hi, This was sent from the WSO2 Mashup Server!");
        return "Message succesfullt sent";
    }
    return "Message not sent";
}

function disconnect(){
    var im = session.get("im");
    if (im != null) {       
        im.disconnect();
    }
}

4.0 References

© WSO2 Inc.