|
Smack | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.jivesoftware.smack.XMPPConnection
public class XMPPConnection
Creates a connection to a XMPP server. A simple use of this API might look like the following:
// Create a connection to the igniterealtime.org XMPP server. XMPPConnection con = new XMPPConnection("igniterealtime.org"); // Connect to the server con.connect(); // 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 = connection.getChatManager().createChat("jdoe@igniterealtime.org", new MessageListener() { public void processMessage(Chat chat, Message message) { // Print out any messages we get back to standard out. System.out.println("Received message: " + message); } }); chat.sendMessage("Howdy!"); // Disconnect from the server con.disconnect();XMPPConnections can be reused between connections. This means that an XMPPConnection may be connected, disconnected and then connected again. Listeners of the XMPPConnection will be retained accross connections.
If a connected XMPPConnection gets disconnected abruptly then it will try to reconnect again. To stop the reconnection process, use
disconnect()
. Once stopped
you can use connect()
to manually connect to the server.
Field Summary | |
---|---|
static boolean |
DEBUG_ENABLED
Value that indicates whether debugging is enabled. |
Constructor Summary | |
---|---|
XMPPConnection(ConnectionConfiguration config)
Creates a new XMPP conection in the same way XMPPConnection(ConnectionConfiguration,CallbackHandler) does, but
with no callback handler for password prompting of the keystore. |
|
XMPPConnection(ConnectionConfiguration config,
javax.security.auth.callback.CallbackHandler callbackHandler)
Creates a new XMPP connection using the specified connection configuration. |
|
XMPPConnection(String serviceName)
Creates a new XMPP conection in the same way XMPPConnection(String,CallbackHandler) does, but
with no callback handler for password prompting of the keystore. |
|
XMPPConnection(String serviceName,
javax.security.auth.callback.CallbackHandler callbackHandler)
Creates a new connection to the specified XMPP server. |
Method Summary | |
---|---|
static void |
addConnectionCreationListener(ConnectionCreationListener connectionCreationListener)
Adds a new listener that will be notified when new XMPPConnections are created. |
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 |
addPacketWriterInterceptor(PacketInterceptor packetInterceptor,
PacketFilter packetFilter)
Registers a packet interceptor with this connection. |
void |
addPacketWriterListener(PacketListener packetListener,
PacketFilter packetFilter)
Registers a packet listener with this connection. |
void |
connect()
Establishes a connection to the XMPP server and performs an automatic login only if the previous connection state was logged (authenticated). |
PacketCollector |
createPacketCollector(PacketFilter packetFilter)
Creates a new packet collector for this connection. |
void |
disconnect()
Closes the connection by setting presence to unavailable then closing the stream to the XMPP server. |
void |
disconnect(Presence unavailablePresence)
Closes the connection. |
AccountManager |
getAccountManager()
Returns an account manager instance for this connection. |
ChatManager |
getChatManager()
Returns a chat manager instance for this connection. |
protected ConnectionConfiguration |
getConfiguration()
Returns the configuration used to connect to the server. |
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 server where the XMPP server is running. |
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. |
SASLAuthentication |
getSASLAuthentication()
Returns the SASLAuthentication manager that is responsible for authenticating with the server. |
String |
getServiceName()
Returns the name of the service provided by the XMPP server for this connection. |
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 to the server has successfully negotiated TLS. |
boolean |
isUsingCompression()
Returns true if network traffic is being compressed. |
boolean |
isUsingTLS()
Returns true if the connection to the server has successfully negotiated TLS. |
void |
login(String username,
String password)
Logs in to the server using the strongest authentication mode supported by the server, then sets 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. |
void |
loginAnonymously()
Logs in to the server anonymously. |
static void |
removeConnectionCreationListener(ConnectionCreationListener connectionCreationListener)
Removes a listener that was interested in connection creation events. |
void |
removeConnectionListener(ConnectionListener connectionListener)
Removes a connection listener from this connection. |
void |
removePacketListener(PacketListener packetListener)
Removes a packet listener from this connection. |
void |
removePacketWriterInterceptor(PacketInterceptor packetInterceptor)
Removes a packet interceptor. |
void |
removePacketWriterListener(PacketListener packetListener)
Removes a packet listener from this connection. |
void |
sendPacket(Packet packet)
Sends the specified packet to the server. |
protected void |
shutdown(Presence unavailablePresence)
Closes the connection by setting presence to unavailable then closing the stream to the XMPP server. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static boolean DEBUG_ENABLED
Constructor Detail |
---|
public XMPPConnection(String serviceName, javax.security.auth.callback.CallbackHandler callbackHandler)
This is the simplest constructor for connecting to an XMPP server. Alternatively, you can get fine-grained control over connection settings using the
XMPPConnection(ConnectionConfiguration)
constructor.Note that XMPPConnection constructors do not establish a connection to the server and you must call
connect()
.The CallbackHandler will only be used if the connection requires the client provide an SSL certificate to the server. The CallbackHandler must handle the PasswordCallback to prompt for a password to unlock the keystore containing the SSL certificate.
serviceName
- the name of the XMPP server to connect to; e.g. example.com.callbackHandler
- the CallbackHandler used to prompt for the password to the keystore.public XMPPConnection(String serviceName)
XMPPConnection(String,CallbackHandler)
does, but
with no callback handler for password prompting of the keystore. This will work
in most cases, provided the client is not required to provide a certificate to
the server.
serviceName
- the name of the XMPP server to connect to; e.g. example.com.public XMPPConnection(ConnectionConfiguration config)
XMPPConnection(ConnectionConfiguration,CallbackHandler)
does, but
with no callback handler for password prompting of the keystore. This will work
in most cases, provided the client is not required to provide a certificate to
the server.
config
- the connection configuration.public XMPPConnection(ConnectionConfiguration config, javax.security.auth.callback.CallbackHandler callbackHandler)
Manually specifying connection configuration information is suitable for advanced users of the API. In many cases, using the
XMPPConnection(String)
constructor is a better approach.Note that XMPPConnection constructors do not establish a connection to the server and you must call
connect()
.The CallbackHandler will only be used if the connection requires the client provide an SSL certificate to the server. The CallbackHandler must handle the PasswordCallback to prompt for a password to unlock the keystore containing the SSL certificate.
config
- the connection configuration.callbackHandler
- the CallbackHandler used to prompt for the password to the keystore.Method Detail |
---|
public String getConnectionID()
public String getServiceName()
public String getHost()
public int getPort()
public String getUser()
public void login(String username, String password) throws XMPPException
It is possible to log in without sending an initial available presence by using
ConnectionConfiguration.setSendPresence(boolean)
. If this connection is
not interested in loading its roster upon login then use
ConnectionConfiguration.setRosterLoadedAtLogin(boolean)
.
Finally, if you want to not pass a password and instead use a more advanced mechanism
while using SASL then you may be interested in using
ConnectionConfiguration.setCallbackHandler(javax.security.auth.callback.CallbackHandler)
.
For more advanced login settings see ConnectionConfiguration
.
username
- the username.password
- the password or null if using a CallbackHandler.
XMPPException
- if an error occurs.public void login(String username, String password, String resource) throws XMPPException
Before logging in (i.e. authenticate) to the server the connection must be connected. For compatibility and easiness of use the connection will automatically connect to the server if not already connected.
It is possible to log in without sending an initial available presence by using
ConnectionConfiguration.setSendPresence(boolean)
. If this connection is
not interested in loading its roster upon login then use
ConnectionConfiguration.setRosterLoadedAtLogin(boolean)
.
Finally, if you want to not pass a password and instead use a more advanced mechanism
while using SASL then you may be interested in using
ConnectionConfiguration.setCallbackHandler(javax.security.auth.callback.CallbackHandler)
.
For more advanced login settings see ConnectionConfiguration
.
username
- the username.password
- the password or null if using a CallbackHandler.resource
- the resource.
XMPPException
- if an error occurs.
IllegalStateException
- if not connected to the server, or already logged in
to the serrver.public void loginAnonymously() throws XMPPException
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.public Roster getRoster()
public AccountManager getAccountManager()
public ChatManager getChatManager()
public boolean isConnected()
public boolean isSecureConnection()
public boolean isAuthenticated()
public boolean isAnonymous()
protected void shutdown(Presence unavailablePresence)
disconnect()
the connection's
packet reader, packet writer, and Roster
will not be removed; thus
connection's state is kept.
unavailablePresence
- the presence packet to send during shutdown.public void disconnect()
This method cleans up all resources used by the connection. Therefore, the roster, listeners and other stateful objects cannot be re-used by simply calling connect() on this connection again. This is unlike the behavior during unexpected disconnects (and subsequent connections). In that case, all state is preserved to allow for more seamless error recovery.
public void disconnect(Presence unavailablePresence)
This method cleans up all resources used by the connection. Therefore, the roster, listeners and other stateful objects cannot be re-used by simply calling connect() on this connection again. This is unlike the behavior during unexpected disconnects (and subsequent connections). In that case, all state is preserved to allow for more seamless error recovery.
unavailablePresence
- the presence packet to send during shutdown.public void sendPacket(Packet packet)
packet
- the packet to send.public void addPacketListener(PacketListener packetListener, PacketFilter packetFilter)
packetListener
- the packet listener to notify of new packets.packetFilter
- the packet filter to use.public void removePacketListener(PacketListener packetListener)
packetListener
- the packet listener to remove.public void addPacketWriterListener(PacketListener packetListener, PacketFilter packetFilter)
packetListener
- the packet listener to notify of sent packets.packetFilter
- the packet filter to use.public void removePacketWriterListener(PacketListener packetListener)
packetListener
- the packet listener to remove.public void addPacketWriterInterceptor(PacketInterceptor packetInterceptor, PacketFilter packetFilter)
packetInterceptor
- the packet interceptor to notify of packets about to be sent.packetFilter
- the packet filter to use.public void removePacketWriterInterceptor(PacketInterceptor packetInterceptor)
packetInterceptor
- the packet interceptor to remove.public PacketCollector createPacketCollector(PacketFilter packetFilter)
packetFilter
- the packet filter to use.
public void addConnectionListener(ConnectionListener connectionListener)
connectionListener
- a connection listener.public void removeConnectionListener(ConnectionListener connectionListener)
connectionListener
- a connection listener.public static void addConnectionCreationListener(ConnectionCreationListener connectionCreationListener)
connectionCreationListener
- a listener interested on new connections.public static void removeConnectionCreationListener(ConnectionCreationListener connectionCreationListener)
connectionCreationListener
- a listener interested on new connections.public boolean isUsingTLS()
public SASLAuthentication getSASLAuthentication()
protected ConnectionConfiguration getConfiguration()
public boolean isUsingCompression()
Note: to use stream compression the smackx.jar file has to be present in the classpath.
public void connect() throws XMPPException
Listeners will be preserved from a previous connection if the reconnection occurs after an abrupt termination.
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.
|
Smack | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |