org.jivesoftware.smack
Class XMPPConnection

java.lang.Object
  org.jivesoftware.smack.XMPPConnection

Direct Known Subclasses:

SSLXMPPConnection

public class XMPPConnection
extends Object

Creates a connection to a XMPP server. A simple use of this API might look like the following:

 // Create a connection to the jivesoftware.com XMPP server.
 XMPPConnection con = new XMPPConnection("jivesoftware.com");
 // Most servers require you to login before performing other tasks.
 con.login("jsmith", "mypass");
 // Start a new conversation with John Doe and send him a message.
 Chat chat = con.createChat("jdoe@jabber.org");
 chat.sendMessage("Hey, how's it going?");
 

Author:

Matt Tucker

Field Summary

static boolean

DEBUG_ENABLED Value that indicates whether debugging is enabled.

Constructor Summary

XMPPConnection(String host)
Creates a new connection to the specified XMPP server.

XMPPConnection(String host, int port)
Creates a new connection to the specified XMPP server on the given port.

XMPPConnection(String host, int port, javax.net.SocketFactory socketFactory)
Creates a new connection to the specified XMPP server on the given port using the specified SocketFactory.

Method Summary

static void	addConnectionListener(ConnectionEstablishedListener connectionEstablishedListener) Adds a connection established listener that will be notified when a new connection is established.
void	addConnectionListener(ConnectionListener connectionListener) Adds a connection listener to this connection that will be notified when the connection closes or fails.
void	addPacketListener(PacketListener packetListener, PacketFilter packetFilter) Registers a packet listener with this connection.
void	addPacketWriterListener(PacketListener packetListener, PacketFilter packetFilter) Registers a packet listener with this connection.
void	close() Closes the connection by setting presence to unavailable then closing the stream to the XMPP server.
Chat	createChat(String participant) Creates a new chat with the specified participant.
GroupChat	createGroupChat(String room) Creates a new group chat connected to the specified room.
PacketCollector	createPacketCollector(PacketFilter packetFilter) Creates a new packet collector for this connection.
AccountManager	getAccountManager() Returns an account manager instance for this connection.
String	getConnectionID() Returns the connection ID for this connection, which is the value set by the server when opening a XMPP stream.
String	getHost() Returns the host name of the XMPP server for this connection.
int	getPort() Returns the port number of the XMPP server for this connection.
Roster	getRoster() Returns the roster for the user logged into the server.
String	getUser() Returns the full XMPP address of the user that is logged in to the connection or null if not logged in yet.
boolean	isAnonymous() Returns true if currently authenticated anonymously.
boolean	isAuthenticated() Returns true if currently authenticated by successfully calling the login method.
boolean	isConnected() Returns true if currently connected to the XMPP server.
boolean	isSecureConnection() Returns true if the connection is a secured one, such as an SSL connection.
void	login(String username, String password) Logs in to the server using the strongest authentication mode supported by the server, then set our presence to available.
void	login(String username, String password, String resource) Logs in to the server using the strongest authentication mode supported by the server, then sets presence to available.
void	loginAnonymously() Logs in to the server anonymously.
static void	removeConnectionListener(ConnectionEstablishedListener connectionEstablishedListener) Removes a listener on new established connections.
void	removeConnectionListener(ConnectionListener connectionListener) Removes a connection listener from this connection.
void	removePacketListener(PacketListener packetListener) Removes a packet listener from this connection.
void	removePacketWriterListener(PacketListener packetListener) Removes a packet listener from this connection.
void	sendPacket(Packet packet) Sends the specified packet to the server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG_ENABLED

public static boolean DEBUG_ENABLED

Value that indicates whether debugging is enabled. When enabled, a debug window will apear for each new connection that will contain the following information:

• Client Traffic -- raw XML traffic generated by Smack and sent to the server.
• Server Traffic -- raw XML traffic sent by the server to the client.
• Interpreted Packets -- shows XML packets from the server as parsed by Smack.

Debugging can be enabled by setting this field to true, or by setting the Java system property smack.debugEnabled to true. The system property can be set on the command line such as "java SomeApp -Dsmack.debugEnabled=true".

