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: 2013 $
Author:
Artur Hefczyc

Method Summary
 void addBuddy(String id, 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(tigase.xmpp.JID jid)
          The addJid method is called when the user's Jabber has been activated another connection to the Jabber server.
 tigase.xmpp.JID[] getAllJids()
          The getAllJids method returns list of all Jabber user JIDs which have been added.
 String getName()
          The getName method returns the transport screen name which is presented the end user in the service discovery function.
 String getPromptMessage()
          The getPromptMessage method returns the prompt message sent to the user upon registration request.
 List<RosterItem> getRoster()
          The getRoster method returns the user roster from the external network account if known.
 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(String id)
          The removeBuddy method is called when the Jabber user has requested removal of the buddy from his roster.
 void removeJid(tigase.xmpp.JID 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(String username, 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

addBuddy

void addBuddy(String id,
              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

addJid

void addJid(tigase.xmpp.JID 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.

getAllJids

tigase.xmpp.JID[] 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.

getName

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

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

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

getType

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.

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.


removeBuddy

void removeBuddy(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

removeJid

void removeJid(tigase.xmpp.JID 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.

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

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.

setLogin

void setLogin(String username,
              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.


Copyright © 2001-2006 Tigase Developers Team. All rights Reserved.