documentation/gettingstarted.html

   1 <html>
   2 <head>
   3         <title>Smack: Getting Started - Jive Software</title>
   4         <link rel="stylesheet" type="text/css" href="style.css" />
   5 </head>
   6
   7 <body>
   8
   9 <div class="header">
  10 Smack: Getting Started
  11 </div>
  12
  13 <div class="nav">
  14 &laquo; <a href="index.html">Table of Contents</a>
  15 </div>
  16
  17 <p>
  18 This document will introduce you to the Smack API and provide an overview of
  19 important classes and concepts.
  20 </p>
  21
  22 <p class="subheader">
  23 JAR Files and Requirements
  24 </p>
  25
  26 Smack is meant to be easily embedded into any existing JDK 1.5 or later Java application.
  27 It has no external dependencies (except for the Jingle voice chat functionality) and is optimized
  28 to be as small as possible. The library ships as several JAR files to provide more flexibility
  29 over which features applications require:
  30
  31 <ul>
  32     <li><tt>smack.jar</tt> -- provides core XMPP functionality and is the only <b>required</b>
  33     library. All XMPP features that are part of the XMPP RFCs are included.</li>
  34     <li><tt>smackx.jar</tt> -- support for many of the the extensions (XEPs) defined
  35     by the XMPP Standards Foundation, including multi-user chat, file transfer, user search, etc.
  36     The extensions are documented in the <a href="extensions/index.html">extensions manual</a>.</li>
  37     <li><tt>smackx-debug.jar</tt> -- an enhanced GUI debugger for protocol traffic. It will
  38     automatically be used when found in the classpath and when <a href="debugging.html">debugging</a>
  39     is enabled.</li>
  40 </ul>
  41
  42
  43 <p class="subheader">
  44 Establishing a Connection
  45 </p>
  46
  47 The <tt>XMPPConnection</tt> class is used to create a connection to an
  48 XMPP server. Below are code examples for making a connection:<p>
  49
  50 <div class="code">
  51 <pre>
  52 <font color="gray"><i>// Create a connection to the jabber.org server.</i></font>
  53 XMPPConnection conn1 = <font color="navy"><b>new</b></font> XMPPConnection(<font color="green">"jabber.org"</font>);
  54 conn1.connect();
  55
  56 <font color="gray"><i>// Create a connection to the jabber.org server on a specific port.</i></font>
  57 ConnectionConfiguration config = new ConnectionConfiguration(<font color="green">"jabber.org"</font>, 5222);
  58 XMPPConnection conn2 = <font color="navy"><b>new</b></font> XMPPConnection(config);
  59 conn2.connect();
  60 </pre></div>
  61
  62 <p>Note that maximum security will be used when connecting to the server by default (and when possible),
  63     including use of TLS encryption. The ConnectionConfiguration class provides advanced control
  64     over the connection created, such as the ability to disable or require encryption. See
  65     <a href="connections.html">Connection Management</a> for full details.</p>
  66
  67 <p>Once you've created a connection, you should login using a username and password
  68 with the <tt>XMPPConnection.login(String username, String password)</tt> method.
  69 Once you've logged in, you can being chatting with other users by creating
  70 new <tt>Chat</tt> or <tt>GroupChat</tt> objects.
  71
  72 <p class="subheader">
  73 Working with the Roster
  74 </p>
  75 The roster lets you keep track of the availability (presence) of other users. Users
  76 can be organized into groups such as "Friends" and "Co-workers", and then you
  77 discover whether each user is online or offline.<p>
  78
  79 Retrieve the roster using the <tt>XMPPConnection.getRoster()</tt> method. The roster
  80 class allows you to find all the roster entries, the groups they belong to, and the
  81 current presence status of each entry.
  82
  83 <p class="subheader">
  84 Reading and Writing Packets
  85 </p>
  86
  87 Each message to the XMPP server from a client is called a packet and is
  88 sent as XML. The <tt>org.jivesoftware.smack.packet</tt> package contains
  89 classes that encapsulate the three different basic packet types allowed by
  90 XMPP (message, presence, and IQ). Classes such as <tt>Chat</tt> and <tt>GroupChat</tt>
  91 provide higher-level constructs that manage creating and sending packets
  92 automatically, but you can also create and send packets directly. Below
  93 is a code example for changing your presence to let people know you're unavailable
  94 and "out fishing":<p>
  95
  96 <div class="code">
  97 <pre>
  98 <font color="gray"><i>// Create a new presence. Pass in false to indicate we're unavailable.</i></font>
  99 Presence presence = new Presence(Presence.Type.UNAVAILABLE);
 100 presence.setStatus(<font color="green">"Gone fishing"</font>);
 101 <font color="gray"><i>// Send the packet (assume we have a XMPPConnection instance called "con").</i></font>
 102 con.sendPacket(presence);
 103 </pre></div>
 104 <p>
 105
 106 Smack provides two ways to read incoming packets: <tt>PacketListener</tt>, and
 107 <tt>PacketCollector</tt>. Both use <tt>PacketFilter</tt> instances to determine
 108 which packets should be processed. A packet listener is used for event style programming,
 109 while a packet collector has a result queue of packets that you can do
 110 polling and blocking operations on. So, a packet listener is useful when
 111 you want to take some action whenever a packet happens to come in, while a
 112 packet collector is useful when you want to wait for a specific packet
 113 to arrive. Packet collectors and listeners can be created using an
 114 XMPPConnection instance.
 115
 116
 117 <p><div class="footer">
 118 Copyright &copy; Jive Software 2002-2005
 119 </div>
 120
 121 </body>
 122 </html>