Smack: Getting Started

Back

This document will introduce you to the Smack API and provide an overview of important classes and concepts.

Smack Modules and Requirements

Smack is meant to be easily embedded into any existing Java application. The library ships as several modules to provide more flexibility over which features applications require:

Configuration

Smack 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 org.jivesoftware.smack/smack- config.xml. This particular configuration contains a list of initializer classes to load. All manager type classes that need to be initialized are contained in this list of initializers.

Establishing a Connection

The XMPPTCPConnection class is used to create a connection to an XMPP server. Below are code examples for making a connection:

// Create a connection and login to the example.org XMPP service.
AbstractXMPPConnection conn1 = new XMPPTCPConnection("username", "password", "example.org");
conn1.connect().login();

Further connection parameters can be configured by using a configuration builder:

// Create a connection to the jabber.org server on a specific port.
XMPPTCPConnectionConfiguration config = XMPPTCPConnectionConfiguration.builder()
  .setUsernameAndPassword("username", "password")
  .setXmppDomain("jabber.org")
  .setHost("earl.jabber.org")
  .setPort(8222)
  .build();

AbstractXMPPConnection conn2 = new XMPPTCPConnection(config);
conn2.connect().login();

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 XMPPConnection Management for full details.

Once you've created a connection, you should login with the XMPPConnection.login() method. Once you've logged in, you can begin chatting with other users by creating new Chat or MultiUserChat objects.

Working with the Roster

The 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 Roster.getInstanceFor(XMPPConnection) 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 Stanzas

Each 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 stanza (assume we have an XMPPConnection instance called "con").
con.sendStanza(presence);

Smack provides two ways to read incoming packets: StanzaListener, and StanzaCollector. Both use StanzaFilter instances to determine which stanzas should be processed. A stanza listener is used for event style programming, while a stanza collector has a result queue of packets that you can do polling and blocking operations on. So, a stanza listener is useful when you want to take some action whenever a stanza happens to come in, while a stanza collector is useful when you want to wait for a specific packet to arrive. Stanza collectors and listeners can be created using an Connection instance.

Copyright (C) Jive Software 2002-2008