Overview
Smack is a library for client-to-server XMPP connections to perform real-time communications and data exchange. This includes, but is not limited to, instant messaging and group chat. More generically speaking, it allows you to easily exchange data in various ways: For example fire-and-forget, publish-subscribe, between human and non-human endpoints. The use cases include M2M, IoT, and many more.
Smack is a pure Java library, open-source and highly modular. It runs on Android and Java SE. The API strives to be easy to use but yet powerful.
Key Advantages
Smack is extremely simple to use, yet provides a powerful API. Sending a text message to a user can be accomplished in only a few lines of code.
AbstractXMPPConnection connection = new XMPPTCPConnection("mtucker", "password", "jabber.org");
connection.connect().login();
Message message = connection.getStanzaFactory()
.buildMessageStanza()
.to("jsmith@igniterealtime.org")
.setBody("Howdy! How are you?")
.build();
connection.sendStanza(message);
connection.disconnect();
Smack doesn't force you to code at the protcol level of XMPP. The library provides intelligent higher level constructs, often called Manager, which let you program more efficiently. Other examples of those constructs are the Chat and Roster classes.
Smack comes with APIs for easy machine-to-machine communication. You can set any number of properties on each message, including properties that are Java objects.
License
Smack is open-source and most parts are under the Apache License 2.0, which means you can incorporate Smack into your commercial or non-commercial applications. Some parts of Smack may be under a different open-source license. Please refer to the individual subprojects for their license statement.
Note that the Apache License 2.0 requires that the contents of a
NOICE text file are shown "…within a display generated by the
Derivative Works, if and wherever such third-party notices normally
appear.". Smack comes with such a NOTICE file. The content of
Smack's NOTICE file can conveniently be retrieved using
Smack.getNoticeStream().
About XMPP
XMPP (eXtensible Messaging and Presence Protocol) is an open protocol standardized by the Internet Engineering Task Force (IETF) and supported and extended by the XMPP Standards Foundation (XSF).
Smack Modules
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.
- smack-core -- provides core XMPP functionality. All XMPP features that are part of the XMPP RFCs are included.
- smack-im -- provides functionality defined in RFC 6121 (XMPP-IM), like the Roster.
smack-tcp-- support for XMPP over TCP. Includes XMPPTCPConnection class, which you usually want to use- smack-extensions -- support for many of the extensions (XEPs) defined by the XMPP Standards Foundation, including multi-user chat, file transfer, user search, etc. The extensions are documented in the [extensions manual](extensions/index.md).
- smack-experimental -- support for experimental extensions (XEPs) defined by the XMPP Standards Foundation. The API and functionality of those extensions should be considered as unstable.
- smack-legacy -- support for legacy extensions (XEPs) defined by the XMPP Standards Foundation.
- smack-bosh -- support for BOSH (XEP-0124). This code should be considered as beta.
- smack-resolver-minidns -- support for resolving DNS SRV records with the help of MiniDNS. Ideal for platforms that do not support the javax.naming API. Also supports [DNSSEC](dnssec.md) TODO: Fix link.
- smack-resolver-dnsjava -- support for resolving DNS SRV records with the help of dnsjava.
- smack-resolver-javax -- support for resolving DNS SRV records with the javax namespace API.
- smack-debug -- an enhanced GUI debugger for protocol traffic. It will automatically be used when found in the classpath and when [debugging](debugging.md) is enabled.
Main API Entry Points
Smack Extensions
Since the X in XMPP stands for eXstensible, Smack comes with many built-in extensions for XMPP. Click
org.jivesoftware.smackxfor an overview of all supporteted XMPP extensions of Smack.
Some selected extensions areConfiguration
Smack has an initialization process that involves 2 phases.
- Initializing system properties - Initializing all the system properties accessible through the class **SmackConfiguration**. These properties are retrieved by the _getXXX_ methods on that class.
- Initializing startup classes - Initializing any classes meant to be active at startup by instantiating the class, and then calling the _initialize_ method on that class if it extends **SmackInitializer**. If it does not extend this interface, then initialization will have to take place in a static block of code which is automatically executed when the class is loaded.
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.
Packages
Package
Description
Examples and tests for Smack.
A REPL (Read Eval Print Loop) for Smack.
Core classes of the Smack API.
Smack's API for XEP-0156: Discovering Alternative XMPP Connection Methods.
Android specific Smack code.
Classes and interfaces for Bind 2.0 (XEP-0386).
Smack's API for BOSH (XEP-206, XEP-124).
Smack's (new) API for client-to-server (c2s) connections.
Smack's internal API for client-to-server (c2s) connections.
Smacks legacy API for 1:1 chats.
Smack's new improved API for 1:1 chats.
Stanzas and extension elements for XMPP stream compression (XEP-138).
Providers for XMPP stream compression (XEP-138).
Smack classes for compression.
Smack classes for compression (XEP-0138) using zlib (RFC 1950).
Custom datatypes for Integers.
Smack includes built-in debugging consoles that will let you track all XML traffic between the client and server.
Classes especially for smack-experimental.
Smacks initializer for extensions.
Allows
StanzaCollector and StanzaListener instances to filter for stanzas with particular attributes.Filter based on the type of an XMPP address.
Smack's Finite State Machine to handle the login logic.
The Smack XMPP client library.
Internal classes for smack-im.
Code used to initialize Smack.
Smack internal classes and interfaces.
Smack's IQ request handler API.
Classes and interfaces for Instant Stream Resumption (ISR) (XEP-0397).
Java7 related classes.
TODO describe me.
XML stanzas and extension elements that are part of the XMPP protocol.
Helper classes for Stanza IDs.
Auxiliary classes for XMPP parsing.
The Smack provider architecture is a system for plugging in custom XML parsing of stanza extensions
(
ExtensionElement, IQ stanzas and
Nonza.Support for XMPP connections over Proxies.
Smacks API for Rosters.
Element classes for Rosters.
Provider classes for Rosters.
Persistence classes for Rosters.
Classes and interfaces for SASL based XMPP authentication.
SASL mechanisms provided by Smack Core.
A javax SASL implementation for Smack.
Stanzas, plain stream- and extension elements for SASL.
A SASL implementation for Smack.
Smack's implementation of XEP-0198: Stream Management.
Plain stream elements for XEP-0198: Stream Management.
Predicates for requesting Stream Management acknowledgements.
XMPPTCPConnection Stream Management Predicates.
Providers for XEP-0198: Stream Management.
TCP-IP related classes for Smack.
Smack's internal API for XMPP connections over TCP.
Utility classes.
Smack's API for DNS related tasks.
A Java DNS resolver implementation for Smack.
A javax DNS resolver implementation for Smack.
A MiniDNS resolver implementation for Smack.
Utility classes for Remote Connection Endpoints (RCE).
Stringencoder utilities.
TODO describe me.
Java7 related classes for Smacks Base64 implementation.
WebSocket related classes for Smack.
This package contains Stanzas required to open and close stream.
This package contains websocket implementations to be plugged inside websocket transport.
WebSocket support for Smack using
WebSocket, which is available since Java 11.Copyright 2020 Aditya Borikar
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
This package contains websocket endpoint classes needed by the websocket transport.
Classes for XML handling.
Classes for XML handling using StAX (Streaming API for XML, JSR 173).
Classes for XML handling using XPP3 (XML Pull Parser 3).
Smack's API for XMPP extensions.
Smack's API for XEP-0033: Extended Stanza Addressing.
Stanzas and extension elements for XEP-0033: Extended Stanzas Addressing.
Providers for XEP-0033: Extended Stanza Addressing.
Smack's API for XEP-0133: Service Administration.
Smack's API for XEP-0079: Advanced Message Processing.
Stanzas and extension elements for XEP-0079: Advanced Message Processing.
Providers for XEP-0079: Advanced Message Processing.
Stanzas and extension elements for XEP-0224: Attention.
Classes and interfaces of Blocking command.
Blocking command elements.
Blocking command providers.
Classes and interfaces of XEP-0231: Bits of Binary.
Bits of Binary elements.
Bits of Binary providers.
Smack's API for XEP-0048: Bookmarks.
Smack's API for XEP-0065: SOCKS5 Bytestreams, as well as XEP-0047: In-Band Bytestreams.
Smack's API for XEP-0047: In-Band Bytestreams.
Stanzas and extension elements for XEP-0047: In-Band Bytestreams.
Providers for XEP-0047: In-Band Bytestreams.
Smack's API for XEP-0065: SOCKS5 Bytestreams.
Stanzas and extension elements for XEP-0065: SOCKS5 Bytestreams.
Providers for XEP-0065: SOCKS5 Bytestreams.
Smacks implementation of XEP-0115: Entity Capabilities, see
EntityCapsManager for more information.Cache classes for XEP-0115: Entity Capabilities.
Element classes for XEP-0115: Entity Capabilities.
Provider classes for XEP-0115: Entity Capabilities.
Smack's API for XEP-0280: Message Carbons.
Stanzas and extension elements for XEP-0280: Message Carbons.
Provider for XEP-0280: Message Carbons.
XEP-0333: Chat Markers.
Chat Markers elements (XEP-0333).
Chat Markers elements (XEP-0333).
Chat Markers providers (XEP-0333).
Classes for Chat States (XEP-0085).
Element classes for XEP-0085: Chat State Notifications.
Provider classes for XEP-0085: Chat State Notifications.
Smack's API for XEP-0392: Consistent Color Generation.
Smacks implementation of XEP-0050: Ad-Hoc Commands.
Element classes for XEP-0050: Ad-Hoc Commands.
Provider classes for XEP-0050: Ad-Hoc Commands.
Smack's API for XEP-0352: Client State Indication.
Plain stream elements for XEP-0352: Client State Indication.
Provider for XEP-0352: Client State Indication.
Smack optional Debuggers, which include
EnhancedDebugger and LiteDebugger.Android classes for debugging purposes.
Smack slf4j debugger implementation.
Smacks implementation of XEP-0203: Delayed Delivery, as well as XEP-0091: Legacy Delayed Delivery.
StanzaFilter classes for XEP-0203: Delayed Delivery, as well as XEP-0091: Legacy Delayed Delivery.
Element classes for XEP-0203: Delayed Delivery, as well as XEP-0091: Legacy Delayed Delivery.
Provider classes for XEP-0203: Delayed Delivery, as well as XEP-0091: Legacy Delayed Delivery.
Smack's API for Service Discovery (XEP-0030).
Element classes for XEP-0030: Service Discovery.
Provider classes for XEP-0030: Service Discovery.
Smack's API for XEP-0418: DNS Queries over XMPP (Dox).
XEP-0418: DNS Queries over XMPP (DoX) XML providers.
XEP-0418: DNS Queries over XMPP (DoX) XML providers.
XEP-0418: DNS Queries over XMPP (Dox) using MiniDNS.
Smack's API for XEP-0380: Explicit Message Encryption.
XMPP extension elements for XEP-0380: Explicit Message Encryption.
Smack Provider for XEP-0380: Explicit Message Encryption.
Smack's API for XEP-0428: Fallback Indication.
Smack's API for XEP-0428: Fallback Indication.
Smack's API for XEP-0428: Fallback Indication.
Smacks implementation of XEP-0446: File Metadata Element.
File metadata element provider.
Smack's API for File Transfers.
Smack's implementation of XEP-0068: Field Standardization for Data Forms.
Element classes for XEP-0297: Stanza Forwarding.
Provider classes for XEP-0297: Stanza Forwarding.
Extension elements for the GCM XMPP extension.
Provider the GCM XMPP extension.
Smacks implementation of XEP-0080: User Location.
Element classes for XEP-0080: User Location.
Provider classes for XEP-0080: User Location.
XEP-0300 - Use of cryptographic hash functions.
XEP-0300 - Use of cryptographic hash functions.
XEP-0300 - Use of cryptographic hash functions.
Smack's API for XEP-0334: Message Processing Hints.
XMPP extension elements for XEP-0334: Message Processing Hints.
Smack Provider for XEP-0334: Message Processing Hints.
Smack's API for XEP-0332: HTTP over XMPP transport.
Stanzas and extension elements for XEP-0332: HTTP over XMPP transport.
Providers for XEP-0332: HTTP over XMPP transport.
Smack's API for XEP-0363: HTTP File Upload.
IQ stanzas and extensions for XEP-0363: HTTP File Upload.
Providers for XEP-0363: HTTP File Upload.
Smack's API for XMPP IoT (XEP-0323, -0324, -0325, -0347).
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT XEP-0347 Discovery.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smack's API for XMPP IoT.
Smacks implementation of XEP-0012: Last Activity.
Element classes for XEP-0012: Last Activity.
Smacks implementation of XEP-0049: Private XML Storage.
Element classes for XEP-0049: Private XML Storage.
Provider classes for XEP-0049: Private XML Storage.
Smacks implementation of XEP-0077: In-Band Registration.
Element classes for XEP-0077: In-Band Registration.
Provider classes for XEP-0077: In-Band Registration.
Smacks implementation of XEP-0092: Software Version.
Element classes for XEP-0092: Software Version.
Provider classes for XEP-0092: Software Version.
Smack's API for XEP-0328: JID Prep.
XML elements for XEP-0328: JID Prep.
Providers for XEP-0328: JID Prep.
Smack's API for XEP-0166: Jingle.
Smack's API for XEP-0234: Jingle File Transfer.
Smack's API for XEP-0234: Jingle File Transfer.
Smack's API for XEP-0234: Jingle File Transfer.
Stanzas and Extension Elements for XEP-0166: Jingle.
Providers and parsers for XEP-0166: Jingle.
Smack's API for XEP-0261: Jingle In-Band Bytestreams.
Smack's API for XEP-0261: Jingle In-Band Bytestreams.
Smack's API for XEP-0261: Jingle In-Band Bytestreams.
Smack's API for XEP-0261: Jingle In-Band Bytestreams.
Smack's API for XEP-0260: Jingle SOCKS5 Bytestreams.
Smack's API for XEP-0260: Jingle SOCKS5 Bytestreams.
Smack's API for XEP-0260: Jingle SOCKS5 Bytestreams.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
Smacks implementation for attaching arbitrary properties to packets according to
https://docs.jivesoftware.com/smack/latest/documentation/properties.html.
Element classes.
Provider classes.
Extension elements for XEP-0295: JSON Encodings for XMPP.
Providers for XEP-0295: JSON Encodings for XMPP.
Element classes for XEP-0319: Last User Interaction in Presence.
Provider classes for XEP-0319: Last User Interaction in Presence.
XEP-0313: Message Archive Management.
Packet classes and interfaces for Message Archive Management (MAM) XEP-0313.
Filters of Message Archive Management (MAM) XEP-0313.
Provider classes of Message Archive Management (MAM) XEP-0313.
Smacks implementation of XEP-0221: Data Forms Media Element.
Element classes for XEP-0221: Data Forms Media Element.
Provider classes for XEP-0221: Data Forms Media Element.
XMPP stream elements for Last Message Correction as defined in XEP-0308.
XMPP stream element providers for Last Message Correction as defined in XEP-0308.
XEP-0422: Message Fastening.
XEP-0422: Message Fastening.
XEP-0422: Message Fastening.
Smack's API for XEP-0394: Message Markup, which can be used to style message.
XEP-0394: Message Markup.
XEP-0424: Message Retraction.
XEP-0424: Message Retraction.
XEP-0424: Message Retraction.
Smack's API for XEP-0107: User Mood.
Smack's API for XEP-0107: User Mood.
Smack's API for XEP-0107: User Mood.
Smack API for Multi-User Chat (MUC, XEP-0045).
Manager to autojoin bookmarked Multi-User Chat conferences.
Stanza filters for Multi-User Chat.
Element classes for XEP-0045: Multi-User Chat.
Provider classes for XEP-0045: Multi-User Chat.
Classes and Interfaces that implement Multi-User Chat Light (MUC Light).
Multi-User Chat Light (MUC Light) elements.
Multi-User Chat Light (MUC Light) providers.
Element classes for XEP-0172: User Nickname.
Providers for XEP-0172: User Nickname.
Smacks implementation of XEP-0013: Flexible Offline Message Retrieval.
Element classes for XEP-0013: Flexible Offline Message Retrieval.
Classes and interfaces for OMEMO Encryption.
Classes that represent OMEMO related stanzas.
Exceptions.
Classes that are used internally to arrange objects.
StanzaListeners used for internal purposes.
Callbacks and listeners.
Provider classes that parse OMEMO related stanzas into objects.
Concrete implementation of OMEMO for smack using the signal-protocol-java library.
Callbacks used to pass trust decisions up to the client.
Helper classes and other stuff.
Smack API for XEP-0373: OpenPGP for XMPP.
Smack API for XEP-0374: OpenPGP for XMPP: Instant Messaging.
Callback classes for XEP-0373: OpenPGP for XMPP.
Callback classes Secret key backups.
Crypto Providers for XEP-0373: OpenPGP for XMPP using Bouncycastle.
XML elements for XEP-0373: OpenPGP for XMPP.
Exceptions for XEP-0373: OpenPGP for XMPP.
Internal OpenPgpContentElement listeners for XEP-0373: OpenPGP for XMPP.
Providers for XEP-0373: OpenPGP for XMPP.
Abstract OpenPGP store implementations.
OpenPgp store class definitions.
File based store implementations.
Utility classes for XEP-0373: OpenPGP for XMPP.
Smacks implementation XEP-0163: Personal Eventing Protocol.
Smacks implementation of XEP-0199: XMPP Ping.
Android classes for XEP-0199: XMPP Ping.
Element classes for XEP-0199: XMPP Ping.
Provider classes for XEP-0199: XMPP Ping.
Smacks implementation of XEP-0016: Privacy Lists.
Filters for XEP-0016: Privacy Lists.
Element classes for XEP-0016: Privacy Lists.
Provider classes for XEP-0016: Privacy Lists.
Smack's API for XEP-0060: Publish-Subscribe.
Filters for Publish-Subscribe (XEP-60).
Smack's implementation of Data Forms (XEP-0004) for PubSub.
Listeners for Publish-Subscribe (XEP-60) events.
Stanzas and extension elements for Publish-Subscribe (XEP-60).
Providers for Publish-Subscribe (XEP-60).
Utilities for Publish-Subscribe (XEP-60).
Classes and interfaces to manage Push Notifications (XEP-0357).
Push Notifications elements (XEP-0357).
Push Notifications providers (XEP-0357).
XEP-0184: Message Delivery Receipts.
Smack's API for XEP-0372: References.
Smack's API for XEP-0372: References.
Smack's API for XEP-0372: References.
XEP-0059: Result Set Management.
Element classes of XEP-0059: Result Set Management.
Providers for XEP-0059: Result Set Management.
Smacks implementation of XEP-0055: Jabber Search.
Implementation of shared groups.
Element classes of shared groups.
Element classes for XEP-0131: Stanza Headers and Internet Metadata.
Provider classes of XEP-0131: Stanza Headers and Internet Metadata.
Element classes for XEP-0095: Stream Initiation.
Provider classes for XEP-0095: Stream Initiation.
Smack's API for XEP-0359: Stable and Unique Stanza IDs.
Smack's API for XEP-0359: Stable and Unique Stanza IDs.
Smack's API for XEP-0359: Stable and Unique Stanza IDs.
Smacks implementation of XEP-0232: Software Information.
Form class needed for XEP-0232: Software Information.
Smack's API for XEP-0382: Spoiler Messages, that can be used to indicate that
the body of a message is a spoiler and should be displayed as such.
Smack's API for XEP-0382: Spoiler Messages.
Smack's API for XEP-0382: Spoiler Messages.
Smack's API for XEP-0420: Stanza Content Encryption: Element classes.
Smack's API for XEP-0420: Stanza Content Encryption: Provider classes.
Smacks implementation of XEP-0264: Jingle Content Thumbnails.
Smacks implementation of XEP-0264: Jingle Content Thumbnails.
Smacks implementation of XEP-0202: Entity Time.
Element classes of XEP-0202: Entity Time.
Provider classes of XEP-0202: Entity Time.
Element classes for XEP-0103: URL Address Information.
Element classes for XEP-0104.
Provider classes for XEP-0103: URL Address Information.
Smack's API for XEP-0118: User Tune.
Smack's API for XEP-0118: User Tune.
Smack's API for XEP-0118: User Tune.
Smacks implementation of XEP-0054: vcard-temp.
Element classes for XEP-0054: vcard-temp.
Provider classes for XEP-0054: vcard-temp.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
TODO describe me.
Smacks API for Data Forms (XEP-0004).
Smacks high-level API for XEP-0004: Data Forms.
Element classes for XEP-0004: Data Forms.
Provider classes for XEP-0004: Data Forms.
Smacks implementation of XEP-0141: Data Forms Layout.
Element classes for XEP-0141: Data Forms Layout.
Provider classes for XEP-0141: Data Forms Layout.
Smacks implementation of XEP-0122: Data Forms Validation.
Element classes for XEP-0122: Data Forms Validation.
Provider classes for XEP-0122: Data Forms Validation.
TODO describe me.
TODO describe me.
TODO describe me.
Smacks implementation of XHTML-IM (XEP-0071), which provides the ability to send and receive formatted messages using
XHTML.
Element classes for XEP-0071: XHTML-IM.
Provider classes for XEP-0071: XHTML-IM.
Smacks implementation of XEP-0315: Data Forms XML Element.
Element classes for XEP-0315: Data Forms XML Element.
Provider classes for XEP-0315: Data Forms XML Element.
This extension is used to send rosters, roster groups and roster entries from one XMPP Entity to another.
TODO describe me.
TODO describe me.