1. Introduction
XMPP is a rich and complex instant messaging protocol.
Instead of writing our own client from scratch, in this tutorial, we’ll take a look at Smack, a modular and portable open source XMPP client written in Java that has done much of the heavy lifting for us.
2. Dependencies
Smack is organized as several modules to provide more flexibility, so we can easily include the features we need.
Some of these include:
- XMPP over TCP module
- A module to support many of the extensions defined by the XMPP Standards Foundation
- Legacy extensions support
- A module to debug
We can find all the supported modules in XMPP’s documentation.
However, in this tutorial, we’ll just make use of the tcp, im, extensions, and java7 modules:
<dependency> <groupId>org.igniterealtime.smack</groupId> <artifactId>smack-tcp</artifactId> </dependency> <dependency> <groupId>org.igniterealtime.smack</groupId> <artifactId>smack-im</artifactId> </dependency> <dependency> <groupId>org.igniterealtime.smack</groupId> <artifactId>smack-extensions</artifactId> </dependency> <dependency> <groupId>org.igniterealtime.smack</groupId> <artifactId>smack-java7</artifactId> </dependency>
The latest versions can be found at Maven Central.
3. Setup
In order to test the client, we’ll need an XMPP server. To do so, we’ll create an account on jabber.hot-chilli.net, a free Jabber/XMPP service for everybody.
Afterward, we can configure Smack using the XMPPTCPConnectionConfiguration class that provides a builder to set up the connection’s parameters:
XMPPTCPConnectionConfiguration config = XMPPTCPConnectionConfiguration.builder() .setUsernameAndPassword("baeldung","baeldung") .setXmppDomain("jabb3r.org") .setHost("jabb3r.org") .build();
The builder allows us to set the basic information needed to perform a connection. If needed, we can also set other parameters such as port, SSL protocols, and timeouts.
4. Connection
Making a connection is simply achieved using the XMPPTCPConnection class:
AbstractXMPPConnection connection = new XMPPTCPConnection(config); connection.connect(); //Establishes a connection to the server connection.login(); //Logs in
The class contains a constructor that accepts the configuration previously built. It also provides methods to connect to the server and log in.
Once a connection has been established, we can use Smack’s features, like chat, that we’ll describe in the next section.
In the event that the connection was suddenly interrupted, by default, Smack will try to reconnect.
The ReconnectionManager will try to immediately reconnect to the server and increase the delay between attempts as successive reconnections keep failing.
5. Chat
One of the major features of the library is – chat support.
Using the Chat class makes possible to create a new thread of messages between two users:
ChatManager chatManager = ChatManager.getInstanceFor(connection); EntityBareJid jid = JidCreate.entityBareFrom("baeldung2@jabb3r.org"); Chat chat = chatManager.chatWith(jid);
Note that, to build a Chat we used a ChatManager and, obviously, specified who to chat with. We achieved the latter by using the EntityBareJid object, which wraps an XMPP address —aka a JID— composed of a local part (baeldung2) and a domain part (jabb3r.org).
After that, we can send a message using the send() method:
chat.send("Hello!");
And receive messages by setting a listener:
chatManager.addIncomingListener(new IncomingChatMessageListener() { @Override public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) { System.out.println("New message from " + from + ": " + message.getBody()); } });
5.1. Rooms
As well as end-to-end user chat, Smack provides support for group chats through the use of rooms.
There are two types of rooms, instant rooms, and reserved rooms.
Instant rooms are available for immediate access and are automatically created based on some default configuration. On the other hand, reserved rooms are manually configured by the room owner before anyone is allowed to enter.
Let’s have a look at how to create an instant room using MultiUserChatManager:
MultiUserChatManager manager = MultiUserChatManager.getInstanceFor(connection); MultiUserChat muc = manager.getMultiUserChat(jid); Resourcepart room = Resourcepart.from("baeldung_room"); muc.create(room).makeInstant();
In a similar fashion we can create a reserved room:
Set<Jid> owners = JidUtil.jidSetFrom( new String[] { "baeldung@jabb3r.org", "baeldung2@jabb3r.org" }); muc.create(room) .getConfigFormManger() .setRoomOwners(owners) .submitConfigurationForm();
6. Roster
Another feature that Smack provides is the possibility to track the presence of other users.
With Roster.getInstanceFor(), we can obtain a Roster instance:
Roster roster = Roster.getInstanceFor(connection);
The Roster is a contact list that represents the users as RosterEntry objects and allows us to organize users into groups.
We can print all entries in the Roster using the getEntries() method:
Collection<RosterEntry> entries = roster.getEntries(); for (RosterEntry entry : entries) { System.out.println(entry); }
Moreover, it allows us to listen for changes in its entries and presence data with a RosterListener:
roster.addRosterListener(new RosterListener() { public void entriesAdded(Collection<String> addresses) { // handle new entries } public void entriesDeleted(Collection<String> addresses) { // handle deleted entries } public void entriesUpdated(Collection<String> addresses) { // handle updated entries } public void presenceChanged(Presence presence) { // handle presence change } });
It also provides a way to protect user’s privacy by making sure that only approved users are able to subscribe to a roster. To do so, Smack implements a permissions-based model.
There are three ways to handle presence subscription requests with the Roster.setSubscriptionMode() method:
- Roster.SubscriptionMode.accept_all – Accept all subscription requests
- Roster.SubscriptionMode.reject_all – Reject all subscription requests
- Roster.SubscriptionMode.manual – Process presence subscription requests manually
If we choose to handle subscription requests manually, we’ll need to register a StanzaListener (described in next section) and handle packets with the Presence.Type.subscribe type.
7. Stanza
In addition to the chat, Smack provides a flexible framework to send a stanza and listen for incoming one.
To clarify, a stanza is a discrete semantic unit of meaning in XMPP. It is structured information that is sent from one entity to another over an XML stream.
We can transmit a Stanza through a Connection using the send() method:
Stanza presence = new Presence(Presence.Type.subscribe); connection.sendStanza(presence);
In the example above, we sent a Presence stanza to subscribe to a roster.
On the other hand, to process the incoming stanzas, the library provides two constructs:
- StanzaCollector
- StanzaListener
In particular, StanzaCollector let us wait synchronously for new stanzas:
StanzaCollector collector = connection.createStanzaCollector(StanzaTypeFilter.MESSAGE); Stanza stanza = collector.nextResult();
While StanzaListener is an interface for asynchronously notifying us of incoming stanzas:
connection.addAsyncStanzaListener(new StanzaListener() { public void processStanza(Stanza stanza) throws SmackException.NotConnectedException,InterruptedException, SmackException.NotLoggedInException { // handle stanza } }, StanzaTypeFilter.MESSAGE);
7.1. Filters
Moreover, the library provides a built-in set of filters to process incoming stanzas.
We can filter stanza by type using StanzaTypeFilter or by ID with StanzaIdFilter:
StanzaFilter messageFilter = StanzaTypeFilter.MESSAGE; StanzaFilter idFilter = new StanzaIdFilter("123456");
Or, discerning by particular address:
StanzaFilter fromFilter = FromMatchesFilter.create(JidCreate.from("baeldung@jabb3r.org")); StanzaFilter toFilter = ToMatchesFilter.create(JidCreate.from("baeldung2@jabb3r.org"));
And we can use logical filter operator (AndFilter, OrFilter, NotFilter) to create complex filters:
StanzaFilter filter = new AndFilter(StanzaTypeFilter.Message, FromMatchesFilter.create("baeldung@jabb3r.org"));
8. Conclusion
In this article, we covered the most useful classes that Smack provides off the shelf.
We learned how to configure the library in order to send and receive XMPP stanza.
Subsequently, we learned how to handle group chats using ChatManager and Roster features.
As usual, all code samples shown in this tutorial are available over on GitHub.