Constructor Detail

XMPPConnection

public XMPPConnection(String host)
               throws XMPPException

Creates a new connection to the specified XMPP server. The default port of 5222 will be used.

Parameters:

host - the name of the XMPP server to connect to; e.g. jivesoftware.com.

Throws:

XMPPException - if an error occurs while trying to establish the connection. Two possible errors can occur which will be wrapped by an XMPPException -- UnknownHostException (XMPP error code 504), and IOException (XMPP error code 502). The error codes and wrapped exceptions can be used to present more appropiate error messages to end-users.

XMPPConnection

public XMPPConnection(String host,
                      int port)
               throws XMPPException

Creates a new connection to the specified XMPP server on the given port.

Parameters:

host - the name of the XMPP server to connect to; e.g. jivesoftware.com.

port - the port on the server that should be used; e.g. 5222.

Throws:

XMPPException - if an error occurs while trying to establish the connection. Two possible errors can occur which will be wrapped by an XMPPException -- UnknownHostException (XMPP error code 504), and IOException (XMPP error code 502). The error codes and wrapped exceptions can be used to present more appropiate error messages to end-users.

XMPPConnection

public XMPPConnection(String host,
                      int port,
                      javax.net.SocketFactory socketFactory)
               throws XMPPException

Creates a new connection to the specified XMPP server on the given port using the specified SocketFactory.

A custom SocketFactory allows fine-grained control of the actual connection to the XMPP server. A typical use for a custom SocketFactory is when connecting through a SOCKS proxy.

Parameters:

host - the name of the XMPP server to connect to; e.g. jivesoftware.com.

port - the port on the server that should be used; e.g. 5222.

socketFactory - a SocketFactory that will be used to create the socket to the XMPP server.

Throws:

XMPPException - if an error occurs while trying to establish the connection. Two possible errors can occur which will be wrapped by an XMPPException -- UnknownHostException (XMPP error code 504), and IOException (XMPP error code 502). The error codes and wrapped exceptions can be used to present more appropiate error messages to end-users.

Method Detail

getConnectionID

public String getConnectionID()

Returns the connection ID for this connection, which is the value set by the server when opening a XMPP stream. If the server does not set a connection ID, this value will be null.

Returns:

the ID of this connection returned from the XMPP server.

getHost

public String getHost()

Returns the host name of the XMPP server for this connection.

Returns:

the host name of the XMPP server.

getPort

public int getPort()

Returns the port number of the XMPP server for this connection. The default port for normal connections is 5222. The default port for SSL connections is 5223.

Returns:

the port number of the XMPP server.

getUser

public String getUser()

Returns the full XMPP address of the user that is logged in to the connection or null if not logged in yet. An XMPP address is in the form username@server/resource.

Returns:

the full XMPP address of the user logged in.

login

public void login(String username,
                  String password)
           throws XMPPException

Logs in to the server using the strongest authentication mode supported by the server, then set our presence to available. If more than five seconds elapses in each step of the authentication process without a response from the server, or if an error occurs, a XMPPException will be thrown.

Parameters:

username - the username.

password - the password.

Throws:

XMPPException - if an error occurs.

login

public void login(String username,
                  String password,
                  String resource)
           throws XMPPException

Logs in to the server using the strongest authentication mode supported by the server, then sets presence to available. If more than five seconds elapses in each step of the authentication process without a response from the server, or if an error occurs, a XMPPException will be thrown.

Parameters:

username - the username.

password - the password.

resource - the resource.

Throws:

XMPPException - if an error occurs.

IllegalStateException - if not connected to the server, or already logged in to the serrver.

loginAnonymously

public void loginAnonymously()
                      throws XMPPException

Logs in to the server anonymously. Very few servers are configured to support anonymous authentication, so it's fairly likely logging in anonymously will fail. If anonymous login does succeed, your XMPP address will likely be in the form "server/123ABC" (where "123ABC" is a random value generated by the server).

Throws:

