vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-12-25 12:08:00 +01:00
Code Issues Releases Wiki Activity
Smack/resources/javadoc-overview.html

122 lines
6.4 KiB
HTML
Raw Permalink Normal View History

Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
<body>
<h1>Overview</h1>
Migrate markdown documentation to javadoc While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
2023-02-03 09:36:54 +01:00
<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>
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
<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>
Migrate markdown documentation to javadoc While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
2023-02-03 09:36:54 +01:00
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.
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
Migrate markdown documentation to javadoc While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
2023-02-03 09:36:54 +01:00
<pre>{@code
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
AbstractXMPPConnection connection = new XMPPTCPConnection("mtucker", "password", "jabber.org");
connection.connect().login();
[javadoc-overview] Use stanza factory in example code
2021-03-25 12:16:04 +01:00
Message message = connection.getStanzaFactory()
.buildMessageStanza()
.to("jsmith@igniterealtime.org")
.setBody("Howdy! How are you?")
.build();
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
connection.sendStanza(message);
[javadoc-overview] Disconnect the connection in example code
2021-03-25 12:23:39 +01:00
connection.disconnect();
Migrate markdown documentation to javadoc While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
2023-02-03 09:36:54 +01:00
}</pre>
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
Link to Manager from javadoc-overview.html
2018-08-02 17:14:33 +02:00
<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>
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
<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>
[javadoc-overview] Improve 'License' section
2021-03-25 12:23:19 +01:00
<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>
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
<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>
Migrate markdown documentation to javadoc While markdown is easier to write, Smack's markdown documentation was never tightly coupled with the source. For example, the markdown documentation never provided links to the actual Java classes and methods. This poses the risk that the documentation and the code diverge over time. Furthermore, javadoc is constantly improving (for example @snippet annotations) and I expect that one will be able to write javadoc in markdown. Fixes SMACK-928.
2023-02-03 09:36:54 +01:00
<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>
Add javadoc-overview.html
2018-08-02 17:02:08 +02:00
</body>
Reference in a new issue Copy permalink