mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-11-22 03:52:06 +01:00
Initial check-in.
git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@1786 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Matt Tucker
mtucker
parent
59a0402000
commit
719f53dfb5
8 changed files with 415 additions and 0 deletions
64
documentation/debugging.html
Normal file
64
documentation/debugging.html
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>Smack: Debugging - Jive Software</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css" />
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
Debugging with Smack
|
||||
</div>
|
||||
|
||||
<div class="nav">
|
||||
« <a href="index.html">Table of Contents</a>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Smack includes a built-in debugging console that will let you track all XML traffic between
|
||||
the client and server.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
When debugging mode is enabled, a debug window will appear when each new connection is created.
|
||||
The window will contain the following information:
|
||||
</p>
|
||||
|
||||
<img src="images/debugwindow.gif" width="359" height="399" alt="" border="0" align="right">
|
||||
|
||||
<ul>
|
||||
<li>Client Traffic (red text) -- raw XML traffic generated by Smack and sent to the server.
|
||||
<li>Server Traffic (blue text) -- raw XML traffic sent by the server to the client.
|
||||
<li>Interpreted Packets (green text) -- shows XML packets from the server as parsed by Smack.
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Debugging mode can be enabled in two different ways:
|
||||
</p>
|
||||
|
||||
<ol>
|
||||
<li>Add the following line of code before creating new connections:<p>
|
||||
<tt>XMPPConection.DEBUG_ENABLED = true;</tt><p>
|
||||
|
||||
<li>Set the Java system property <tt>smack.debugEnabled</tt> to true. The
|
||||
system property can be set on the command line such as:<p>
|
||||
<tt>java SomeApp -Dsmack.debugEnabled=true</tt>.
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
If you wish to explicity disable debug mode in your application, including using the command-line parameter,
|
||||
add the following line to your application before opening new connections:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<tt>XMPPConnection.DEBUG_ENABLED = false;</tt>
|
||||
</p>
|
||||
|
||||
<br clear="all" /><br><br>
|
||||
|
||||
<div class="footer">
|
||||
Copyright © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
96
documentation/gettingstarted.html
Normal file
96
documentation/gettingstarted.html
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>Smack: Getting Started - Jive Software</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css" /
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
Getting Started With Smack
|
||||
</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">
|
||||
Requirements
|
||||
</p>
|
||||
|
||||
The only requirement for Smack is JDK 1.2 or later. An XML parser is embedded in the smack.jar
|
||||
file and no other third party libraries are required.
|
||||
|
||||
<p class="subheader">
|
||||
Establishing a Connection
|
||||
</p>
|
||||
|
||||
The <tt>XMPPConnection</tt> class is used to create a connection to an
|
||||
XMPP server. To create an SSL connection, use the SSLXMPPConnection class.
|
||||
Below are code examples for making a connection:<p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
<font color="gray"><i>// Create a connection to the jabber.org server.</i></font>
|
||||
XMPPConnection conn1 = <font color="navy"><b>new</b></font> XMPPConnection(<font color="green">"jabber.org"</font>);
|
||||
|
||||
<font color="gray"><i>// Create a connection to the jabber.org server on a specific port.</i></font>
|
||||
XMPPConnection conn2 = <font color="navy"><b>new</b></font> XMPPConnection(<font color="green">"jabber.org"</font>, 5222);
|
||||
|
||||
<font color="gray"><i>// Create an SSL connection to jabber.org.</i></font>
|
||||
XMPPConnection connection = <font color="navy"><b>new</b></font> SSLXMPPConnection(<font color="green">"jabber.org"</font>);
|
||||
</pre></div>
|
||||
|
||||
<p>Once you've created a connection, you should login using a username and password
|
||||
with the <tt>XMPPConnection.login(String username, String password)</tt> method.
|
||||
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>
|
||||
|
||||
CONTENT COMING SOON
|
||||
|
||||
<p class="subheader">
|
||||
Packets, the PacketReader, and the PacketWriter
|
||||
</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
|
||||
classes that encapsulate the different packet types allowed by XMPP (message,
|
||||
presence, and IQ). Classes such as <tt>Chat</tt> and <tt>GroupChat</tt>
|
||||
provide higher-level constructs that manage creating and sending packets
|
||||
automatically, but you can also create and send packets directly. Below
|
||||
is a code example for changing the presence to let people we're unavailable
|
||||
because we're out fishing:<p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
<font color="gray"><i>// Create a new presence. Pass in false to indicate we're unavailable.</i></font>
|
||||
Presence presence = new Presence(false);
|
||||
presence.setStatus(<font color="green">"Gone fishing"</font>);
|
||||
<font color="gray"><i>// Send the packet (assume we have a XMPPConnection instance called "con").</i></font>
|
||||
con.getPacketWriter().sendPacket(presence);
|
||||
</pre></div>
|
||||
<p>
|
||||
|
||||
Every connection has a <tt>PacketReader</tt> and <tt>PacketWriter</tt>. The
|
||||
packet reader listens for XML data from the server and parses it into
|
||||
individual packets. You can listen for incoming packets by registering
|
||||
<tt>PacketWatcher</tt> objects with the packet reader. The packet writer
|
||||
is responsible for writing packets to the server. It takes <tt>Packet</tt>
|
||||
objects and converts them to XML before sending them over the network.
|
||||
|
||||
|
||||
<p><div class="footer">
|
||||
Copyright © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
BIN
documentation/images/debugwindow.gif
Normal file
BIN
documentation/images/debugwindow.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
30
documentation/index.html
Normal file
30
documentation/index.html
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>Smack Documentation - Jive Software</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css" />
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
Smack Documentation
|
||||
</div>
|
||||
|
||||
|
||||
<p>
|
||||
Documentation Contents:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><a href="overview.html">Overview</a>
|
||||
<li><a href="gettingstarted.html">Getting Started Guide</a>
|
||||
<li><a href="properties.html">Packet Properties</a>
|
||||
<li><a href="debugging.html">Debugging with Smack</a>
|
||||
</ul>
|
||||
|
||||
<div class="footer">
|
||||
Copyright © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
55
documentation/overview.html
Normal file
55
documentation/overview.html
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>Smack: Overview - Jive Software</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css" />
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
Smack Overview
|
||||
</div>
|
||||
|
||||
<div class="nav">
|
||||
« <a href="index.html">Table of Contents</a>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
|
||||
Smack is a library for communicating with XMPP (Jabber) servers to perform
|
||||
instant messaging and chat.
|
||||
|
||||
<p class="subheader">
|
||||
Key Advantages:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>Extremely simple to use, yet powerful API. Sending a text message to a user
|
||||
can be accomplished in three lines of code:
|
||||
|
||||
<div class="code"><pre>
|
||||
XMPPConnection connection = <font color="navy"><b>new</b></font> XMPPConnection(<font color="green">"jabber.org"</font>);
|
||||
connection.login(<font color="green">"mtucker"</font>, <font color="green">"password"</font>);
|
||||
connection.createChat(<font color="green">"jsmith@jivesoftware.com"</font>).sendMessage(<font color="green">"Howdy!"</font>);
|
||||
</pre></div>
|
||||
|
||||
|
||||
<li>Doesn't force you to code at the packet level, as other libraries do. Smack provides
|
||||
intelligent higher level constructs such as the <tt>Chat</tt> and <tt>GroupChat</tt>
|
||||
classes, which let you program more efficiently.
|
||||
|
||||
<li>Does not require that you're familiar with the XMPP XML format, or even that you're familiar with XML.
|
||||
|
||||
<li>Provides easy machine to machine communication. Smack lets you set any number of properties on
|
||||
each message, including properties that are Java objects.
|
||||
|
||||
<li>Open Source under the Apache License, which means you can incorporate Smack into your commercial or
|
||||
non-commercial applications.
|
||||
</ul>
|
||||
|
||||
<div class="footer">
|
||||
Copyright © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
0
documentation/processing.html
Normal file
0
documentation/processing.html
Normal file
114
documentation/properties.html
Normal file
114
documentation/properties.html
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>Smack: Packet Properties - Jive Software</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css" /
|
||||
</head>
|
||||
|
||||
<body>
|
||||
|
||||
<div class="header">
|
||||
Packet Properties
|
||||
</div>
|
||||
|
||||
<div class="nav">
|
||||
« <a href="index.html">Table of Contents</a>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
Smack provides an easy mechanism for attaching arbitrary properties to packets. Each property
|
||||
has a String name, and a value that is a Java primitive (int, long, float, double, boolean) or
|
||||
any Serializable object (a Java object is Serializable when it implements the Serializable
|
||||
interface).
|
||||
</p>
|
||||
|
||||
<p class="subheader">
|
||||
Using the API
|
||||
</p>
|
||||
|
||||
<p>
|
||||
All major objects have property support, such as Message objects. The following code
|
||||
demonstrates how to set properties:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
Message message = chat.createMessage();
|
||||
<font color="gray"></i>// Add a Color object as a property.</i></font>
|
||||
message.setProperty(<font color="blue">"favoriteColor"</font>, new Color(0, 0, 255));
|
||||
<font color="gray"></i>// Add an int as a property.</i></font>
|
||||
message.setProperty(<font color="blue">"favoriteNumber"</font>, 4);
|
||||
chat.sendMessage(message);
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Getting those same properties would use the following code:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
Message message = chat.nextMessage();
|
||||
<font color="gray"></i>// Get a Color object property.</i></font>
|
||||
Color favoriteColor = (Color)message.getProperty(<font color="blue">"favoriteColor"</font>);
|
||||
<font color="gray"></i>// Get an int property. Note that properties are always returned as
|
||||
// Objects, so we must cast the value to an Integer, then convert
|
||||
// it to an int.</i></font>
|
||||
int favoriteNumber = ((Integer)message.getProperty(<font color="blue">"favoriteNumber"</font>)).intValue();
|
||||
</pre></div>
|
||||
|
||||
<p class="subheader">
|
||||
Objects as Properties
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Using objects as property values is a very powerful and easy way to exchange data. However,
|
||||
you should keep the following in mind:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li>When you send a Java object, only clients running Java will be able to interpret the data.
|
||||
So, consider using a series of primitive values to transfer data instead.
|
||||
|
||||
<li>Objects sent as property values must implement Serialiable. Additionally, both the sender
|
||||
and receiver must have identical versions of the class, or a serialization exception
|
||||
will occur when de-serialiazing the object.
|
||||
|
||||
<li>Serialized objects can potentially be quite large, which will use more bandwidth and
|
||||
server resources.
|
||||
</ul>
|
||||
|
||||
<p class="subheader">
|
||||
XML Format
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The current XML format used to send property data is not a standard, so will likely not be
|
||||
recognized by clients not using Smack. The XML looks like the following (comments added for
|
||||
clarity):
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<font color="gray"><i><!-- All properties are in a x block. --></i></font>
|
||||
<x xmlns="http://www.jivesoftware.com/xmlns/xmpp/properties">
|
||||
<font color="gray"><i><!-- First, a property named "prop1" that's an integer. --></i></font>
|
||||
<property>
|
||||
<name>prop1</name>
|
||||
<value type="integer">123</value>
|
||||
<property>
|
||||
<font color="gray"><i><!-- Next, a Java object that's been serialized and then converted
|
||||
from binary data to base-64 encoded text. --></i></font>
|
||||
<property>
|
||||
<name>blah2</name>
|
||||
<value type="java-object">adf612fna9nab</value>
|
||||
<property>
|
||||
</x>
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
The currently supported types are: <tt>integer</tt>, <tt>long</tt>, <tt>float</tt>,
|
||||
<tt>double</tt>, <tt>boolean</tt>, <tt>string</tt>, and <tt>java-object</tt>.
|
||||
</p>
|
||||
|
||||
<div class="footer">
|
||||
Copyright © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
56
documentation/style.css
Normal file
56
documentation/style.css
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
BODY {
|
||||
font-size : 100%;
|
||||
background-color : #fff;
|
||||
}
|
||||
BODY, TD, TH {
|
||||
font-family : tahoma, arial, helvetica;
|
||||
font-size : 0.8em;
|
||||
}
|
||||
PRE, TT, CODE {
|
||||
font-family : courier new, monospaced;
|
||||
font-size : 1.0em;
|
||||
}
|
||||
A:hover {
|
||||
text-decoration : none;
|
||||
}
|
||||
LI {
|
||||
padding-bottom : 4px;
|
||||
}
|
||||
.header {
|
||||
font-size : 1.4em;
|
||||
font-weight : bold;
|
||||
width : 100%;
|
||||
border-bottom : 1px #ccc solid;
|
||||
padding-bottom : 2px;
|
||||
}
|
||||
.subheader {
|
||||
font-weight : bold;
|
||||
}
|
||||
.footer {
|
||||
font-size : 0.8em;
|
||||
color : #999;
|
||||
text-align : center;
|
||||
width : 100%;
|
||||
border-top : 1px #ccc solid;
|
||||
padding-top : 2px;
|
||||
}
|
||||
.code {
|
||||
border : 1px #ccc solid;
|
||||
padding : 0em 1.0em 0em 1.0em;
|
||||
margin : 4px 0px 4px 0px;
|
||||
}
|
||||
.nav, .nav A {
|
||||
font-family : verdana;
|
||||
font-size : 0.85em;
|
||||
color : #600;
|
||||
text-decoration : none;
|
||||
font-weight : bold;
|
||||
}
|
||||
.nav {
|
||||
width : 100%;
|
||||
border-bottom : 1px #ccc solid;
|
||||
padding : 3px 3px 5px 1px;
|
||||
}
|
||||
.nav A:hover {
|
||||
text-decoration : underline;
|
||||
}
|
||||
Loading…
Reference in a new issue