tigase.server.gateways
Interface GatewayConnection

public interface GatewayConnection

Instance of the GatewayConnection identifies a single user connection to the external network. The gateway connection is responsinble for maintaining the connection and translating all the data between Jabber/XMPP protocol and the protocol of the external network.

It is recommended that the library for connecting to the exernal network uses internal thread pooling and all it's method work in non-blocking mode. Otherwise delays on one connection may affect all other connections.

Please consider also using NIO for better networking performnce. Recommended library for NIO is the one available in Tigase server core package. Created: Mon Nov 12 15:07:33 2007

Version:

$Rev: 899 $

Author:

Artur Hefczyc

Method Summary

void	addBuddy(java.lang.String id, java.lang.String nick) The addBuddy method is called when the Jabber user has requested adding new buddy to his roster from the external network.
void	addJid(java.lang.String jid) The addJid method is called when the user's Jabber has been activated another connection to the Jabber server.
java.lang.String[]	getAllJids() The getAllJids method returns list of all Jabber user JIDs which have been added.
java.lang.String	getName() The getName method returns the transport screen name which is presented the end user in the service discovery function.
java.lang.String	getPromptMessage() The getPromptMessage method returns the prompt message sent to the user upon registration request.
java.util.List<RosterItem>	getRoster() The getRoster method returns the user roster from the external network account if known.
java.lang.String	getType() The getType method returns the transport type as described in Addressing Gateway section.
void	init() The init method is called to initialize the gateway connection for earlier specified user in setLogin() method.
void	login() The login method is called after setLogin() and init() method.
void	logout() The logout method is called to logout from the external network and close the network connection.
void	removeBuddy(java.lang.String id) The removeBuddy method is called when the Jabber user has requested removal of the buddy from his roster.
void	removeJid(java.lang.String jid) The removeJid method is called when the user's Jabber connection has been closed and the resource is no longer available.
void	sendMessage(Packet message) The sendMessage method is called to submit a message from the Jabber network to the externl network.
void	setGatewayListener(GatewayListener listener) The setGatewayListener method sets the gateway listener.
void	setLogin(java.lang.String username, java.lang.String password) The setLogin method initializes the instance of the GatewayConnection with user ID and password used for loging into the external network.

Method Detail

setLogin

void setLogin(java.lang.String username,
              java.lang.String password)

The setLogin method initializes the instance of the GatewayConnection with user ID and password used for loging into the external network.

Parameters:

username - a String value of the user ID for the external network.

password - a String value of the user password for the external network.

addJid

void addJid(java.lang.String jid)

The addJid method is called when the user's Jabber has been activated another connection to the Jabber server. In other words another user resource is active. The transport has to decide where to send messages coming from the external network.

Parameters:

jid - a String value of the Jabber user full JID including resource part.

removeJid

void removeJid(java.lang.String jid)

The removeJid method is called when the user's Jabber connection has been closed and the resource is no longer available. If the last user connection has been closed the next method called after removeJid is logout().

Parameters:

jid - a String value of the Jabber user full JID including resource part.

getAllJids

java.lang.String[] getAllJids()

The getAllJids method returns list of all Jabber user JIDs which have been added. In other words this is a list of all user's active resources.

Returns:

a String[] value list of all active Jabber's IDs.

setGatewayListener

void setGatewayListener(GatewayListener listener)

The setGatewayListener method sets the gateway listener. The object which can receive packets from the external network.

Parameters:

listener - a GatewayListener value of the gateway listener.

init

void init()
          throws GatewayException

The init method is called to initialize the gateway connection for earlier specified user in setLogin() method. Normally the method should not open network connection yet. This is to initialize internal variables and structures.

Throws:

GatewayException - if an error occurs

login

void login()
           throws LoginGatewayException

The login method is called after setLogin() and init() method. This call is supposed to open network connection to the external network.

Throws:

LoginGatewayException - if an error occurs

logout

void logout()

The logout method is called to logout from the external network and close the network connection. Normally it is called after the user sends unavailable presence stanza from the last active Jabber connection. Or when the gateway is shuting down.

sendMessage

void sendMessage(Packet message)
                 throws GatewayException

The sendMessage method is called to submit a message from the Jabber network to the externl network. The destination address is in the JID nick part and normally it can be obtained by calling: listener.decodeLegacyName(packet.getElemTo()).

Parameters:

message - a Packet value

Throws:

GatewayException - if an error occurs

addBuddy

void addBuddy(java.lang.String id,
              java.lang.String nick)
              throws GatewayException

The addBuddy method is called when the Jabber user has requested adding new buddy to his roster from the external network. The ID is a buddy name in the external network, already decoded from the Jabber's form.

Parameters:

id - a String value of the buddy ID in the external network.

nick - a String value of the buddy screen name.

Throws:

GatewayException - if an error occurs

removeBuddy

void removeBuddy(java.lang.String id)
                 throws GatewayException

The removeBuddy method is called when the Jabber user has requested removal of the buddy from his roster. The ID is a buddy name in the external network, already decoded from the Jabber's form.

Parameters:

id - a String value of the buddy ID in the external network.

Throws:

GatewayException - if an error occurs

getType

java.lang.String getType()

The getType method returns the transport type as described in Addressing Gateway section. The type is used to return service discovery for the gateway using this GatewayConnection implementation. The transport type is normally used by the client application to apply proper icon for the transport.

Returns:

a String value of the gateway type.

getName

java.lang.String getName()

The getName method returns the transport screen name which is presented the end user in the service discovery function.

Returns:

a String value of the gateway screen name.

getPromptMessage

java.lang.String getPromptMessage()

The getPromptMessage method returns the prompt message sent to the user upon registration request.

Returns:

a String value of the prompt message.

getRoster

java.util.List<RosterItem> getRoster()

The getRoster method returns the user roster from the external network account if known. If the roster is not (yet) known the method should return null. The method can be called at any time during the live time of the object.

Returns:

a String value of the list with roster items..