public interface XMPPConnection
XMPPTCPConnection
or XMPPBOSHConnection
). To create a connection to an XMPP server
a simple usage of this API might look like the following:
// Create a connection to the igniterealtime.org XMPP server. XMPPTCPConnection con = new XMPPTCPConnection("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. ChatManager chatManager = ChatManager.getInstanceFor(con); chatManager.addIncomingListener(new IncomingChatMessageListener() { public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) { // Print out any messages we get back to standard out. System.out.println("Received message: " + message); } }); Chat chat = chatManager.chatWith("jdoe@igniterealtime.org"); chat.send("Howdy!"); // Disconnect from the server con.disconnect();
Note that the XMPPConnection interface does intentionally not declare any methods that manipulate
the connection state, e.g. connect()
, disconnect()
. You should use the
most specific connection type, e.g. XMPPTCPConnection
as declared type and use the
XMPPConnection interface when you don't need to manipulate the connection state.
XMPPConnections can be reused between connections. This means that an Connection may be connected, disconnected and then connected again. Listeners of the XMPPConnection will be retained across connections.
Modifier and Type | Interface and Description |
---|---|
static class |
XMPPConnection.FromMode |
Modifier and Type | Method and Description |
---|---|
void |
addAsyncStanzaListener(StanzaListener stanzaListener,
StanzaFilter stanzaFilter)
Registers an asynchronous stanza listener with this connection.
|
void |
addConnectionListener(ConnectionListener connectionListener)
Adds a connection listener to this connection that will be notified when
the connection closes or fails.
|
void |
addOneTimeSyncCallback(StanzaListener callback,
StanzaFilter stanzaFilter)
Add a callback that is called exactly once and synchronously with the incoming stanza that matches the given
stanza filter.
|
void |
addPacketInterceptor(StanzaListener stanzaInterceptor,
StanzaFilter stanzaFilter)
|
void |
addPacketSendingListener(StanzaListener stanzaListener,
StanzaFilter stanzaFilter)
|
void |
addStanzaInterceptor(StanzaListener stanzaInterceptor,
StanzaFilter stanzaFilter)
Registers a stanza interceptor with this connection.
|
void |
addStanzaSendingListener(StanzaListener stanzaListener,
StanzaFilter stanzaFilter)
Registers a stanza listener with this connection.
|
void |
addSyncStanzaListener(StanzaListener stanzaListener,
StanzaFilter stanzaFilter)
Registers a synchronous stanza listener with this connection.
|
StanzaCollector |
createStanzaCollector(StanzaCollector.Configuration configuration)
Create a new stanza collector with the given stanza collector configuration.
|
StanzaCollector |
createStanzaCollector(StanzaFilter stanzaFilter)
Creates a new stanza collector for this connection.
|
StanzaCollector |
createStanzaCollectorAndSend(IQ request)
Creates a new stanza collector collecting IQ responses that are replies to the IQ
request . |
StanzaCollector |
createStanzaCollectorAndSend(StanzaFilter stanzaFilter,
Stanza stanza)
Creates a new stanza collector for this connection.
|
int |
getConnectionCounter()
Get the connection counter of this XMPPConnection instance.
|
<F extends ExtensionElement> |
getFeature(String element,
String namespace)
Get the feature stanza extensions for a given stream feature of the
server, or
null if the server doesn't support that feature. |
XMPPConnection.FromMode |
getFromMode()
Get the currently active FromMode.
|
String |
getHost()
Returns the host name of the server where the XMPP server is running.
|
long |
getLastStanzaReceived()
Returns the timestamp in milliseconds when the last stanza was received.
|
int |
getPort()
Returns the port number of the XMPP server for this connection.
|
long |
getReplyTimeout()
Returns the current value of the reply timeout in milliseconds for request for this
XMPPConnection instance.
|
String |
getStreamId()
Returns the stream ID for this connection, which is the value set by the server
when opening an XMPP stream.
|
EntityFullJid |
getUser()
Returns the full XMPP address of the user that is logged in to the connection or
null if not logged in yet.
|
DomainBareJid |
getXMPPServiceDomain()
Returns the XMPP Domain of the service provided by the XMPP server and used for this connection.
|
boolean |
hasFeature(String element,
String namespace)
Return true if the server supports the given stream feature.
|
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 encryption.
|
boolean |
isUsingCompression()
Returns true if network traffic is being compressed.
|
IQRequestHandler |
registerIQRequestHandler(IQRequestHandler iqRequestHandler)
Register an IQ request handler with this connection.
|
boolean |
removeAsyncStanzaListener(StanzaListener stanzaListener)
Removes an asynchronous stanza listener for received stanzas from this connection.
|
void |
removeConnectionListener(ConnectionListener connectionListener)
Removes a connection listener from this connection.
|
void |
removePacketInterceptor(StanzaListener stanzaInterceptor)
Deprecated.
|
void |
removePacketSendingListener(StanzaListener stanzaListener)
Deprecated.
|
void |
removeStanzaCollector(StanzaCollector collector)
Remove a stanza collector of this connection.
|
void |
removeStanzaInterceptor(StanzaListener stanzaInterceptor)
Removes a stanza interceptor.
|
void |
removeStanzaSendingListener(StanzaListener stanzaListener)
Removes a stanza listener for sending stanzas from this connection.
|
boolean |
removeSyncStanzaListener(StanzaListener stanzaListener)
Removes a stanza listener for received stanzas from this connection.
|
<S extends Stanza> |
sendAsync(S stanza,
StanzaFilter replyFilter)
Send a stanza asynchronously, waiting for exactly one response stanza using the given reply filter.
|
<S extends Stanza> |
sendAsync(S stanza,
StanzaFilter replyFilter,
long timeout)
Send a stanza asynchronously, waiting for exactly one response stanza using the given reply filter.
|
<I extends IQ> |
sendIqRequestAndWaitForResponse(IQ request)
Send an IQ request and wait for the response.
|
SmackFuture<IQ,Exception> |
sendIqRequestAsync(IQ request)
Send an IQ request asynchronously.
|
SmackFuture<IQ,Exception> |
sendIqRequestAsync(IQ request,
long timeout)
Send an IQ request asynchronously.
|
void |
sendIqWithResponseCallback(IQ iqRequest,
StanzaListener callback)
Deprecated.
use
sendIqRequestAsync(IQ) instead. |
void |
sendIqWithResponseCallback(IQ iqRequest,
StanzaListener callback,
ExceptionCallback exceptionCallback)
Deprecated.
use
sendIqRequestAsync(IQ) instead. |
void |
sendIqWithResponseCallback(IQ iqRequest,
StanzaListener callback,
ExceptionCallback exceptionCallback,
long timeout)
Deprecated.
use
sendIqRequestAsync(IQ, long) instead. |
void |
sendNonza(Nonza nonza)
Send a Nonza.
|
void |
sendStanza(Stanza stanza)
Sends the specified stanza to the server.
|
void |
sendStanzaWithResponseCallback(Stanza stanza,
StanzaFilter replyFilter,
StanzaListener callback)
Deprecated.
use
sendAsync(Stanza, StanzaFilter) instead. |
void |
sendStanzaWithResponseCallback(Stanza stanza,
StanzaFilter replyFilter,
StanzaListener callback,
ExceptionCallback exceptionCallback)
Deprecated.
use
sendAsync(Stanza, StanzaFilter) instead. |
void |
sendStanzaWithResponseCallback(Stanza stanza,
StanzaFilter replyFilter,
StanzaListener callback,
ExceptionCallback exceptionCallback,
long timeout)
Deprecated.
use
sendAsync(Stanza, StanzaFilter, long) instead. |
void |
setFromMode(XMPPConnection.FromMode fromMode)
Set the FromMode for this connection instance.
|
void |
setReplyTimeout(long timeout)
Set the stanza reply timeout in milliseconds.
|
IQRequestHandler |
unregisterIQRequestHandler(IQRequestHandler iqRequestHandler)
Convenience method for
unregisterIQRequestHandler(String, String, org.jivesoftware.smack.packet.IQ.Type) . |
IQRequestHandler |
unregisterIQRequestHandler(String element,
String namespace,
IQ.Type type)
Unregister an IQ request handler with this connection.
|
DomainBareJid getXMPPServiceDomain()
String getHost()
int getPort()
EntityFullJid getUser()
String getStreamId()
boolean isConnected()
boolean isAuthenticated()
boolean isAnonymous()
boolean isSecureConnection()
boolean isUsingCompression()
void sendStanza(Stanza stanza) throws SmackException.NotConnectedException, InterruptedException
stanza
- the stanza to send.SmackException.NotConnectedException
- if the connection is not connected.InterruptedException
void sendNonza(Nonza nonza) throws SmackException.NotConnectedException, InterruptedException
This method is not meant for end-user usage! It allows sending plain stream elements, which should not be done by a user manually. Doing so may result in a unstable or unusable connection. Certain Smack APIs use this method to send plain stream elements.
nonza
- the Nonza to send.SmackException.NotConnectedException
InterruptedException
void addConnectionListener(ConnectionListener connectionListener)
connectionListener
- a connection listener.void removeConnectionListener(ConnectionListener connectionListener)
connectionListener
- a connection listener.<I extends IQ> I sendIqRequestAndWaitForResponse(IQ request) throws SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException
request
- the IQ requestSmackException.NoResponseException
XMPPException.XMPPErrorException
SmackException.NotConnectedException
InterruptedException
StanzaCollector createStanzaCollectorAndSend(IQ request) throws SmackException.NotConnectedException, InterruptedException
request
.
Does also send the request
IQ. The stanza filter for the collector is an
IQReplyFilter
, guaranteeing that stanza id and JID in the 'from' address have
expected values.request
- the IQ request to filter responses fromSmackException.NotConnectedException
InterruptedException
StanzaCollector createStanzaCollectorAndSend(StanzaFilter stanzaFilter, Stanza stanza) throws SmackException.NotConnectedException, InterruptedException
StanzaListener
when you need to wait for
a specific result.stanzaFilter
- the stanza filter to use.stanza
- the stanza to send right after the collector got createdInterruptedException
SmackException.NotConnectedException
StanzaCollector createStanzaCollector(StanzaFilter stanzaFilter)
StanzaListener
when you need to wait for a specific result.
Note: If you send a Stanza right after using this method, then
consider using
createStanzaCollectorAndSend(StanzaFilter, Stanza)
instead.
Otherwise make sure cancel the StanzaCollector in every case, e.g. even
if an exception is thrown, or otherwise you may leak the StanzaCollector.
stanzaFilter
- the stanza filter to use.StanzaCollector createStanzaCollector(StanzaCollector.Configuration configuration)
Please make sure to cancel the collector when it is no longer required. See also
createStanzaCollector(StanzaFilter)
.
configuration
- the stanza collector configuration.void removeStanzaCollector(StanzaCollector collector)
collector
- a stanza collectors which was created for this connection.void addSyncStanzaListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
Important: This stanza listeners will be called in the same single thread that processes all
incoming stanzas. Only use this kind of stanza filter if it does not perform any XMPP activity that waits for a
response. Consider using addAsyncStanzaListener(StanzaListener, StanzaFilter)
when possible, i.e. when
the invocation order doesn't have to be the same as the order of the arriving stanzas. If the order of the
arriving stanzas, consider using a StanzaCollector
when possible.
stanzaListener
- the stanza listener to notify of new received stanzas.stanzaFilter
- the stanza filter to use.addStanzaInterceptor(StanzaListener, StanzaFilter)
boolean removeSyncStanzaListener(StanzaListener stanzaListener)
stanzaListener
- the stanza listener to remove.void addAsyncStanzaListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
Unlike addAsyncStanzaListener(StanzaListener, StanzaFilter)
stanza listeners added with this method will be
invoked asynchronously in their own thread. Use this method if the order of the stanza listeners must not depend
on the order how the stanzas where received.
stanzaListener
- the stanza listener to notify of new received stanzas.stanzaFilter
- the stanza filter to use.addStanzaInterceptor(StanzaListener, StanzaFilter)
boolean removeAsyncStanzaListener(StanzaListener stanzaListener)
stanzaListener
- the stanza listener to remove.@Deprecated void addPacketSendingListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
addStanzaSendingListener(org.jivesoftware.smack.StanzaListener, org.jivesoftware.smack.filter.StanzaFilter)
insteadstanzaListener
- the stanza listener to notify of sent stanzas.stanzaFilter
- the stanza filter to use.void addStanzaSendingListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
stanzaListener
- the stanza listener to notify of sent stanzas.stanzaFilter
- the stanza filter to use.@Deprecated void removePacketSendingListener(StanzaListener stanzaListener)
removeStanzaSendingListener(org.jivesoftware.smack.StanzaListener)
insteadstanzaListener
- the stanza listener to remove.void removeStanzaSendingListener(StanzaListener stanzaListener)
stanzaListener
- the stanza listener to remove.@Deprecated void addPacketInterceptor(StanzaListener stanzaInterceptor, StanzaFilter stanzaFilter)
addStanzaInterceptor(org.jivesoftware.smack.StanzaListener, org.jivesoftware.smack.filter.StanzaFilter)
instead
NOTE: For a similar functionality on incoming stanzas, see addAsyncStanzaListener(StanzaListener, StanzaFilter)
.
stanzaInterceptor
- the stanza interceptor to notify of stanzas about to be sent.stanzaFilter
- the stanza filter to use.void addStanzaInterceptor(StanzaListener stanzaInterceptor, StanzaFilter stanzaFilter)
NOTE: For a similar functionality on incoming stanzas, see addAsyncStanzaListener(StanzaListener, StanzaFilter)
.
stanzaInterceptor
- the stanza interceptor to notify of stanzas about to be sent.stanzaFilter
- the stanza filter to use.@Deprecated void removePacketInterceptor(StanzaListener stanzaInterceptor)
removeStanzaInterceptor(org.jivesoftware.smack.StanzaListener)
insteadstanzaInterceptor
- the stanza interceptor to remove.void removeStanzaInterceptor(StanzaListener stanzaInterceptor)
stanzaInterceptor
- the stanza interceptor to remove.long getReplyTimeout()
void setReplyTimeout(long timeout)
SmackException.NoResponseException
if no reply to a request was received within the timeout period.timeout
- for a reply in millisecondsint getConnectionCounter()
void setFromMode(XMPPConnection.FromMode fromMode)
fromMode
- XMPPConnection.FromMode getFromMode()
XMPPConnection.FromMode
<F extends ExtensionElement> F getFeature(String element, String namespace)
null
if the server doesn't support that feature.F
- ExtensionElement
type of the feature.element
- namespace
- null
boolean hasFeature(String element, String namespace)
element
- namespace
- SmackFuture<IQ,Exception> sendIqRequestAsync(IQ request)
request
- the IQ request to send.SmackFuture<IQ,Exception> sendIqRequestAsync(IQ request, long timeout)
request
- the IQ request to send.timeout
- the reply timeout in milliseconds.<S extends Stanza> SmackFuture<S,Exception> sendAsync(S stanza, StanzaFilter replyFilter)
stanza
- the stanza to send.replyFilter
- the filter used for the response stanza.<S extends Stanza> SmackFuture<S,Exception> sendAsync(S stanza, StanzaFilter replyFilter, long timeout)
stanza
- the stanza to send.replyFilter
- the filter used for the response stanza.timeout
- the reply timeout in milliseconds.@Deprecated void sendStanzaWithResponseCallback(Stanza stanza, StanzaFilter replyFilter, StanzaListener callback) throws SmackException.NotConnectedException, InterruptedException
sendAsync(Stanza, StanzaFilter)
instead.replyFilter
.
If there is a response, then callback
will be invoked. The callback will be
invoked at most once and it will be not invoked after the connections default reply timeout
has been elapsed.
stanza
- the stanza to send (required)replyFilter
- the filter used to determine response stanza (required)callback
- the callback invoked if there is a response (required)SmackException.NotConnectedException
InterruptedException
@Deprecated void sendStanzaWithResponseCallback(Stanza stanza, StanzaFilter replyFilter, StanzaListener callback, ExceptionCallback exceptionCallback) throws SmackException.NotConnectedException, InterruptedException
sendAsync(Stanza, StanzaFilter)
instead.replyFilter
.
If there is a response, then callback
will be invoked. If there is no response
after the connections default reply timeout, then exceptionCallback
will be invoked
with a SmackException.NoResponseException
. The callback will be invoked at most once.
stanza
- the stanza to send (required)replyFilter
- the filter used to determine response stanza (required)callback
- the callback invoked if there is a response (required)exceptionCallback
- the callback invoked if there is an exception (optional)SmackException.NotConnectedException
InterruptedException
@Deprecated void sendStanzaWithResponseCallback(Stanza stanza, StanzaFilter replyFilter, StanzaListener callback, ExceptionCallback exceptionCallback, long timeout) throws SmackException.NotConnectedException, InterruptedException
sendAsync(Stanza, StanzaFilter, long)
instead.replyFilter
.
If there is a response, then callback
will be invoked. If there is no response
after timeout
milliseconds, then exceptionCallback
will be invoked
with a SmackException.NoResponseException
. The callback will be invoked at most once.
stanza
- the stanza to send (required)replyFilter
- the filter used to determine response stanza (required)callback
- the callback invoked if there is a response (required)exceptionCallback
- the callback invoked if there is an exception (optional)timeout
- the timeout in milliseconds to wait for a responseSmackException.NotConnectedException
InterruptedException
@Deprecated void sendIqWithResponseCallback(IQ iqRequest, StanzaListener callback) throws SmackException.NotConnectedException, InterruptedException
sendIqRequestAsync(IQ)
instead.callback
if there is a result of
IQ.Type.result
with that result IQ. The callback will
not be invoked after the connections default reply timeout has been elapsed.iqRequest
- the IQ stanza to send (required)callback
- the callback invoked if there is result response (required)SmackException.NotConnectedException
InterruptedException
@Deprecated void sendIqWithResponseCallback(IQ iqRequest, StanzaListener callback, ExceptionCallback exceptionCallback) throws SmackException.NotConnectedException, InterruptedException
sendIqRequestAsync(IQ)
instead.callback
if there is a result of
IQ.Type.result
with that result IQ. If there is an
error response exceptionCallback
will be invoked, if not null, with the received
error as XMPPException.XMPPErrorException
. If there is no response after the
connections default reply timeout, then exceptionCallback
will be invoked with a
SmackException.NoResponseException
.iqRequest
- the IQ stanza to send (required)callback
- the callback invoked if there is result response (required)exceptionCallback
- the callback invoked if there is an Exception optionalSmackException.NotConnectedException
InterruptedException
@Deprecated void sendIqWithResponseCallback(IQ iqRequest, StanzaListener callback, ExceptionCallback exceptionCallback, long timeout) throws SmackException.NotConnectedException, InterruptedException
sendIqRequestAsync(IQ, long)
instead.callback
if there is a result of
IQ.Type.result
with that result IQ. If there is an
error response exceptionCallback
will be invoked, if not null, with the received
error as XMPPException.XMPPErrorException
. If there is no response after
timeout
, then exceptionCallback
will be invoked with a
SmackException.NoResponseException
.iqRequest
- the IQ stanza to send (required)callback
- the callback invoked if there is result response (required)exceptionCallback
- the callback invoked if there is an Exception optionaltimeout
- the timeout in milliseconds to wait for a responseSmackException.NotConnectedException
InterruptedException
void addOneTimeSyncCallback(StanzaListener callback, StanzaFilter stanzaFilter)
callback
- the callback invoked once the stanza filter matches a stanza.stanzaFilter
- the filter to match stanzas or null to match all.IQRequestHandler registerIQRequestHandler(IQRequestHandler iqRequestHandler)
IQ request handler process incoming IQ requests, i.e. incoming IQ stanzas of type 'get' or 'set', and return a result.
iqRequestHandler
- the IQ request handler to register.IQRequestHandler unregisterIQRequestHandler(IQRequestHandler iqRequestHandler)
unregisterIQRequestHandler(String, String, org.jivesoftware.smack.packet.IQ.Type)
.iqRequestHandler
- IQRequestHandler unregisterIQRequestHandler(String element, String namespace, IQ.Type type)
element
- the IQ element the IQ request handler is responsible for.namespace
- the IQ namespace the IQ request handler is responsible for.type
- the IQ type the IQ request handler is responsible for.long getLastStanzaReceived()