1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-12-24 03:27:59 +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 2003-01-15 15:03:36 +00:00 committed by mtucker
parent 59a0402000
commit 719f53dfb5
8 changed files with 415 additions and 0 deletions

View 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">
&laquo; <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 &copy; Jive Software 2002-2003
</div>
</body>
</html>

View 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">
&laquo; <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 &copy; Jive Software 2002-2003
</div>
</body>
</html>

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

30
documentation/index.html Normal file
View 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 &copy; Jive Software 2002-2003
</div>
</body>
</html>

View 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">
&laquo; <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 &copy; Jive Software 2002-2003
</div>
</body>
</html>

View file

View 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">
&laquo; <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>&lt;!-- All properties are in a x block. --&gt;</i></font>
&lt;x xmlns="http://www.jivesoftware.com/xmlns/xmpp/properties"&gt;
<font color="gray"><i>&lt;!-- First, a property named "prop1" that's an integer. --&gt;</i></font>
&lt;property&gt;
&lt;name&gt;prop1&lt;/name&gt;
&lt;value type="integer"&gt;123&lt;/value&gt;
&lt;property&gt;
<font color="gray"><i>&lt;!-- Next, a Java object that's been serialized and then converted
from binary data to base-64 encoded text. --&gt;</i></font>
&lt;property&gt;
&lt;name&gt;blah2&lt;/name&gt;
&lt;value type="java-object"&gt;adf612fna9nab&lt;/value&gt;
&lt;property&gt;
&lt;/x&gt;
</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 &copy; Jive Software 2002-2003
</div>
</body>
</html>

56
documentation/style.css Normal file
View 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;
}