1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2024-12-22 20:47:57 +01:00

Documentation updates.

git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@1969 b35dd754-fafc-0310-a699-88a17e54d16e
This commit is contained in:
Matt Tucker 2003-06-19 18:11:37 +00:00 committed by mtucker
parent b9778d77ab
commit 8a94e69045
5 changed files with 220 additions and 5 deletions

View file

@ -18,6 +18,10 @@ Documentation Contents:
<ul>
<li><a href="overview.html">Overview</a>
<li><a href="gettingstarted.html">Getting Started Guide</a>
<li><a href="messaging.html">Messaging using Smack</a>
<li><a href="roster.html">Presence and Roster</a>
<li><a href="processing.html">Processing Incoming Packets</a>
<li><a href="extensions.html">Extending Packets</a>
<li><a href="properties.html">Packet Properties</a>
<li><a href="debugging.html">Debugging with Smack</a>
</ul>

View file

@ -0,0 +1,108 @@
<html>
<head>
<title>Smack: Chat - Jive Software</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div class="header">
Messaging using Chat and GroupChat
</div>
<div class="nav">
&laquo; <a href="index.html">Table of Contents</a>
</div>
<p>
Sending messages back and forth is at the core of instant messaging. Two classes
aid in sending and recieiving messages:
<ul>
<li> <tt>org.jivesoftware.smack.Chat</tt> -- used to send messages between two people.
<li> <tt>org.jivesoftware.smack.GroupChat</tt> -- used to join a chat room to send messages between many people.
</ul>
Both the Chat and GroupChat classes use the <tt>org.jivesoftware.smack.packet.Message</tt> packet
class to send messages. In certain circumstances, you may wish to bypass the higher-level
Chat and GroupChat classes to send and listen for messages directly.
</p>
<p class="subheader">
Chat
</p>
A chat creates a new thread of messgaes (using a thread ID) between two users. The
following code snippet demonstrates how to create a new Chat with a user and then send
them a text message:<p>
<div class="code"><pre>
<font color="gray"><i>// Assume we've created an XMPPConnection name "connection".</i></font>
Chat newChat = connection.createChat(<font color="green">"jsmith@jivesoftware.com"</font>);
newChat.sendMessage(<font color="green">"Howdy!"</font>);
</pre></div><p>
The <tt>Chat.sendMessage(String)</tt> method is a convenience method that creates a Message
object, sets the body using the String parameter, then sends the message. In the case
that you wish to set additional values on a Message before sending it, use the
<tt>Chat.createMessage()</tt> and <tt>Chat.sendMessage(Message)</tt> methods, as in the
following code snippet:<p>
<div class="code"><pre>
<font color="gray"><i>// Assume we've created an XMPPConnection name "connection".</i></font>
Chat newChat = connection.createChat(<font color="green">"jsmith@jivesoftware.com"</font>);
Message newMessage = newChat.createMessage();
newMessage.setBody(<font color="green">"Howdy!"</font>);
message.setProperty(<font color="green">"favoriteColor"</font>, <font color="green">"red"</font>);
newChat.sendMessage(newMessage);
</pre></div><p>
The Chat object allows you to easily listen for replies from the other chat participant.
The following code snippet is a parrot-bot -- it echoes back everything the other user types.<p>
<div class="code"><pre>
<font color="gray"><i>// Assume we've created an XMPPConnection name "connection".</i></font>
Chat newChat = connection.createChat(<font color="green">"jsmith@jivesoftware.com"</font>);
newMessage.setBody(<font color="green">"Hi, I'm an annoying parrot-bot! Type something back to me."</font>);
<b>while</b> (<b>true</b>) {
<font color="gray"><i>// Wait for the next message the user types to us.</i></font>
Message message = newChat.nextMessage();
<font color="gray"><i>// Send back the same text the other user sent us.</i></font>
newChat.sendMessage(message.getBody());
}
</pre></div><p>
The code above uses the <tt>Chat.nextMessage()</tt> method to get the next message, which
will wait indefinitely until another message comes in. There are other methods to wait
a specific amount of time for a new message, or you can add a listener that will be notified
every time a new message arrives.
<p class="subheader">
GroupChat
</p>
A group chat connects to a chat room on a server and allows you to send and receive messages
from a group of people. Before you can send or receive messages, you must join the room using
a nickname. The following code snippet connects to a chat room and sends a
message.<p>
<div class="code"><pre>
<font color="gray"><i>// Assume we've created an XMPPConnection name "connection".</i></font>
GroupChat newGroupChat = connection.createGroupChat(<font color="green">"test@jivesoftware.com"</font>);
<font color="gray"><i>// Join the gropu chat using the nickname "jsmith".</i></font>
newGroupChat.join(<font color="green">"jsmith"</font>);
<font color="gray"><i>// Send a message to all the other people in the chat room.</i></font>
newGroupChat.sendMessage(<font color="green">"Howdy!"</font>);
</pre></div><p>
In general, sending and receiving messages in a group chat works very similarly to
the <tt>Chat</tt> class. Method are also provided to get the list of the other
users in the room.<p>
<br clear="all" /><br><br>
<div class="footer">
Copyright &copy; Jive Software 2002-2003
</div>
</body>
</html>

