122 lines
6.4 KiB
HTML
122 lines
6.4 KiB
HTML
<body>
|
|
|
|
<h1>Overview</h1>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>Key Advantages</h2>
|
|
|
|
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.
|
|
|
|
<pre>{@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();
|
|
}</pre>
|
|
|
|
<p>Smack doesn't force you to code at the protcol level of XMPP. The library provides intelligent higher level constructs, often called {@link org.jivesoftware.smack.Manager}, which let you program more efficiently. Other examples of those constructs are the Chat and Roster classes.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<h2>License</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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
|
|
{@link org.jivesoftware.smack.Smack#getNoticeStream}.</p>
|
|
|
|
<h2>About XMPP</h2>
|
|
|
|
<p>XMPP (eXtensible Messaging and Presence Protocol) is an open protocol standardized by the <a href="https://ietf.org/">Internet Engineering Task Force (IETF)</a> and supported and extended by the <a href="https://www.xmpp.org/">XMPP Standards Foundation (XSF)</a>.</p>
|
|
|
|
<h2>Smack Modules</h2>
|
|
|
|
<p>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.</p>
|
|
|
|
<ul>
|
|
<li>smack-core -- provides core XMPP functionality. All XMPP features that are part of the XMPP RFCs are included.</li>
|
|
<li>smack-im -- provides functionality defined in RFC 6121 (XMPP-IM), like the Roster.</li>
|
|
<li>{@link org.jivesoftware.smack.tcp smack-tcp} -- support for XMPP over TCP. Includes XMPPTCPConnection class, which you usually want to use</li>
|
|
<li>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).</li>
|
|
<li>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.</li>
|
|
<li>smack-legacy -- support for legacy extensions (XEPs) defined by the XMPP Standards Foundation.
|
|
<li>smack-bosh -- support for BOSH (XEP-0124). This code should be considered as beta.</li>
|
|
<li>smack-resolver-minidns -- support for resolving DNS SRV records with the help of <a href="https://minidns.org">MiniDNS</a>. Ideal for platforms that do not support the javax.naming API. Also supports [DNSSEC](dnssec.md) TODO: Fix link.</li>
|
|
<li>smack-resolver-dnsjava -- support for resolving DNS SRV records with the help of dnsjava.</li>
|
|
<li>smack-resolver-javax -- support for resolving DNS SRV records with the javax namespace API.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
|
|
<h2>Main API Entry Points</h2>
|
|
|
|
<ul>
|
|
<li>{@link org.jivesoftware.smack.XMPPConnection}</li>
|
|
<li>{@link org.jivesoftware.smack.tcp.XMPPTCPConnection}</li>
|
|
<li>{@link org.jivesoftware.smack.roster.Roster}</li>
|
|
<!-- <li>{@link org.jivesoftware.smack.chat2.Chat}</li> -->
|
|
<!-- More form index.md -->
|
|
</ul>
|
|
|
|
<h2>Smack Extensions</h2>
|
|
|
|
<p>
|
|
Since the X in XMPP stands for eXstensible, Smack comes with many
|
|
built-in extensions for XMPP. Click
|
|
</p>
|
|
<blockquote><b>{@link org.jivesoftware.smackx}</b></blockquote>
|
|
<p>
|
|
for an overview of all supporteted XMPP extensions of Smack.
|
|
</p>
|
|
|
|
Some selected extensions are
|
|
<ul>
|
|
<li>{@link org.jivesoftware.smackx.muc.MultiUserChat Multi-User Chat (XEP-0045)}</li>
|
|
<li>{@link org.jivesoftware.smackx.carbons.CarbonManager Message Carbons (XEP-0289)}</li>
|
|
<li>{@link org.jivesoftware.smackx.omemo OMEMO (XEP-0384)}</li>
|
|
<!-- <li>{@link org.jivesoftware.smack.chat2.Chat}</li> -->
|
|
<!-- More form index.md -->
|
|
</ul>
|
|
|
|
<h2>Configuration</h2>
|
|
|
|
<p>Smack has an initialization process that involves 2 phases.</p>
|
|
|
|
<ul>
|
|
<li>Initializing system properties - Initializing all the system properties accessible through the class **SmackConfiguration**. These properties are retrieved by the _getXXX_ methods on that class.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
</body>
|