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 |
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(java.lang.String element,
java.lang.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.
|
java.lang.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.
|
java.lang.String |
getStreamId()
Returns the stream ID for this connection, which is the value set by the server
when opening an XMPP stream.
|
org.jxmpp.jid.EntityFullJid |
getUser()
Returns the full XMPP address of the user that is logged in to the connection or
null if not logged in yet.
|
org.jxmpp.jid.DomainBareJid |
getXMPPServiceDomain()
Returns the XMPP Domain of the service provided by the XMPP server and used for this connection.
|
boolean |
hasFeature(java.lang.String element,
java.lang.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 |
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,java.lang.Exception> |
sendIqRequestAsync(IQ request)
Send an IQ request asynchronously.
|
SmackFuture<IQ,java.lang.Exception> |
sendIqRequestAsync(IQ request,
long timeout)
Send an IQ request asynchronously.
|
void |
sendNonza(Nonza nonza)
Send a Nonza.
|
void |
sendStanza(Stanza stanza)
Sends the specified stanza to the server.
|
void |
setFromMode(XMPPConnection.FromMode fromMode)
Set the FromMode for this connection instance.
|
void |
setReplyTimeout(long timeout)
Set the stanza reply timeout in milliseconds.
|
boolean |
trySendStanza(Stanza stanza)
Try to send the given stanza.
|
boolean |
trySendStanza(Stanza stanza,
long timeout,
java.util.concurrent.TimeUnit unit)
Try to send the given stanza.
|
IQRequestHandler |
unregisterIQRequestHandler(IQRequestHandler iqRequestHandler)
Convenience method for
unregisterIQRequestHandler(String, String, org.jivesoftware.smack.packet.IQ.Type). |
IQRequestHandler |
unregisterIQRequestHandler(java.lang.String element,
java.lang.String namespace,
IQ.Type type)
Unregister an IQ request handler with this connection.
|
org.jxmpp.jid.DomainBareJid getXMPPServiceDomain()
java.lang.String getHost()
int getPort()
org.jxmpp.jid.EntityFullJid getUser()
java.lang.String getStreamId()
boolean isConnected()
boolean isAuthenticated()
boolean isAnonymous()
boolean isSecureConnection()
boolean isUsingCompression()
void sendStanza(Stanza stanza) throws SmackException.NotConnectedException, java.lang.InterruptedException
stanza - the stanza to send.SmackException.NotConnectedException - if the connection is not connected.java.lang.InterruptedExceptionboolean trySendStanza(Stanza stanza) throws SmackException.NotConnectedException
true if the stanza was successfully put into the outgoing stanza
queue, otherwise, if false is returned, the stanza could not be scheduled for sending (for example
because the outgoing element queue is full). Note that this means that the stanza possibly was not put onto the
wire, even if true is returned, it just has been successfully scheduled for sending.
Note: Implementations are not required to provide that functionality. In that case this method is mapped
to sendStanza(Stanza) and will possibly block until the stanza could be scheduled for sending.
stanza - the stanza to send.true if the stanza was successfully scheduled to be send, false otherwise.SmackException.NotConnectedException - if the connection is not connected.boolean trySendStanza(Stanza stanza, long timeout, java.util.concurrent.TimeUnit unit) throws SmackException.NotConnectedException, java.lang.InterruptedException
true if the stanza was successfully put into the outgoing stanza
queue within the given timeout period, otherwise, if false is returned, the stanza could not be scheduled
for sending (for example because the outgoing element queue is full). Note that this means that the stanza
possibly was not put onto the wire, even if true is returned, it just has been successfully scheduled for
sending.
Note: Implementations are not required to provide that functionality. In that case this method is mapped
to sendStanza(Stanza) and will possibly block until the stanza could be scheduled for sending.
stanza - the stanza to send.timeout - how long to wait before giving up, in units of unit.unit - a TimeUnit determining how to interpret the timeout parameter.true if the stanza was successfully scheduled to be send, false otherwise.SmackException.NotConnectedException - if the connection is not connected.java.lang.InterruptedException - if the calling thread was interrupted.void sendNonza(Nonza nonza) throws SmackException.NotConnectedException, java.lang.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.NotConnectedExceptionjava.lang.InterruptedExceptionvoid 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, java.lang.InterruptedException
request - the IQ requestSmackException.NoResponseExceptionXMPPException.XMPPErrorExceptionSmackException.NotConnectedExceptionjava.lang.InterruptedExceptionStanzaCollector createStanzaCollectorAndSend(IQ request) throws SmackException.NotConnectedException, java.lang.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.NotConnectedExceptionjava.lang.InterruptedExceptionStanzaCollector createStanzaCollectorAndSend(StanzaFilter stanzaFilter, Stanza stanza) throws SmackException.NotConnectedException, java.lang.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 createdjava.lang.InterruptedExceptionSmackException.NotConnectedExceptionStanzaCollector 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.void addStanzaSendingListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
stanzaListener - the stanza listener to notify of sent stanzas.stanzaFilter - the stanza filter to use.void removeStanzaSendingListener(StanzaListener stanzaListener)
stanzaListener - the stanza listener to remove.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.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(java.lang.String element, java.lang.String namespace)
null if the server doesn't support that feature.F - ExtensionElement type of the feature.element - namespace - nullboolean hasFeature(java.lang.String element,
java.lang.String namespace)
element - namespace - SmackFuture<IQ,java.lang.Exception> sendIqRequestAsync(IQ request)
request - the IQ request to send.SmackFuture<IQ,java.lang.Exception> sendIqRequestAsync(IQ request, long timeout)
request - the IQ request to send.timeout - the reply timeout in milliseconds.<S extends Stanza> SmackFuture<S,java.lang.Exception> sendAsync(S stanza, StanzaFilter replyFilter)
stanza - the stanza to send.replyFilter - the filter used for the response stanza.<S extends Stanza> SmackFuture<S,java.lang.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.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(java.lang.String element, java.lang.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()