com.ibm.tivoli.imi.spi

Interface IMSession

All Known Implementing Classes:

IMSessionMocImpl, IMSessionSTImpl

public interface IMSession

Author:

fabiosc - Fabio Silva Carvalho 06/09/2007

Method Summary

Modifier and Type	Method and Description
void	changeUserStatus(IMUser.IMUserStatus imUserStatus) Changes the user status related to the connection established with IM server
void	close() Closes the connection established with IM server.
void	configure(java.util.Properties properties) Configures the session using the properties specified.
IMMessageHandler	createMessageHandler(IMUser partner) Creates a new message handler allowing objects to do operations like sending new messages, closing the conversation or verifying if the conversation is still opened
IMResolveHandler	createResolveHandler(boolean onlyUnique, boolean exhaustiveLookup) Creates and returns a resolve object
IMUserStatusHandler	createUserStatusHandler() Creates a new user status handler allowing listener objects to be registered to be notified when some user changes his/her IM status
long	getConnectionTimeout() Returns the connection timeout
long	getDefaultConnectionTimeout() Returns the default connection timeout
long	getDefaultResolveTimeout() Returns the default resolve timeout
IMUser	getIMUser() Returns the IMUser object related to the user account used to open this IM chat session.
long	getResolveTimeout() Returns the resolve timeout
java.lang.String	getServerHostName()
java.lang.String	getSessionName() Returns the session name
java.lang.String	getUserId()
java.lang.String	getUserPassword()
boolean	isOpened()
void	open() Connects to the IM server using the information set using configure(Properties) method.
void	registerIMSingleListener(IMSingleListener listener) Registers a new listener for handling incoming messages.
void	removeIMSingleListener(IMSingleListener listener) Remove the specified IMSingleListener
IMUser	resolve(java.lang.String userDisplayName) Resolves the user identified by userDisplayName parameter.
IMResolveEvent	resolve(java.lang.String userDisplayName, boolean onlyUnique, boolean exhaustiveLookup) Resolves the user identified by userDisplayName parameter.
void	setConnectionTimeout(long timeout) Defines the timeout used by method open().
void	setResolveTimeout(long timeout) Defines the timeout used by method resolve(String, boolean, boolean).

Method Detail

configure

void configure(java.util.Properties properties)
        throws IMException

Configures the session using the properties specified. A unique session name is automatically created and set to this session. The method IMDriver.validateProperties(Properties) can be used to make sure that the properties are valid

Parameters:

properties -

Throws:

IMException - if the properties are invalid or if the session could not be created

getServerHostName

java.lang.String getServerHostName()

getSessionName

java.lang.String getSessionName()

Returns the session name

Returns:

the session name or null if it is not opened yet

getUserId

java.lang.String getUserId()

getUserPassword

java.lang.String getUserPassword()

getIMUser

IMUser getIMUser()

Returns the IMUser object related to the user account used to open this IM chat session. If the session is not opened yet this method will return null

Returns:

the IMUser object related to the user account used to open this IM chat session or null if the session is not opened yet

open

void open()
   throws IMException

Connects to the IM server using the information set using configure(Properties) method. This method uses a connection timeout set by setConnectionTimeout(long), and not returns until the timeout is over or the connection opens. So, this method is blocking (bolcks the current thread). A not blockiing method to open a session will be available soon.

Throws:

IMException - if it is not possible to open the session (invalid user or password, for example), or if the connection timeout has finished

changeUserStatus

void changeUserStatus(IMUser.IMUserStatus imUserStatus)
               throws IMException

Changes the user status related to the connection established with IM server

Parameters:

imUserStatus -

Throws:

IMException - if the IM session is not opened

getDefaultConnectionTimeout

long getDefaultConnectionTimeout()

Returns the default connection timeout

Returns:

the default connection timeout

getConnectionTimeout

long getConnectionTimeout()

Returns the connection timeout

Returns:

the connection timeout

setConnectionTimeout

void setConnectionTimeout(long timeout)

