This document will introduce you to the Smack API and provide an overview of important classes and concepts.
JAR Files and RequirementsSmack is meant to be easily embedded into any existing JDK 1.5 or later Java application. It has no external dependencies (except for the Jingle voice chat functionality) and is optimized to be as small as possible. The library ships as several JAR files to provide more flexibility over which features applications require:
ConfigurationSmack has an initialization process that involves 2 phases.
Initialization is accomplished via a configuration file. By default, Smack will load the one embedded in the Smack jar at META-INF/smack-config.xml. This particular configuration contains all the default property values as well as a list of initializer classes to load. All manager type classes are contained in this list of initializers. If your application does not use all the features provided by Smack via the aforementioned managers, you may want to 'turn them off' by providing a custom config file that does not include that feature.
If you want to change the configuration file used, you have two options:
Please note, there is a copy of the smack-config.xml in the samples directory of the deployment archive file (zip or tar).
Establishing a ConnectionThe XMPPConnection class is used to create a connection to an XMPP server. Below are code examples for making a connection:
// Create a connection to the jabber.org server. Connection conn1 = new XMPPConnection("jabber.org"); conn1.connect(); // Create a connection to the jabber.org server on a specific port. ConnectionConfiguration config = new ConnectionConfiguration("jabber.org", 5222); Connection conn2 = new XMPPConnection(config); conn2.connect();
Note that maximum security will be used when connecting to the server by default (and when possible), including use of TLS encryption. The ConnectionConfiguration class provides advanced control over the connection created, such as the ability to disable or require encryption. See Connection Management for full details.
Once you've created a connection, you should login using a username and password with the Connection.login(String username, String password) method. Once you've logged in, you can being chatting with other users by creating new Chat or GroupChat objects.
Working with the RosterThe roster lets you keep track of the availability (presence) of other users. Users can be organized into groups such as "Friends" and "Co-workers", and then you discover whether each user is online or offline.
Retrieve the roster using the Connection.getRoster() method. The roster class allows you to find all the roster entries, the groups they belong to, and the current presence status of each entry.
Reading and Writing PacketsEach message to the XMPP server from a client is called a packet and is sent as XML. The org.jivesoftware.smack.packet package contains classes that encapsulate the three different basic packet types allowed by XMPP (message, presence, and IQ). Classes such as Chat and GroupChat provide higher-level constructs that manage creating and sending packets automatically, but you can also create and send packets directly. Below is a code example for changing your presence to let people know you're unavailable and "out fishing":
// Create a new presence. Pass in false to indicate we're unavailable. Presence presence = new Presence(Presence.Type.unavailable); presence.setStatus("Gone fishing"); // Send the packet (assume we have a Connection instance called "con"). con.sendPacket(presence);
Smack provides two ways to read incoming packets: PacketListener, and PacketCollector. Both use PacketFilter instances to determine which packets should be processed. A packet listener is used for event style programming, while a packet collector has a result queue of packets that you can do polling and blocking operations on. So, a packet listener is useful when you want to take some action whenever a packet happens to come in, while a packet collector is useful when you want to wait for a specific packet to arrive. Packet collectors and listeners can be created using an Connection instance.