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 **#sendMessage(Message)** of -_**Chat**_ or you can use the message **#sendStanza(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 -IncomingChatMessageListener listener = new IncomingChatMessageListener() { -public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) { - // 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 98343b1c1..000000000 --- a/documentation/messaging.md +++ /dev/null @@ -1,60 +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.chat2.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); -chatManager.addIncomingListener(new IncomingChatMessageListener() { - @Override - void newIncomingMessage(EntityBareJid from, Message message, Chat chat) { - System.out.println("New message from " + from + ": " + message.getBody()); - } -}); -EntityBareJid jid = JidCreate.entityBareFrom("jsmith@jivesoftware.com"); -Chat chat = chatManager.chatWith(jid); -chat.send("Howdy!"); -} -``` - -The `Chat.send(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.send(Message)` method, as in the following code snippet: - -``` -Message newMessage = new Message(); -newMessage.setBody("Howdy!"); -// Additional modifications to the message Stanza. -JivePropertiesManager.addProperty(newMessage, "favoriteColor", "red"); -chat.send(newMessage); -``` - -You'll also notice in the example above that we specified an IncomingChatMessageListener. -The listener is notified any time a new chat message arrives. -The following code snippet uses the listener -as a parrot-bot -- it echoes back everything the other user types. - -``` -// Assume a IncomingChatMessageListener we've setup with a ChatManager -public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) { - // Send back the same text the other user sent us. - chat.send(message.getBody()); -} -``` - -Copyright (C) Jive Software 2002-2008 diff --git a/documentation/overview.md b/documentation/overview.md deleted file mode 100644 index 2e169a8b6..000000000 --- a/documentation/overview.md +++ /dev/null @@ -1,46 +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(); - - Message message = connection.getStanzaFactory() - .buildMessageStanza() - .to("jsmith@jivesoftware.com") - .setBody("Howdy! How are you?") - .build(); - connection.sendStanza(message); - ``` - -* Doesn't force you to code at the XMPP protocol 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 2.0, 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 (XSF, [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 c5c246713..000000000 --- a/documentation/processing.md +++ /dev/null @@ -1,60 +0,0 @@ -Processing Incoming Stanzas -=========================== - -[Back](index.md) - -Smack provides a flexible framework for processing incoming stanzas using two -constructs: - - * `org.jivesoftware.smack.StanzaCollector` -- a class that lets you synchronously wait for new stanzas. - * `org.jivesoftware.smack.StanzaListener` -- an interface for asynchronously notifying you of incoming stanzas. A stanza listener is used for event style programming, while a stanza collector has a result queue of stanzas that you can do polling and blocking operations on. So, a stanza listener is useful when you want to take some action whenever a stanza happens to come in, while a stanza collector is useful when you want to wait for a specific stanza to arrive. Stanza collectors and listeners can be created using an `XMPPConnection` instance. - -The `org.jivesoftware.smack.filter.StanzaFilter` interface determines which -specific stanzas will be delivered to a `StanzaCollector` or `StanzaListener`. -Many pre-defined filters can be found in the `org.jivesoftware.smack.filter` -package. - -The following code snippet demonstrates registering both a stanza collector -and a stanza listener: - -``` -// Create a stanza filter to listen for new messages from a particular -// user. We use an AndFilter to combine two other filters._ -StanzaFilter filter = new AndFilter(StanzaTypeFilter.MESSAGE, - FromMatchesFilter.create(JidCreate.entityBareFrom("mary@jivesoftware.com"))); -// Assume we've created an XMPPConnection named "connection". - -// First, register a stanza collector using the filter we created. -StanzaCollector myCollector = connection.createStanzaCollector(filter); -// Normally, you'd do something with the collector, like wait for new packets. - -// Next, create a stanza listener. We use an anonymous inner class for brevity. -StanzaListener myListener = new StanzaListener() { - public void processStanza(Stanza stanza) { - // Do something with the incoming stanza here._ - } - }; -// Register the listener._ -connection.addAsyncStanzaListener(myListener, filter); -// or for a synchronous stanza listener use -connection.addSyncStanzaListener(myListener, filter); -``` - -Standard Stanza Filters ------------------------ - -A rich set of stanza 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 stanzas that are a particular Class type. - * `StanzaIdFilter` -- filters for stanzas with a particular packet ID. - * `ThreadFilter` -- filters for message stanzas with a particular thread ID. - * `ToMatchesFilter` -- filters for stanzas that are sent to a particular address. - * `FromMatchesFilter` -- filters for stanzas that are sent from a particular address. - * `StanzaExtensionFilter` -- filters for stanzas that have a particular stanza 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 8eb6a5108..000000000 --- a/documentation/providers.md +++ /dev/null @@ -1,350 +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 ExtensionElement 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 extend the -ExtensionElementProvider abstract class. Each extension provider is -responsible for parsing the raw XML stream, via the -Smack's `XmlPullParser` interface, to construct 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 -StandardExtensionElement 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.providers` - -or - -`-Dsmack.provider.file=file:///c:/myco/provider/myco_custom.providers` - - -IQ Providers ------------- - -The IQ provider class must extend the IQProvider abstract class. 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_ - - -