mirror of
https://github.com/vanitasvitae/Smack.git
synced 2024-11-22 12:02:05 +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
mtucker
parent
b9778d77ab
commit
8a94e69045
5 changed files with 220 additions and 5 deletions
|
|
@ -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>
|
||||
|
|
|
|||
108
documentation/messaging.html
Normal file
108
documentation/messaging.html
Normal 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">
|
||||
« <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 © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -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 © Jive Software 2002-2003
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
« <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 © Jive Software 2002-2003
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue