Hey John, this is my new - green - !!!! -
- -``` - -``` -// Create a message to send -Message msg = chat.createMessage(); -msg.setSubject("Any subject you want"); -msg.setBody("Hey John, this is my new green!!!!"); - -// Create an XHTMLText to send with the message -XHTMLText xhtmlText = new XHTMLText(null, null); -xhtmlText.appendOpenParagraphTag("font-size:large"); -xhtmlText.append("Hey John, this is my new "); -xhtmlText.appendOpenSpanTag("color:green"); -xhtmlText.append("green"); -xhtmlText.appendCloseSpanTag(); -xhtmlText.appendOpenEmTag(); -xhtmlText.append("!!!!"); -xhtmlText.appendCloseEmTag(); -xhtmlText.appendCloseParagraphTag(); -xhtmlText.appendCloseBodyTag(); - -// Add the XHTML text to the message -XHTMLManager.addBody(msg, xhtmlText); -``` - -Send an XHTML Message ---------------------- - -**Description** - -After you have composed an XHTML message you will want to send it. Once you -have added the XHTML content to the message you want to send you are almost -done. The last step is to send the message as you do with any other message. - -**Usage** - -An XHTML message is like any regular message, therefore to send the message -you can follow the usual steps you do in order to send a message. For example, -to send a message as part of a chat just use the message **#send(Message)** of -_**Chat**_ or you can use the message **#send(Stanza)** of -_**XMPPConnection**_. - -**Example** - -In this example we can see how to send a message with XHTML content as part of -a chat. - -``` -// Create a message to send -Message msg = chat.createMessage(); -// Obtain the XHTML text to send from somewhere -XHTMLText xhtmlBody = getXHTMLTextToSend(); - -// Add the XHTML text to the message -XHTMLManager.addBody(msg, xhtmlBody); - -// Send the message that contains the XHTML -chat.sendMessage(msg); -``` - -Receive an XHTML Message ------------------------- - -**Description** - -It is also possible to obtain the XHTML content from a received message. -Remember that the specification defines that a message may contain several -XHTML bodies where each body should be for a different language. - -**Usage** - -To get the XHTML bodies of a given message just send the message -**#getBodies(Message)** to the class _**XHTMLManager**_. The answer of this -message will be an _**List**_ with the different XHTML bodies of the -message or null if none. - -**Example** - -In this example we can see how to create a PacketListener that obtains the -XHTML bodies of any received message. - -``` -// Create a listener for the chat and display any XHTML content -PacketListener packetListener = new PacketListener() { -public void processPacket(Stanza packet) { - Message message = (Message) packet; - // Obtain the XHTML bodies of the message - ListThe XMPP protocol includes a base protocol and many optional extensions - typically documented as "XEP's". Smack provides the smack-legacy artifcate, with - implementations of now obsolete XEPs. You should no longer use this code!
- -- -
| Name | XEP # | Description | -
| Message Events | -XEP-0022 | -Requests and responds to message events. | -
- -This extension is used to request and respond to events relating to the delivery, -display, and composition of messages. There are three stages in this extension:
For more information on each stage please follow these links:
--Description
- -In order to receive event notifications for a given message you first have to specify -which events are you interested in. Each message that you send has to request its own event -notifications. Therefore, every message that you send as part of a chat should request its own event -notifications.
- -Usage- -The class MessageEventManager provides an easy way for requesting event notifications. All you have to do is specify -the message that requires the event notifications and the events that you are interested in. -
Use the static method MessageEventManager.addNotificationsRequests(Message message, boolean offline, boolean -delivered, boolean displayed, boolean composing) for requesting event notifications. -
- -Example-Below you can find an example that logs in a user to the server, creates a message, adds the requests -for notifications and sends the message. -
- // Connect to the server and log in
- conn1 = new XMPPConnection(host);
- conn1.login(server_user1, pass1);
-
- // Create a chat with user2
- Chat chat1 = conn1.createChat(user2);
-
- // Create a message to send
- Message msg = chat1.createMessage();
- msg.setSubject("Any subject you want");
- msg.setBody("An interesting body comes here...");
- // Add to the message all the notifications requests (offline, delivered, displayed,
- // composing)
- MessageEventManager.addNotificationsRequests(msg, true, true, true, true);
-
- // Send the message that contains the notifications request
- chat1.sendMessage(msg);
-
-
-
-- -Description
- -You can receive notification requests for the following events: delivered, displayed, composing and offline. You -must listen for these requests and react accordingly.
- -Usage- -The general idea is to create a new DefaultMessageEventRequestListener that will listen to the event notifications -requests and react with custom logic. Then you will have to add the listener to the -MessageEventManager that works on -the desired XMPPConnection. -
Note that DefaultMessageEventRequestListener is a default implementation of the -MessageEventRequestListener interface. -The class DefaultMessageEventRequestListener automatically sends a delivered notification to the sender of the message -if the sender has requested to be notified when the message is delivered. If you decide to create a new class that -implements the MessageEventRequestListener interface, please remember to send the delivered notification.
-- -Below you can find an example that connects two users to the server. One user will create a message, add the requests -for notifications and will send the message to the other user. The other user will add a -DefaultMessageEventRequestListener -to a MessageEventManager that will listen and react to the event notification requested by the other user. -
- // Connect to the server and log in the users
- conn1 = new XMPPTCPConnection(host);
- conn1.login(server_user1, pass1);
- conn2 = new XMPPTCPConnection(host);
- conn2.login(server_user2, pass2);
-
- // User2 creates a MessageEventManager
- MessageEventManager messageEventManager = new MessageEventManager(conn2);
- // User2 adds the listener that will react to the event notifications requests
- messageEventManager.addMessageEventRequestListener(new DefaultMessageEventRequestListener() {
- public void deliveredNotificationRequested(
- String from,
- String packetID,
- MessageEventManager messageEventManager) {
- super.deliveredNotificationRequested(from, packetID, messageEventManager);
- // DefaultMessageEventRequestListener automatically responds that the message was delivered when receives this request
- System.out.println("Delivered Notification Requested (" + from + ", " + packetID + ")");
- }
-
- public void displayedNotificationRequested(
- String from,
- String packetID,
- MessageEventManager messageEventManager) {
- super.displayedNotificationRequested(from, packetID, messageEventManager);
- // Send to the message's sender that the message was displayed
- messageEventManager.sendDisplayedNotification(from, packetID);
- }
-
- public void composingNotificationRequested(
- String from,
- String packetID,
- MessageEventManager messageEventManager) {
- super.composingNotificationRequested(from, packetID, messageEventManager);
- // Send to the message's sender that the message's receiver is composing a reply
- messageEventManager.sendComposingNotification(from, packetID);
- }
-
- public void offlineNotificationRequested(
- String from,
- String packetID,
- MessageEventManager messageEventManager) {
- super.offlineNotificationRequested(from, packetID, messageEventManager);
- // The XMPP server should take care of this request. Do nothing.
- System.out.println("Offline Notification Requested (" + from + ", " + packetID + ")");
- }
- });
-
- // User1 creates a chat with user2
- Chat chat1 = conn1.createChat(user2);
-
- // User1 creates a message to send to user2
- Message msg = chat1.createMessage();
- msg.setSubject("Any subject you want");
- msg.setBody("An interesting body comes here...");
- // User1 adds to the message all the notifications requests (offline, delivered, displayed,
- // composing)
- MessageEventManager.addNotificationsRequests(msg, true, true, true, true);
-
- // User1 sends the message that contains the notifications request
- chat1.sendMessage(msg);
- Thread.sleep(500);
- // User2 sends to the message's sender that the message's receiver cancelled composing a reply
- messageEventManager.sendCancelledNotification(user1, msg.getPacketID());
-
-
-
-- -Description
- -Once you have requested for event notifications you will start to receive notifications of events. You can -receive notifications of the following events: delivered, displayed, composing, offline and cancelled. You -will probably want to react to some or all of these events.
- -Usage- -The general idea is to create a new MessageEventNotificationListener that will listen to the event notifications -and react with custom logic. Then you will have to add the listener to the MessageEventManager that works on -the desired XMPPConnection. -
-Below you can find an example that logs in a user to the server, adds a MessageEventNotificationListener -to a MessageEventManager that will listen and react to the event notifications, creates a message, adds -the requests for notifications and sends the message. -
- // Connect to the server and log in
- conn1 = new XMPPTCPConnection(host);
- conn1.login(server_user1, pass1);
-
- // Create a MessageEventManager
- MessageEventManager messageEventManager = new MessageEventManager(conn1);
- // Add the listener that will react to the event notifications
- messageEventManager.addMessageEventNotificationListener(new MessageEventNotificationListener() {
- public void deliveredNotification(String from, String packetID) {
- System.out.println("The message has been delivered (" + from + ", " + packetID + ")");
- }
-
- public void displayedNotification(String from, String packetID) {
- System.out.println("The message has been displayed (" + from + ", " + packetID + ")");
- }
-
- public void composingNotification(String from, String packetID) {
- System.out.println("The message's receiver is composing a reply (" + from + ", " + packetID + ")");
- }
-
- public void offlineNotification(String from, String packetID) {
- System.out.println("The message's receiver is offline (" + from + ", " + packetID + ")");
- }
-
- public void cancelledNotification(String from, String packetID) {
- System.out.println("The message's receiver cancelled composing a reply (" + from + ", " + packetID + ")");
- }
- });
-
- // Create a chat with user2
- Chat chat1 = conn1.createChat(user2);
-
- // Create a message to send
- Message msg = chat1.createMessage();
- msg.setSubject("Any subject you want");
- msg.setBody("An interesting body comes here...");
- // Add to the message all the notifications requests (offline, delivered, displayed,
- // composing)
- MessageEventManager.addNotificationsRequests(msg, true, true, true, true);
-
- // Send the message that contains the notifications request
- chat1.sendMessage(msg);
-
-
-
-
-
-
diff --git a/documentation/legacy/toc.html b/documentation/legacy/toc.html
deleted file mode 100644
index 6ee245e50..000000000
--- a/documentation/legacy/toc.html
+++ /dev/null
@@ -1,19 +0,0 @@
-
-
-- -
- -
- - - diff --git a/documentation/messaging.md b/documentation/messaging.md deleted file mode 100644 index 3aa595dae..000000000 --- a/documentation/messaging.md +++ /dev/null @@ -1,95 +0,0 @@ -Messaging using Chats -===================== - -[Back](index.md) - -Sending messages back and forth is at the core of instant messaging. Although -individual messages can be sent and received as packets, it's generally easier -to treat the string of messages as a chat using the -`org.jivesoftware.smack.Chat` class. - -Chat ----- - -A chat creates a new thread of messages (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"._ -ChatManager chatmanager = ChatManager.getInstanceFor(connection); -Chat newChat = chatmanager.createChat("jsmith@jivesoftware.com", new MessageListener() { - public void processMessage(Chat chat, Message message) { - System.out.println("Received message: " + message); - } -}); - -try { - newChat.sendMessage("Howdy!"); -} -catch (XMPPException e) { - System.out.println("Error Delivering block"); -} -``` - -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: - -``` -Message newMessage = new Message(); -newMessage.setBody("Howdy!"); -message.setProperty("favoriteColor", "red"); -newChat.sendMessage(newMessage); -``` - -You'll also notice in the example above that we specified a MessageListener -when creating a chat. The listener is notified any time a new message arrives -from the other user in the chat. The following code snippet uses the listener -as a parrot-bot -- it echoes back everything the other user types. - -``` -// Assume a MessageListener we've setup with a chat._ - -public void processMessage(Chat chat, Message message) { - // Send back the same text the other user sent us._ - chat.sendMessage(message.getBody()); -} -``` - -Incoming Chat -------------- - -When chats are prompted by another user, the setup is slightly different since -you are receiving a chat message first. Instead of explicitly creating a chat -to send messages, you need to register to handle newly created Chat instances -when the ChatManager creates them. The ChatManager will already find a -matching chat (by thread id) and if none exists, then it will create a new one -that does match. To get this new chat, you have to register to be notified -when it happens. You can register a message listener to receive all future -messages as part of this handler. - -``` -// Assume we've created an XMPPConnection name "connection"._ -ChatManager chatManager = ChatManager.getInstanceFor(connection); -chatManager.addChatListener( - new ChatManagerListener() { - @Override - public void chatCreated(Chat chat, boolean createdLocally) - { - if (!createdLocally) - chat.addMessageListener(new MyNewMessageListener());; - } - }); -``` - -In addition to thread based chat messages, there are some clients that do not -send a thread id as part of the chat. To handle this scenario, Smack will -attempt match the incoming messages to the best fit existing chat, based on -the JID. It will attempt to find a chat with the same full JID, failing that, -it will try the base JID. If no existing chat to the user can found, then a -new one is created. - -Copyright (C) Jive Software 2002-2008 diff --git a/documentation/overview.md b/documentation/overview.md deleted file mode 100644 index 9c9d00334..000000000 --- a/documentation/overview.md +++ /dev/null @@ -1,48 +0,0 @@ -Smack Overview -============== - -[Back](index.md) - -Smack is a library for communicating with XMPP servers to perform real-time -communications, including instant messaging and group chat. - -Smack Key Advantages --------------------- - - * Extremely simple to use, yet powerful API. Sending a text message to a user can be accomplished in only a few lines of code: - - ```java - AbstractXMPPConnection connection = new XMPPTCPConnection("mtucker", "password", "jabber.org"); - connection.connect().login(); - - Chat chat = ChatManager.getInstanceFor(connection) - .createChat("jsmith@jivesoftware.com", new MessageListener() { - - public void processMessage(Chat chat, Message message) { - System.out.println("Received message: " + message); - } - }); - chat.sendMessage("Howdy!"); - ``` - -* Doesn't force you to code at the packet level, as other libraries do. Smack provides intelligent higher level constructs such as the `Chat` and `Roster` classes, which let you program more efficiently. - * Does not require that you're familiar with the XMPP XML format, or even that you're familiar with XML. - * Provides easy machine to machine communication. Smack lets you set any number of properties on each message, including properties that are Java objects. - * Open Source under the Apache License, which means you can incorporate Smack into your commercial or non-commercial applications. - -About XMPP ----------- - -XMPP (eXtensible Messaging and Presence Protocol) is an open protocol -standardized by the IETF and supported and extended by the XMPP Standards -Foundation (([http://www.xmpp.org](http://www.xmpp.org)). - -How To Use This Documentation ------------------------------ - -This documentation assumes that you're already familiar with the main features -of XMPP instant messaging. It's also highly recommended that you open the -Javadoc API guide and use that as a reference while reading through this -documentation. - -Copyright (C) Jive Software 2002-2008 diff --git a/documentation/processing.md b/documentation/processing.md deleted file mode 100644 index 868b88d4c..000000000 --- a/documentation/processing.md +++ /dev/null @@ -1,58 +0,0 @@ -Processing Incoming Stanzas -=========================== - -[Back](index.md) - -Smack provides a flexible framework for processing incoming packets using two -constructs: - - * `org.jivesoftware.smack.PacketCollector` -- a class that lets you synchronously wait for new packets. - * `org.jivesoftware.smack.PacketListener` -- an interface for asynchronously notifying you of incoming packets. 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 arrive. Packet collectors and listeners can be created using an `XMPPConnection` instance. - -The `org.jivesoftware.smack.filter.StanzaFilter` 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._ -StanzaFilter filter = new AndFilter(new StanzaTypeFilter(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 Stanza Filters ------------------------ - -A rich set of packet filters are included with Smack, or you can create your -own filters by coding to the `StanzaFilter` interface. The default set of -filters includes: - - * `StanzaTypeFilter` -- filters for packets that are a particular Class type. - * `StanzaIdFilter` -- filters for packets with a particular packet ID. - * `ThreadFilter` -- filters for message packets with a particular thread ID. - * `ToContainsFilter` -- filters for packets that are sent to a particular address. - * `FromContainsFilter` -- filters for packets that are sent to a particular address. - * `StanzaExtensionFilter` -- filters for packets that have a particular packet extension. - * `AndFilter` -- implements the logical AND operation over two filters. - * `OrFilter` -- implements the logical OR operation over two filters. - * `NotFilter` -- implements the logical NOT operation on a filter. - -Copyright (C) Jive Software 2002-2008 diff --git a/documentation/providers.md b/documentation/providers.md deleted file mode 100644 index 954fc64e3..000000000 --- a/documentation/providers.md +++ /dev/null @@ -1,345 +0,0 @@ -Provider Architecture: Stanza Extensions and Custom IQ's -======================================================== - -[Back](index.md) - -Introduction ------------- - -The Smack provider architecture is a system for plugging in custom XML parsing -of packet extensions and IQ packets. The standard [Smack -Extensions](extensions/index.md) are built using the provider architecture. -There are two types of providers: - - * `IQProvider` -- parses IQ requests into Java objects. - * `Extension Provider` -- parses XML sub-documents attached to packets into PacketExtension instances. By default, Smack only knows how to process a few standard packets and sub-packets that are in a few namespaces such as: - * jabber:iq:auth - * jabber:iq:roster - * jabber:iq:register There are many more IQ types and extensions that are part of XMPP standards, and of course an endless number that can be added as custom extensions. To support this, an extensible parsing mechanism is provided via Smack and user build providers. - -Whenever a packet extension is found in a packet, parsing will be -passed to the correct provider. Each provider must implement the -PacketExtensionProvider interface. Each extension provider is -responsible for parsing the raw XML stream, via the -[XML Pull Parser](http://www.xmlpull.org/), to contruct an object. - -You can also create an introspection provider -(`provider.IntrospectionProvider.PacketExtensionIntrospectionProvider`). Here, -bean introspection is used to try to automatically set the properties -of the class using the values in the packet extension sub-element. - -When no extension provider is registered for an element name and namespace -combination, Smack will store all top-level elements of the sub-packet in the -DefaultPacketExtension object and then attach it to the packet. - -Management of these providers is accomplished via the [ProviderManager]() -class. There are multiple ways to add providers to the manager. - - * Call addXXProvider methods - You can call the appropriate add methods directly. - -``` -ProviderManager.addIQProvider("element", "namespace", new MyIQProvider()); -ProviderManager.addExtensionProvider("element", "namespace", new MyExtProvider()); -``` - - * Add a loader - You can add a ProviderLoader which will inject a means of loading multiple providers (both types) into the manager. This is the mechanism used by Smack to load from the Smack specific file format (via ProviderFileLoader). Implementers can provide the means to load providers from any source they wish, or simply reuse the ProviderFileLoader to load from their own provider files. - - - ProviderManager.addLoader(new ProviderFileLoader(FileUtils.getStreamForUrl("classpath:com/myco/provider/myco_custom.providers", null))); - - - * VM Argument - You can add a provider file via the VM argument _smack.provider.file_. This will load the file at the specified URL during startup when Smack initializes. This also assumes the default configuration, since it requires that the **VmArgInitializer** was part of the startup configuration. - - -`-Dsmack.provider.file=classpath:com/myco/provider/myco_custom.provider`s - -or - -`-Dsmack.provider.file=file:///c:/myco/provider/myco_custom.providers` - - -IQ Providers ------------- - -The IQ provider class must implement the IQProvider interface. Each -IQProvider is responsible for parsing the raw XML stream to create an -IQ instance. - -You can also create an introspection provider -(`provider.IntrospectionProvider.IQIntrospectionProvider`). Which -uses, bean introspection to try to automatically set properties of the -IQ instance using the values found in the IQ packet XML. For example, -an XMPP time packet resembles the following: - -### Introspection - -_Time Stanza_ - - -