Defines the timeout used by method open(). If a connection timeout is not set, the default value will be used. The default connection timeout value can be got using the getDefaultConnectionTimeout() method

Parameters:

timeout -

isOpened

boolean isOpened()

close

void close()
    throws IMException

Closes the connection established with IM server. It doesn't do nothing it the session is not opened

Throws:

IMException - if some error occurs during the closing operation

getDefaultResolveTimeout

long getDefaultResolveTimeout()

Returns the default resolve timeout

Returns:

the default resolve timeout

getResolveTimeout

long getResolveTimeout()

Returns the resolve timeout

Returns:

the resolve timeout

setResolveTimeout

void setResolveTimeout(long timeout)

Defines the timeout used by method resolve(String, boolean, boolean). If a resolve timeout is not set, the default value will be used. The default resolve timeout value can be got using the getDefaultResolveTimeout() method

Parameters:

timeout -

resolve

IMResolveEvent resolve(java.lang.String userDisplayName,
                       boolean onlyUnique,
                       boolean exhaustiveLookup)
                throws IMException

Resolves the user identified by userDisplayName parameter. This method is blocking, what means that the thread that call this method will be blocked until the resolve operation is finished. It happens because this function is done remotely. Use a IMResolveHandler object and a IMResolveListener class if you don't want to block your thread to use this function.

Parameters:

userDisplayName -

onlyUnique - This option determines if it should resolve successfully only if the provided name is matched exactly in the IM directory

exhaustiveLookup - This option determines if it should perform an exhaustive lookup through all directories or stop in the first directory where a match is found

Returns:

this object contains all information needed to get the STUser object or to know the reason that it could not be generated

Throws:

IMException - if the session is not opened, or if the resolve operation is not concluded in X milliseconds. X can be set using setResolveTimeout(long) method

See Also:

createResolveHandler(boolean, boolean)

resolve

IMUser resolve(java.lang.String userDisplayName)
        throws IMException

Resolves the user identified by userDisplayName parameter. This method is blocking, what means that the thread that call this method will be blocked until the resolve operation is finished. It happens because this function is done remotely. Use a IMResolveHandler object and a IMResolveListener class if you don't want to block your thread to use this function. This method returns a user resolve only if the display name is exactly equal to the existent in server

Parameters:

userDisplayName -

Returns:

the user resolved or null if could not be found

Throws:

IMException - if the session is not opened, or if the resolve operation is not concluded in X milliseconds. X can be set using setResolveTimeout(long) method

See Also:

createResolveHandler(boolean, boolean)

createResolveHandler

IMResolveHandler createResolveHandler(boolean onlyUnique,
                                      boolean exhaustiveLookup)
                               throws IMException

Creates and returns a resolve object

Parameters:

onlyUnique - This option determines whether the created resolver object should resolve successfully only if the provided name is matched exactly in the IM directory

exhaustiveLookup - This option determines whether the created resolver object should perform an exhaustive lookup through all directories or stop in the first directory where a match is found

Returns:

Throws:

IMException - if this session is not opened yet, or if the partner can not be resolved

createUserStatusHandler

IMUserStatusHandler createUserStatusHandler()
                                     throws IMException

Creates a new user status handler allowing listener objects to be registered to be notified when some user changes his/her IM status

Returns:

a new user status handler

Throws:

IMException - if this session is not opened yet

createMessageHandler

IMMessageHandler createMessageHandler(IMUser partner)
                               throws IMException

Creates a new message handler allowing objects to do operations like sending new messages, closing the conversation or verifying if the conversation is still opened

Returns:

a new user status handler

Throws:

IMException - if this session is not opened yet

registerIMSingleListener

void registerIMSingleListener(IMSingleListener listener)
                       throws IMException

Registers a new listener for handling incoming messages.

Parameters:

listener -

Throws:

IMException

removeIMSingleListener

void removeIMSingleListener(IMSingleListener listener)
                     throws IMException

Remove the specified IMSingleListener

Parameters:

listener -

Throws:

IMException