2003-01-15 16:03:36 +01:00
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<title>Smack: Getting Started - Jive Software</title>
|
2007-03-01 02:51:12 +01:00
|
|
|
<link rel="stylesheet" type="text/css" href="style.css" />
|
2003-01-15 16:03:36 +01:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<div class="header">
|
2007-03-01 02:51:12 +01:00
|
|
|
Smack: Getting Started
|
2003-01-15 16:03:36 +01:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="nav">
|
|
|
|
|
« <a href="index.html">Table of Contents</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
This document will introduce you to the Smack API and provide an overview of
|
|
|
|
|
important classes and concepts.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p class="subheader">
|
2007-03-01 02:51:12 +01:00
|
|
|
JAR Files and Requirements
|
2003-01-15 16:03:36 +01:00
|
|
|
</p>
|
|
|
|
|
|
2007-03-01 02:51:12 +01:00
|
|
|
Smack is meant to be easily embedded into any existing JDK 1.5 or later Java application.
|
|
|
|
|
It has no external dependencies (except for the Jingle voice chat functionality) and is optimized
|
|
|
|
|
to be as small as possible. The library ships as several JAR files to provide more flexibility
|
|
|
|
|
over which features applications require:
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li><tt>smack.jar</tt> -- provides core XMPP functionality and is the only <b>required</b>
|
|
|
|
|
library. All XMPP features that are part of the XMPP RFCs are included.</li>
|
|
|
|
|
<li><tt>smackx.jar</tt> -- support for many of the the extensions (XEPs) defined
|
|
|
|
|
by the XMPP Standards Foundation, including multi-user chat, file transfer, user search, etc.
|
|
|
|
|
The extensions are documented in the <a href="extensions/index.html">extensions manual</a>.</li>
|
|
|
|
|
<li><tt>smackx-debug.jar</tt> -- an enhanced GUI debugger for protocol traffic. It will
|
|
|
|
|
automatically be used when found in the classpath and when <a href="debugging.html">debugging</a>
|
|
|
|
|
is enabled.</li>
|
|
|
|
|
</ul>
|
2003-01-27 16:54:32 +01:00
|
|
|
|
2003-01-15 16:03:36 +01:00
|
|
|
|
2014-01-16 06:14:39 +01:00
|
|
|
<p class="subheader">Configuration</p>
|
|
|
|
|
Smack has an initialization process that involves 2 phases.
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Initializing system properties - Initializing all the system properties accessible through the class
|
|
|
|
|
<b>SmackConfiguration</b>. These properties are retrieve by the <i>getXXX</i> methods on that class.
|
|
|
|
|
<li>Initializing startup classes - Initializing any classes meant to be active at startup by instantiating
|
|
|
|
|
the class, and then calling the <i>initialize</i> method on that class if it extends <b>SmackInitializer</b>.
|
|
|
|
|
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.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
Initialization is accomplished via a configuration file. By default, Smack will load the one embedded in
|
|
|
|
|
the Smack jar at <i>META-INF/smack-config.xml</i>. This particular configuration contains all the default
|
|
|
|
|
property values as well as a list of initializer classes to load. All manager type classes are contained
|
|
|
|
|
in this list of initializers. If your application does not use all the features provided by Smack via the
|
|
|
|
|
aforementioned managers, you may want to 'turn them off' by providing a custom config file that does not
|
|
|
|
|
include that feature.
|
|
|
|
|
<p>
|
|
|
|
|
If you want to change the configuration file used, you have two options:
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Programmatically - Call the <i>setConfigFileUrl</i> method of <b>SmackConfiguration</b> with the location
|
|
|
|
|
of a new config file.
|
|
|
|
|
<pre>SmackConfiguration.setConfigFileUrl("classpath:test/smack-config.xml", null)</pre>
|
|
|
|
|
<li>VM Argument - Set the VM argument <i>smack.config.file</i> to the location of a new config file.
|
|
|
|
|
<pre>-Dsmack.config.file=file:///c:/com/myco/provider/myco_custom_config.xml</pre>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Please note, there is a copy of the <b>smack-config.xml</b> in the <i>samples</i> directory of the deployment
|
|
|
|
|
archive file (zip or tar).
|
|
|
|
|
|
2003-01-15 16:03:36 +01:00
|
|
|
<p class="subheader">
|
|
|
|
|
Establishing a Connection
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
The <tt>XMPPConnection</tt> class is used to create a connection to an
|
2007-02-04 23:53:16 +01:00
|
|
|
XMPP server. Below are code examples for making a connection:<p>
|
2003-01-15 16:03:36 +01:00
|
|
|
|
|
|
|
|
<div class="code">
|
|
|
|
|
<pre>
|
|
|
|
|
<font color="gray"><i>// Create a connection to the jabber.org server.</i></font>
|
2010-02-09 12:55:56 +01:00
|
|
|
Connection conn1 = <font color="navy"><b>new</b></font> XMPPConnection(<font color="green">"jabber.org"</font>);
|
2007-02-04 23:53:16 +01:00
|
|
|
conn1.connect();
|
2003-01-15 16:03:36 +01:00
|
|
|
|
|
|
|
|
<font color="gray"><i>// Create a connection to the jabber.org server on a specific port.</i></font>
|
2007-02-04 23:53:16 +01:00
|
|
|
ConnectionConfiguration config = new ConnectionConfiguration(<font color="green">"jabber.org"</font>, 5222);
|
2010-02-09 12:55:56 +01:00
|
|
|
Connection conn2 = <font color="navy"><b>new</b></font> XMPPConnection(config);
|
2007-02-04 23:53:16 +01:00
|
|
|
conn2.connect();
|
2003-01-15 16:03:36 +01:00
|
|
|
</pre></div>
|
|
|
|
|
|
2007-02-04 23:53:16 +01:00
|
|
|
<p>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
|
2007-03-01 02:51:12 +01:00
|
|
|
over the connection created, such as the ability to disable or require encryption. See
|
|
|
|
|
<a href="connections.html">Connection Management</a> for full details.</p>
|
2007-02-04 23:53:16 +01:00
|
|
|
|
2003-01-15 16:03:36 +01:00
|
|
|
<p>Once you've created a connection, you should login using a username and password
|
2010-02-09 12:55:56 +01:00
|
|
|
with the <tt>Connection.login(String username, String password)</tt> method.
|
2003-01-15 16:03:36 +01:00
|
|
|
Once you've logged in, you can being chatting with other users by creating
|
|
|
|
|
new <tt>Chat</tt> or <tt>GroupChat</tt> objects.
|
|
|
|
|
|
|
|
|
|
<p class="subheader">
|
|
|
|
|
Working with the Roster
|
|
|
|
|
</p>
|
2003-08-19 15:22:31 +02:00
|
|
|
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.<p>
|
2003-01-15 16:03:36 +01:00
|
|
|
|
2010-02-09 12:55:56 +01:00
|
|
|
Retrieve the roster using the <tt>Connection.getRoster()</tt> method. The roster
|
2003-04-25 22:23:45 +02:00
|
|
|
class allows you to find all the roster entries, the groups they belong to, and the
|
2003-08-19 15:22:31 +02:00
|
|
|
current presence status of each entry.
|
2003-01-15 16:03:36 +01:00
|
|
|
|
|
|
|
|
<p class="subheader">
|
2003-01-27 16:54:32 +01:00
|
|
|
Reading and Writing Packets
|
2003-01-15 16:03:36 +01:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
Each message to the XMPP server from a client is called a packet and is
|
|
|
|
|
sent as XML. The <tt>org.jivesoftware.smack.packet</tt> package contains
|
2003-08-19 15:22:31 +02:00
|
|
|
classes that encapsulate the three different basic packet types allowed by
|
|
|
|
|
XMPP (message, presence, and IQ). Classes such as <tt>Chat</tt> and <tt>GroupChat</tt>
|
2003-01-15 16:03:36 +01:00
|
|
|
provide higher-level constructs that manage creating and sending packets
|
|
|
|
|
automatically, but you can also create and send packets directly. Below
|
2003-08-19 15:22:31 +02:00
|
|
|
is a code example for changing your presence to let people know you're unavailable
|
|
|
|
|
and "out fishing":<p>
|
2003-01-15 16:03:36 +01:00
|
|
|
|
|
|
|
|
<div class="code">
|
|
|
|
|
<pre>
|
|
|
|
|
<font color="gray"><i>// Create a new presence. Pass in false to indicate we're unavailable.</i></font>
|
2007-06-01 23:42:38 +02:00
|
|
|
Presence presence = new Presence(Presence.Type.unavailable);
|
2003-01-15 16:03:36 +01:00
|
|
|
presence.setStatus(<font color="green">"Gone fishing"</font>);
|
2010-02-09 12:55:56 +01:00
|
|
|
<font color="gray"><i>// Send the packet (assume we have a Connection instance called "con").</i></font>
|
2003-01-17 19:37:44 +01:00
|
|
|
con.sendPacket(presence);
|
2003-01-15 16:03:36 +01:00
|
|
|
</pre></div>
|
|
|
|
|
<p>
|
|
|
|
|
|
2003-01-17 19:37:44 +01:00
|
|
|
Smack provides two ways to read incoming packets: <tt>PacketListener</tt>, and
|
|
|
|
|
<tt>PacketCollector</tt>. Both use <tt>PacketFilter</tt> instances to determine
|
|
|
|
|
which packets should be processed. A packet listener is used for event style programming,
|
|
|
|
|
while a packet collector has a result queue of packets that you can do
|
|
|
|
|
polling and blocking operations on. So, a packet listener is useful when
|
|
|
|
|
you want to take some action whenever a packet happens to come in, while a
|
|
|
|
|
packet collector is useful when you want to wait for a specific packet
|
2003-08-19 15:22:31 +02:00
|
|
|
to arrive. Packet collectors and listeners can be created using an
|
2010-02-09 12:55:56 +01:00
|
|
|
Connection instance.
|
2003-01-15 16:03:36 +01:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<p><div class="footer">
|
2008-11-03 17:28:57 +01:00
|
|
|
Copyright © Jive Software 2002-2008
|
2003-01-15 16:03:36 +01:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