View file

@ -16,11 +16,11 @@ Smack Overview
<p>
Smack is a library for communicating with XMPP (Jabber) servers to perform
instant messaging and chat.
Smack is a library for communicating with XMPP servers to perform
instant messaging and chat.<p>
<p class="subheader">
Key Advantages:
Smack Key Advantages
</p>
<ul>
@ -47,6 +47,18 @@ connection.createChat(<font color="green">"jsmith@jivesoftware.com"</font>).send
non-commercial applications.
</ul>
<p class="subheader">
About XMPP
</p>
XMPP (eXtensible Messaging and Presence Protocol) is an open, XML based protocol
making it's way through the IETF approval process under the guidance of the
Jabber Software Foundation (<a href="http://www.jabber.org">http://www.jabber.org</a>).
For a good overview of the protocol, read the first chapter of <u>Instant Messaging
in Java</u>, available free at
<a href="http://www.jivesoftware.com/products/messenger/book/">http://www.jivesoftware.com/products/messenger/book/</a>
<br clear="all" /><br><br>
<div class="footer">
Copyright &copy; Jive Software 2002-2003
</div>

View file

@ -0,0 +1,86 @@
<html>
<head>
<title>Smack: Processing Incoming Packets - Jive Software</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<div class="header">
Processing Incoming Packets
</div>
<div class="nav">
&laquo; <a href="index.html">Table of Contents</a>
</div>
<p>
Smack provides a flexible framework for processing incoming packets using two constructs:
<ul>
<li><tt>org.jivesoftware.smack.PacketCollector</tt> -- a class that lets you
synchronously wait for new packets.
<li><tt>org.jivesoftware.smack.PacketListener</tt> -- an interface for asynchronously
notifying you of incoming packets.
</ul>
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 to come
through. Packet collectors and listeners can be created using an <tt>XMPPConnection</tt> object.<p>
The <tt>org.jivesoftware.smack.filter.PacketFilter</tt> interface determines which
specific packets will be delivered to a <tt>PacketCollector</tt> or <tt>PacketListener</tt>.
Many pre-defined filters can be found in the <tt>org.jivesoftware.smack.filter</tt> package.
<p>
The following code snippet demonstrates registering both a packet collector and a packet
listener:<p>
<div class="code"><pre>
<font color="gray"><i>// Create a packet filter to listen for new messages from a particular</i></font>
<font color="gray"><i>// user. We use an AndFilter to combine two other filters.</i></font>
PacketFilter filter = new AndFilter(new PacketTypeTypeFilter(<b>Message.class</b>),
new FromContainsFilter(<font color="green">"mary@jivesoftware.com"</font>));
<font color="gray"><i>// Assume we've created an XMPPConnection name "connection".</i></font>
<font color="gray"><i>// First, register a packet collector using the filter we created.</i></font>
PacketCollector myCollector = connection.createPacketCollector(filter);
<font color="gray"><i>// Normally, you'd do something with the collector, like wait for new packets.</i></font>
<font color="gray"><i>// Next, create a packet listener. We use an anonymous inner class for brevity.</i></font>
PacketListener myListener = new PacketListener() {
<b>public</b> <b>void</b> processPacket(Packet packet) {
<font color="gray"><i>// Do something with the incoming packet here.</i></font>
}
};
<font color="gray"><i>// Register the listener.</i></font>
connection.addPacketListener(myListener, filter);
</pre></div><p>
<p class="subheader">
Standard Packet Filters
</p>
A rich set of packet filters are included with Smack, or you can create your own filters by coding
to the <tt>PacketFilter</tt> interface. The default set of filters includes:
<ul>
<li> <tt>PacketTypeFilter</tt> -- filters for packets that are a particular Class type.
<li> <tt>PacketIDFilter</tt> -- filters for packets with a particular packet ID.
<li> <tt>ThreadFilter</tt> -- filters for message packets with a parituclar thread ID.
<li> <tt>ToContainsFilter</tt> -- filters for packets that are sent to a particular address.
<li> <tt>FromContainsFilter</tt> -- filters for packets that are sent to a particular address.
<li> <tt>PacketExtensionFilter</tt> -- filters for packets that have a particular packet extension.
<li> <tt>AndFilter</tt> -- implements the logical AND operation over two filters.
<li> <tt>OrFilter</tt> -- implements the logical OR operation over two filters.
<li> <tt>NotFilter</tt> -- implements the logical NOT operation on a filter.
</ul>
<br clear="all" /><br><br>
<div class="footer">
Copyright &copy; Jive Software 2002-2003
</div>
</body>
</html>

View file

@ -63,8 +63,13 @@ 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>Packet extensions are the more standard way to add extra data to XMPP stanzas. Using
properties may be more convenient in some cases, however, since Smack will do the
work of handling the XML.
<li>When you send a Java object as a property, 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