From 8a94e6904502f0f04e97350fc0cb8a6e9566887d Mon Sep 17 00:00:00 2001 From: Matt Tucker Date: Thu, 19 Jun 2003 18:11:37 +0000 Subject: [PATCH] Documentation updates. git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@1969 b35dd754-fafc-0310-a699-88a17e54d16e --- documentation/index.html | 4 ++ documentation/messaging.html | 108 ++++++++++++++++++++++++++++++++++ documentation/overview.html | 18 +++++- documentation/processing.html | 86 +++++++++++++++++++++++++++ documentation/properties.html | 9 ++- 5 files changed, 220 insertions(+), 5 deletions(-) create mode 100644 documentation/messaging.html diff --git a/documentation/index.html b/documentation/index.html index 006a01cae..bce5aded1 100644 --- a/documentation/index.html +++ b/documentation/index.html @@ -18,6 +18,10 @@ Documentation Contents: diff --git a/documentation/messaging.html b/documentation/messaging.html new file mode 100644 index 000000000..c6c176f3c --- /dev/null +++ b/documentation/messaging.html @@ -0,0 +1,108 @@ + + + Smack: Chat - Jive Software + + + + + +
+Messaging using Chat and GroupChat +
+ +
+« Table of Contents +
+ +

+Sending messages back and forth is at the core of instant messaging. Two classes +aid in sending and recieiving messages: +

+ +Both the Chat and GroupChat classes use the org.jivesoftware.smack.packet.Message 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. +

+ +

+Chat +

+ +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:

+ +

+// Assume we've created an XMPPConnection name "connection".
+Chat newChat = connection.createChat("jsmith@jivesoftware.com");
+newChat.sendMessage("Howdy!");
+

+ +The Chat.sendMessage(String) 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 +Chat.createMessage() and Chat.sendMessage(Message) methods, as in the +following code snippet:

+ +

+// Assume we've created an XMPPConnection name "connection".
+Chat newChat = connection.createChat("jsmith@jivesoftware.com");
+Message newMessage = newChat.createMessage();
+newMessage.setBody("Howdy!");
+message.setProperty("favoriteColor", "red");
+newChat.sendMessage(newMessage);
+

+ +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.

+ +

+// Assume we've created an XMPPConnection name "connection".
+Chat newChat = connection.createChat("jsmith@jivesoftware.com");
+newMessage.setBody("Hi, I'm an annoying parrot-bot! Type something back to me.");
+while (true) {
+    // Wait for the next message the user types to us.
+    Message message = newChat.nextMessage();
+    // Send back the same text the other user sent us.
+    newChat.sendMessage(message.getBody());
+}
+

+ +The code above uses the Chat.nextMessage() 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. + +

+GroupChat +

+ +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.

+ +

+// Assume we've created an XMPPConnection name "connection".
+GroupChat newGroupChat = connection.createGroupChat("test@jivesoftware.com");
+// Join the gropu chat using the nickname "jsmith".
+newGroupChat.join("jsmith");
+// Send a message to all the other people in the chat room.
+newGroupChat.sendMessage("Howdy!");
+

+ +In general, sending and receiving messages in a group chat works very similarly to +the Chat class. Method are also provided to get the list of the other +users in the room.

+ +


+ +

+Copyright © Jive Software 2002-2003 +
+ + + diff --git a/documentation/overview.html b/documentation/overview.html index 56e9b4d4a..c23d9104e 100644 --- a/documentation/overview.html +++ b/documentation/overview.html @@ -16,11 +16,11 @@ Smack Overview

-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.

-Key Advantages: +Smack Key Advantages

+

+About XMPP +

+ +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 (http://www.jabber.org). +For a good overview of the protocol, read the first chapter of Instant Messaging +in Java, available free at +http://www.jivesoftware.com/products/messenger/book/ + +


Copyright © Jive Software 2002-2003
diff --git a/documentation/processing.html b/documentation/processing.html index e69de29bb..2a4ebb38b 100644 --- a/documentation/processing.html +++ b/documentation/processing.html @@ -0,0 +1,86 @@ + + + Smack: Processing Incoming Packets - Jive Software + + + + + +
+Processing Incoming Packets +
+ +
+« Table of Contents +
+ +

+ +Smack provides a flexible framework for processing incoming packets using two constructs: +

+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 XMPPConnection object.

+ +The org.jivesoftware.smack.filter.PacketFilter interface determines which +specific packets will be delivered to a PacketCollector or PacketListener. +Many pre-defined filters can be found in the org.jivesoftware.smack.filter package. + +

+The following code snippet demonstrates registering both a packet collector and a packet +listener:

+ +

+// Create a packet filter to listen for new messages from a particular
+// user. We use an AndFilter to combine two other filters.
+PacketFilter filter = new AndFilter(new PacketTypeTypeFilter(Message.class), 
+        new FromContainsFilter("mary@jivesoftware.com"));
+// Assume we've created an XMPPConnection name "connection".
+
+// First, register a packet collector using the filter we created.
+PacketCollector myCollector = connection.createPacketCollector(filter);
+// Normally, you'd do something with the collector, like wait for new packets.
+
+// Next, create a packet listener. We use an anonymous inner class for brevity.
+PacketListener myListener = new PacketListener() {
+        public void processPacket(Packet packet) {
+            // Do something with the incoming packet here.
+        }
+    };
+// Register the listener.
+connection.addPacketListener(myListener, filter);
+

+ +

+Standard Packet Filters +

+ +A rich set of packet filters are included with Smack, or you can create your own filters by coding +to the PacketFilter interface. The default set of filters includes: + + +


+ +
+Copyright © Jive Software 2002-2003 +
+ + + \ No newline at end of file diff --git a/documentation/properties.html b/documentation/properties.html index 236e2d866..14ac19043 100644 --- a/documentation/properties.html +++ b/documentation/properties.html @@ -63,8 +63,13 @@ you should keep the following in mind: