com.echomine.jabber
Class JabberUserService

java.lang.Object
  extended by com.echomine.jabber.JabberUserService

public class JabberUserService
extends java.lang.Object

The user service contains all the methods needed to interact with user related services such as authentication and registration.

For authentication, there are several different ways to secure the authentication. Cleartext password and digest are the two core features (although it appears there is a new method called zero-knowledge, known as 0k). The User Service physically queries the server to see what kinds of secure authentication methods are supported, and will automatically choose the most secure way to authenticate. This means, it will choose by priority, zero-knowledge, digest, and password, in that order.


Constructor Summary
JabberUserService(JabberSession session)
           
 
Method Summary
 void changePassword(java.lang.String newPassword)
          changes the password.
 java.util.HashMap getRegisterFields(JID serviceJID)
          Retrieves a list of fields that are required to register with a specific gateway (ie.
 int login()
          logs in to the server using the info provided in JabberContext.
 void register(JID serviceJID, java.util.HashMap fields)
          Registers with a service.
 void removeRegisterService(JID serviceJID, java.lang.String key)
          Tries to unsubscribe/remove your account from a specific service.
 void removeVacationMessage()
          removes the vacation message.
 VacationIQMessage requestVacationMessage(boolean wait)
          requests for the logged in user's vacation message settings.
 void setVacationMessage(java.util.Calendar startDate, java.util.Calendar endDate, java.lang.String vacationMessage)
          sets the vacation message synchronously.
 java.lang.String translateUserToJID(JID serviceJID, java.lang.String user)
          translates a service-specific username into a JID usable for reference.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JabberUserService

public JabberUserService(JabberSession session)
Method Detail

login

public int login()
          throws JabberMessageException,
                 SendMessageFailedException
logs in to the server using the info provided in JabberContext. This is a synchronous method; the method will not return until authentication succeeds or fails. If the authentication succeeds, everything will proceed as normal. If authentication fails, an exception with the error will be thrown. This method contains logic to login using the most secure authentication method provided by the server. You have no need to do that yourself. Login will currently also reset the zero-knowledge sequence when it reaches below 3 (not 0). The new reset sequence will default to 500.

Returns:
the authentication type used. The codes are listed in AuthIQMessage
Throws:
JabberMessageException - when user authentication fails
SendMessageFailedException - when message can't be sent

register

public void register(JID serviceJID,
                     java.util.HashMap fields)
              throws JabberMessageException,
                     SendMessageFailedException

Registers with a service. It's used to create a new account OR update a current account. This method is synchronous and will not return until the server sends a reply. If register is successful, the method will return normally, but an exception will be thrown if error in registration occurs. This method is set to accept default information. It simply obtains a hash table of name/value pairs to add to the message. If you need more advanced control on what kind of data to pass in, you should create the register message and send the message yourself without going through this method. An exception is thrown if there is an error. Otherwise, everything went successfully.

Normally when updating data information, you will need to first request the current info first (by retrieving the register fields). In that request, there will be a "key" field that you need in order to modify any information. For any modification, you need to include that key in the HashMap that you submit.

Parameters:
serviceJID - the service name to register with (ie. jabber.org, aim.jabber.org, msn.jabber.org)
fields - a set of name/value pairs that will be submitted to the server (ie. username, password, email, etc)
Throws:
JabberMessageException - when registration fails. The error message will indicate the reason.
SendMessageFailedException - when message can't be sent

changePassword

public void changePassword(java.lang.String newPassword)
                    throws JabberMessageException,
                           SendMessageFailedException
changes the password. This method is synchronous and will not return until a reply is received. If there is an error, then the password is not changed, and an exception is thrown. Otherwise, if everything went ok, the method returns normally.

Throws:
JabberMessageException - if password is not changed
SendMessageFailedException

getRegisterFields

public java.util.HashMap getRegisterFields(JID serviceJID)
                                    throws JabberMessageException,
                                           SendMessageFailedException

Retrieves a list of fields that are required to register with a specific gateway (ie. AIM, MSN, etc). You can also use this method retrieve the current information registered with the gateway (except the password). This method works for user registration as well as gateway/transport registration.

If you happen to be registered already with the gateway, this method will return the fields (with the data that you registered with) that you can modify. The information inside will contain a key that must be passed between the client and server for any changes or sets. The key acts as a security mechanism that makes sure that you're the one who is modifying the information.

You need to provide the gateway that this message goes to. This can actually be retrieved by querying for the list of agents from the server (available in the Server Service).

This method is synchronous and will not return until a reply or error is received.

Parameters:
serviceJID - the JID of the gateway (ie. jabber.org, aim.jabber.org, etc)
Throws:
JabberMessageException
SendMessageFailedException

removeRegisterService

public void removeRegisterService(JID serviceJID,
                                  java.lang.String key)
                           throws JabberMessageException,
                                  SendMessageFailedException

Tries to unsubscribe/remove your account from a specific service. This is normally used to unregister yourself from a service (ie. MSN, AIM, ICQ, etc) that you were previously registered with. in order to unsubscribe from an account, you obviously need to be registered first. Thus, you muse first retrieve the list of register fields and obtain the key. Then, you can use the key to remove.

This method is synchronous and will not return until a reply or error is received

Note that the key has been obsoleted. This may mean that you do not necessarily need to pass in a key any longer depending on the server.

Parameters:
serviceJID - the service JID that you will be removing yourself from.
key - the key that is sent by the server to you when you retrieved the fields (null if you don't have one).
Throws:
JabberMessageException
SendMessageFailedException

translateUserToJID

public java.lang.String translateUserToJID(JID serviceJID,
                                           java.lang.String user)
                                    throws JabberMessageException,
                                           SendMessageFailedException

translates a service-specific username into a JID usable for reference. This is used to translate gateway-specific user naming convention into a Jabber JID naming convention (ie. "123456" for ICQ might be translated into "123456@icq.jabber.org").

This message is sent synchronously and will not return until an error or reply is received.

Parameters:
serviceJID - the service/gateway to translate this user into
user - the service/gateway's user name that needs to be translated
Returns:
the translated name in JID form, or null the name cannot be translated somehow.
Throws:
JabberMessageException - if there is an error during translation or timeout occurs.
SendMessageFailedException - sending the message failed

requestVacationMessage

public VacationIQMessage requestVacationMessage(boolean wait)
                                         throws SendMessageFailedException,
                                                JabberMessageException
requests for the logged in user's vacation message settings. This returns the vacation reply message that contains the data requested if wait is true

Parameters:
wait - whether to wait for the response or not
Returns:
the vacation message reply (not the request)
Throws:
SendMessageFailedException
JabberMessageException

removeVacationMessage

public void removeVacationMessage()
                           throws SendMessageFailedException,
                                  JabberMessageException
removes the vacation message. The message will be sent synchronously and will not return until a reply is received.

Throws:
SendMessageFailedException
JabberMessageException

setVacationMessage

public void setVacationMessage(java.util.Calendar startDate,
                               java.util.Calendar endDate,
                               java.lang.String vacationMessage)
                        throws SendMessageFailedException,
                               JabberMessageException
sets the vacation message synchronously.

Parameters:
startDate - the starting date for the vacation
endDate - the ending date for the vacation
vacationMessage - the message to display
Throws:
SendMessageFailedException
JabberMessageException


Copyright © 2001-2005 Echomine. All Rights Reserved.