* *
* // Create a connection to the igniterealtime.org XMPP server.
* XMPPConnection 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.
* Chat chat = ChatManager.getInstanceFor(con).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();
*
* * Connections can be reused between connections. This means that an Connection may be connected, * disconnected and then connected again. Listeners of the Connection will be retained across * connections. * * @author Matt Tucker * @author Guenther Niess */ @SuppressWarnings("javadoc") public interface XMPPConnection { /** * Returns the name of the service provided by the XMPP server for this connection. * This is also called XMPP domain of the connected server. After * authenticating with the server the returned value may be different. * * @return the name of the service provided by the XMPP server. */ public String getServiceName(); /** * Returns the host name of the server where the XMPP server is running. This would be the * IP address of the server or a name that may be resolved by a DNS server. * * @return the host name of the server where the XMPP server is running or null if not yet connected. */ public String getHost(); /** * Returns the port number of the XMPP server for this connection. The default port * for normal connections is 5222. * * @return the port number of the XMPP server or 0 if not yet connected. */ public int getPort(); /** * 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. * * @return the full XMPP address of the user logged in. */ public String getUser(); /** * 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. This value will be null if not connected to the server. * * @return the ID of this connection returned from the XMPP server or null if * not connected to the server. */ public String getConnectionID(); /** * Returns true if currently connected to the XMPP server. * * @return true if connected. */ public boolean isConnected(); /** * Returns true if currently authenticated by successfully calling the login method. * * @return true if authenticated. */ public boolean isAuthenticated(); /** * Returns true if currently authenticated anonymously. * * @return true if authenticated anonymously. */ public boolean isAnonymous(); /** * Returns true if the connection to the server has successfully negotiated encryption. * * @return true if a secure connection to the server. */ public boolean isSecureConnection(); /** * Returns true if network traffic is being compressed. When using stream compression network * traffic can be reduced up to 90%. Therefore, stream compression is ideal when using a slow * speed network connection. However, the server will need to use more CPU time in order to * un/compress network data so under high load the server performance might be affected. * * @return true if network traffic is being compressed. */ public boolean isUsingCompression(); /** * Returns the configuration used to connect to the server. * * @return the configuration used to connect to the server. */ public ConnectionConfiguration getConfiguration(); /** * Sends the specified packet to the server. * * @param packet the packet to send. * @throws NotConnectedException */ public void sendPacket(Packet packet) throws NotConnectedException; /** * Returns the roster for the user. *
* This method will never return null, instead if the user has not yet logged into
* the server or is logged in anonymously all modifying methods of the returned roster object
* like {@link Roster#createEntry(String, String, String[])},
* {@link Roster#removeEntry(RosterEntry)} , etc. except adding or removing
* {@link RosterListener}s will throw an IllegalStateException.
*
* @return the user's roster.
* @throws IllegalStateException if the connection is anonymous
*/
public Roster getRoster();
/**
* Adds a connection listener to this connection that will be notified when
* the connection closes or fails.
*
* @param connectionListener a connection listener.
*/
public void addConnectionListener(ConnectionListener connectionListener);
/**
* Removes a connection listener from this connection.
*
* @param connectionListener a connection listener.
*/
public void removeConnectionListener(ConnectionListener connectionListener);
/**
* Creates a new packet collector collecting packets that are replies to packet.
* Does also send packet. The packet filter for the collector is an
* {@link IQReplyFilter}, guaranteeing that packet id and JID in the 'from' address have
* expected values.
*
* @param packet the packet to filter responses from
* @return a new packet collector.
* @throws NotConnectedException
*/
public PacketCollector createPacketCollectorAndSend(IQ packet) throws NotConnectedException;
/**
* Creates a new packet collector for this connection. A packet filter determines
* which packets will be accumulated by the collector. A PacketCollector is
* more suitable to use than a {@link PacketListener} when you need to wait for
* a specific result.
*
* @param packetFilter the packet filter to use.
* @return a new packet collector.
*/
public PacketCollector createPacketCollector(PacketFilter packetFilter);
/**
* Remove a packet collector of this connection.
*
* @param collector a packet collectors which was created for this connection.
*/
public void removePacketCollector(PacketCollector collector);
/**
* Registers a packet listener with this connection. A packet listener will be invoked only
* when an incoming packet is received. A packet filter determines
* which packets will be delivered to the listener. If the same packet listener
* is added again with a different filter, only the new filter will be used.
*
* NOTE: If you want get a similar callback for outgoing packets, see {@link #addPacketInterceptor(PacketInterceptor, PacketFilter)}.
*
* @param packetListener the packet listener to notify of new received packets.
* @param packetFilter the packet filter to use.
*/
public void addPacketListener(PacketListener packetListener, PacketFilter packetFilter);
/**
* Removes a packet listener for received packets from this connection.
*
* @param packetListener the packet listener to remove.
*/
public void removePacketListener(PacketListener packetListener);
/**
* 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. Note that the thread
* that writes packets will be used to invoke the listeners. Therefore, each
* packet listener should complete all operations quickly or use a different
* thread for processing.
*
* @param packetListener the packet listener to notify of sent packets.
* @param packetFilter the packet filter to use.
*/
public void addPacketSendingListener(PacketListener packetListener, PacketFilter packetFilter);
/**
* Removes a packet listener for sending packets from this connection.
*
* @param packetListener the packet listener to remove.
*/
public void removePacketSendingListener(PacketListener packetListener);
/**
* Registers a packet interceptor with this connection. The interceptor will be
* invoked every time a packet is about to be sent by this connection. Interceptors
* may modify the packet to be sent. A packet filter determines which packets
* will be delivered to the interceptor.
*
*
* NOTE: For a similar functionality on incoming packets, see {@link #addPacketListener(PacketListener, PacketFilter)}. * * @param packetInterceptor the packet interceptor to notify of packets about to be sent. * @param packetFilter the packet filter to use. */ public void addPacketInterceptor(PacketInterceptor packetInterceptor, PacketFilter packetFilter); /** * Removes a packet interceptor. * * @param packetInterceptor the packet interceptor to remove. */ public void removePacketInterceptor(PacketInterceptor packetInterceptor); /** * Retrieve the servers Entity Caps node * * XMPPConnection holds this information in order to avoid a dependency to * smackx where EntityCapsManager lives from smack. * * @return the servers entity caps node */ public String getServiceCapsNode(); /** * Returns true if the server supports roster versioning as defined in XEP-0237. * * @return true if the server supports roster versioning */ public boolean isRosterVersioningSupported(); /** * Returns the current value of the reply timeout in milliseconds for request for this * XMPPConnection instance. * * @return the packet reply timeout in milliseconds */ public long getPacketReplyTimeout(); /** * Set the packet reply timeout in milliseconds. In most cases, Smack will throw a * {@link NoResponseException} if no reply to a request was received within the timeout period. * * @param timeout the packet reply timeout in milliseconds */ public void setPacketReplyTimeout(long timeout); /** * Get the connection counter of this XMPPConnection instance. Those can be used as ID to * identify the connection, but beware that the ID may not be unique if you create more then * 2*Integer.MAX_VALUE instances as the counter could wrap. * * @return the connection counter of this XMPPConnection */ public int getConnectionCounter(); public static enum FromMode { /** * Leave the 'from' attribute unchanged. This is the behavior of Smack < 4.0 */ UNCHANGED, /** * Omit the 'from' attribute. According to RFC 6120 8.1.2.1 1. XMPP servers "MUST (...) * override the 'from' attribute specified by the client". It is therefore safe to specify * FromMode.OMITTED here. */ OMITTED, /** * Set the from to the clients full JID. This is usually not required. */ USER } /** * Set the FromMode for this connection instance. Defines how the 'from' attribute of outgoing * stanzas should be populated by Smack. * * @param fromMode */ public void setFromMode(FromMode fromMode); /** * Get the currently active FromMode. * * @return the currently active {@link FromMode} */ public FromMode getFromMode(); /** * Schedule a Runnable related to this connection. *
* It is possible that the connection is blocked if the Runnable takes a considerably long * amount to complete. So either make sure that it always finishes within a reasonably fast or * use your own ScheduledExecutorService. * * @param command * @param delay * @param unit * @return the ScheduldedFuture */ public ScheduledFuture schedule(Runnable command, long delay, TimeUnit unit); }