Smack/documentation/overview.md

Smack Overview
==============

[Back](index.md)

Smack is a library for communicating with XMPP servers to perform real-time
communications, including instant messaging and group chat.

Smack Key Advantages
--------------------

  * Extremely simple to use, yet powerful API. Sending a text message to a user can be accomplished in only a few lines of code: 

    ```java
    AbstractXMPPConnection connection = new XMPPTCPConnection("mtucker", "password", "jabber.org");
    connection.connect().login();

    Message message = connection.getStanzaFactory()
                      .buildMessageStanza()
                      .to("jsmith@jivesoftware.com")
                      .setBody("Howdy! How are you?")
                      .build();
    connection.sendStanza(message);
    ```

* Doesn't force you to code at the XMPP protocol level, as other libraries do. Smack provides intelligent higher level constructs such as the `Chat` and `Roster` classes, which let you program more efficiently. 
  * Does not require that you're familiar with the XMPP XML format, or even that you're familiar with XML. 
  * Provides easy machine to machine communication. Smack lets you set any number of properties on each message, including properties that are Java objects. 
  * Open Source under the Apache License 2.0, which means you can incorporate Smack into your commercial or non-commercial applications. 

About XMPP
----------

XMPP (eXtensible Messaging and Presence Protocol) is an open protocol
standardized by the IETF and supported and extended by the XMPP Standards
Foundation (XSF, [http://www.xmpp.org](http://www.xmpp.org)).

How To Use This Documentation
-----------------------------

This documentation assumes that you're already familiar with the main features
of XMPP instant messaging. It's also highly recommended that you open the
Javadoc API guide and use that as a reference while reading through this
documentation.

Copyright (C) Jive Software 2002-2008
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00			`Smack Overview`
Don't repeat documentation, link to it instead also fix some typos and improve some markdown formatting. 2014-08-28 15:18:39 +02:00			`==============`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
Update markdown-gradle-plugin to 1.0.0 and rename documentation links from .html to .md, since markdown-gradle-plugin will now automatically transfer the links .md to .html. Now users can broswe the documentation in their markdown form (e.g. via github) and via html. Also add a symlink from README.md to index.md in documentation/. 2015-03-07 21:05:31 +01:00			`[Back](index.md)`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
			`Smack is a library for communicating with XMPP servers to perform real-time`
			`communications, including instant messaging and group chat.`

			`Smack Key Advantages`
Don't repeat documentation, link to it instead also fix some typos and improve some markdown formatting. 2014-08-28 15:18:39 +02:00			`--------------------`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
			`* Extremely simple to use, yet powerful API. Sending a text message to a user can be accomplished in only a few lines of code:`

Don't repeat documentation, link to it instead also fix some typos and improve some markdown formatting. 2014-08-28 15:18:39 +02:00			```java
Apply builder pattern to ConnectionConfiguration Introducing a clean split between the constant connection configuration parameters, which are now all in ConnectionConfiguration and the dynamic connection state (e.g. hostAddresses) which are now in AbstractXMPPConnection. Also removed all arguments of login() since the username, password, resource and callback handler need now to be configured via ConnectionConfiguration. Also remove documentation/extensions/messageevents.md, as it's already in documentation/legacy 2014-11-09 18:30:16 +01:00			`AbstractXMPPConnection connection = new XMPPTCPConnection("mtucker", "password", "jabber.org");`
Make connect() return a self-reference 2015-01-25 19:48:52 +01:00			`connection.connect().login();`

Introduce StanzaBuilder As first step to immutable Stanza types. 2019-10-24 15:45:08 +02:00			`Message message = connection.getStanzaFactory()`
			`.buildMessageStanza()`
			`.to("jsmith@jivesoftware.com")`
			`.setBody("Howdy! How are you?")`
			`.build();`
Update README and documentation 2017-01-03 08:55:14 +01:00			`connection.sendStanza(message);`
Don't repeat documentation, link to it instead also fix some typos and improve some markdown formatting. 2014-08-28 15:18:39 +02:00			```
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
Update README and documentation 2017-01-03 08:55:14 +01:00			* Doesn't force you to code at the XMPP protocol level, as other libraries do. Smack provides intelligent higher level constructs such as the `Chat` and `Roster` classes, which let you program more efficiently.
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00			`* Does not require that you're familiar with the XMPP XML format, or even that you're familiar with XML.`
			`* Provides easy machine to machine communication. Smack lets you set any number of properties on each message, including properties that are Java objects.`
Update README and documentation 2017-01-03 08:55:14 +01:00			`* Open Source under the Apache License 2.0, which means you can incorporate Smack into your commercial or non-commercial applications.`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
			`About XMPP`
Don't repeat documentation, link to it instead also fix some typos and improve some markdown formatting. 2014-08-28 15:18:39 +02:00			`----------`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
			`XMPP (eXtensible Messaging and Presence Protocol) is an open protocol`
			`standardized by the IETF and supported and extended by the XMPP Standards`
Update documentation and README.md 2015-03-13 16:27:50 +01:00			`Foundation (XSF, [http://www.xmpp.org](http://www.xmpp.org)).`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
			`How To Use This Documentation`
Don't repeat documentation, link to it instead also fix some typos and improve some markdown formatting. 2014-08-28 15:18:39 +02:00			`-----------------------------`
Convert html documentation to markdown 2014-08-16 00:09:55 +02:00
			`This documentation assumes that you're already familiar with the main features`
			`of XMPP instant messaging. It's also highly recommended that you open the`
			`Javadoc API guide and use that as a reference while reading through this`
			`documentation.`

			`Copyright (C) Jive Software 2002-2008`