XMPPException - if an error occurs or anonymous logins are not supported by the server.

IllegalStateException - if not connected to the server, or already logged in to the serrver.

getRoster

public Roster getRoster()

Returns the roster for the user logged into the server. If the user has not yet logged into the server (or if the user is logged in anonymously), this method will return null.

Returns:

the user's roster, or null if the user has not logged in yet.

getAccountManager

public AccountManager getAccountManager()

Returns an account manager instance for this connection.

Returns:

an account manager for this connection.

createChat

public Chat createChat(String participant)

Creates a new chat with the specified participant. The participant should be a valid XMPP user such as jdoe@jivesoftware.com or jdoe@jivesoftware.com/work.

Parameters:

participant - the person to start the conversation with.

Returns:

a new Chat object.

createGroupChat

public GroupChat createGroupChat(String room)

Creates a new group chat connected to the specified room. The room name should be full address, such as room@chat.example.com.

Most XMPP servers use a sub-domain for the chat service (eg chat.example.com for the XMPP server example.com). You must ensure that the room address you're trying to connect to includes the proper chat sub-domain.

Parameters:

room - the fully qualifed name of the room.

Returns:

a new GroupChat object.

isConnected

public boolean isConnected()

Returns true if currently connected to the XMPP server.

Returns:

true if connected.

isSecureConnection

public boolean isSecureConnection()

Returns true if the connection is a secured one, such as an SSL connection.

Returns:

true if a secure connection to the server.

isAuthenticated

public boolean isAuthenticated()

Returns true if currently authenticated by successfully calling the login method.

Returns:

true if authenticated.

isAnonymous

public boolean isAnonymous()

Returns true if currently authenticated anonymously.

Returns:

true if authenticated anonymously.

close

public void close()

Closes the connection by setting presence to unavailable then closing the stream to the XMPP server. Once a connection has been closed, it cannot be re-opened.

sendPacket

public void sendPacket(Packet packet)

Sends the specified packet to the server.

Parameters:

packet - the packet to send.

addPacketListener

public void addPacketListener(PacketListener packetListener,
                              PacketFilter packetFilter)

Registers a packet listener with this connection. A packet filter determines which packets will be delivered to the listener.

Parameters:

packetListener - the packet listener to notify of new packets.

packetFilter - the packet filter to use.

removePacketListener

public void removePacketListener(PacketListener packetListener)

Removes a packet listener from this connection.

Parameters:

packetListener - the packet listener to remove.

addPacketWriterListener

public void addPacketWriterListener(PacketListener packetListener,
                                    PacketFilter packetFilter)

Registers a packet listener with this connection. The listener will be notified of every packet that this connection sends. A packet filter determines which packets will be delivered to the listener.

Parameters:

packetListener - the packet listener to notify of sent packets.

packetFilter - the packet filter to use.

removePacketWriterListener

public void removePacketWriterListener(PacketListener packetListener)

Removes a packet listener from this connection.

Parameters:

packetListener - the packet listener to remove.

createPacketCollector

public PacketCollector createPacketCollector(PacketFilter packetFilter)

Creates a new packet collector for this connection. A packet filter determines which packets will be accumulated by the collector.

Parameters:

packetFilter - the packet filter to use.

Returns:

a new packet collector.

addConnectionListener

public void addConnectionListener(ConnectionListener connectionListener)

Adds a connection listener to this connection that will be notified when the connection closes or fails.

Parameters:

connectionListener - a connection listener.

removeConnectionListener

public void removeConnectionListener(ConnectionListener connectionListener)

Removes a connection listener from this connection.

Parameters:

connectionListener - a connection listener.

addConnectionListener

public static void addConnectionListener(ConnectionEstablishedListener connectionEstablishedListener)

Adds a connection established listener that will be notified when a new connection is established.

Parameters:

connectionEstablishedListener - a listener interested on connection established events.

removeConnectionListener

public static void removeConnectionListener(ConnectionEstablishedListener connectionEstablishedListener)

Removes a listener on new established connections.

Parameters:

connectionEstablishedListener - a listener interested on connection established events.