vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2025-09-09 09:09:38 +02:00
Code Issues Releases Wiki Activity

Deprecate Chat API, introduce new Chat API

Browse source 
Also add (From|To)TypeFilter and update/fix the documentation in a few places.
This commit is contained in:
Florian Schmaus 2017-01-11 19:35:55 +01:00
parent b0fef6ffcb
commit d47463a533
22 changed files with 612 additions and 113 deletions
Download patch file Download diff file Expand all files Collapse all files

1
documentation/extensions/index.md
View file

@ -69,6 +69,7 @@ Smack Extensions and currently supported XEPs of smack-extensions
| XMPP Over BOSH | [XEP-0206](http://xmpp.org/extensions/xep-0206.html) | Use Bidirectional-streams Over Synchronous HTTP (BOSH) to transport XMPP stanzas. |
| Attention | [XEP-0224](http://xmpp.org/extensions/xep-0224.html) | Getting attention of another user. |
| Bits of Binary | [XEP-0231](http://xmpp.org/extensions/xep-0231.html) | Including or referring to small bits of binary data in an XML stanza. |
| Best Practices for Resource Locking | [XEP-0296](https://xmpp.org/extensions/xep-0296.html) | Specifies best practices to be followed by Jabber/XMPP clients about when to lock into, and unlock away from, resources. |
| Last Message Correction | [XEP-0308](http://xmpp.org/extensions/xep-0308.html) | Provides a method for indicating that a message is a correction of the last sent message. |
| [Group Chat Invitations](invitation.md) | n/a | Send invitations to other users to join a group chat room. |
| [Jive Properties](properties.md) | n/a | TODO |

23
documentation/extensions/xhtml.md
View file

@ -97,8 +97,8 @@ done. The last step is to send the message as you do with any other message.
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
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**
@ -142,19 +142,20 @@ XHTML bodies of any received message.
```
// Create a listener for the chat and display any XHTML content
PacketListener packetListener = new PacketListener() {
public void processStanza(Stanza stanza) {
Message message = (Message) stanza;
IncomingChatMessageListener listener = new IncomingChatMessageListener() {
public void newIncomingMessage(EntityBareJid from, Message message, Chat chat) {
// Obtain the XHTML bodies of the message
List<CharSequence> bodies = XHTMLManager.getBodies(message);
if (bodies != null) {
// Display the bodies on the console
for (CharSequence body : bodies) {
System.out.println(body);
}
if (bodies == null) {
return;
// Display the bodies on the console
for (CharSequence body : bodies) {
System.out.println(body);
}
}
};
chat.addMessageListener(packetListener);
chatManager.addListener(listener);
```
Discover support for XHTML Messages

20
documentation/gettingstarted.md
View file

@ -70,7 +70,7 @@ created, such as the ability to disable or require encryption. See
Once you've created a connection, you should login with the
`XMPPConnection.login()` method. Once you've logged in, you can being
chatting with other users by creating new `Chat` or `GroupChat`
chatting with other users by creating new `Chat` or `MultiUserChat`
objects.
Working with the Roster
@ -98,18 +98,18 @@ your presence to let people know you're unavailable and "out fishing":
// Create a new presence. Pass in false to indicate we're unavailable._
Presence presence = new Presence(Presence.Type.unavailable);
presence.setStatus("Gone fishing");
// Send the packet (assume we have an XMPPConnection instance called "con").
// Send the stanza (assume we have an XMPPConnection instance called "con").
con.sendStanza(presence);
```
Smack provides two ways to read incoming packets: `PacketListener`, and
`PacketCollector`. Both use `StanzaFilter` instances to determine which
packets should be processed. 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 Connection
Smack provides two ways to read incoming packets: `StanzaListener`, and
`StanzaCollector`. Both use `StanzaFilter` instances to determine which
stanzas should be processed. A stanza listener is used for event style
programming, while a stanza collector has a result queue of packets 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 packet to
arrive. Stanza collectors and listeners can be created using an Connection
instance.
Copyright (C) Jive Software 2002-2008

76
documentation/messaging.md
View file

@ -6,7 +6,7 @@ Messaging using Chats
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.
`org.jivesoftware.smack.chat2.Chat` class.
Chat
----
@ -17,80 +17,44 @@ 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);
}
ChatManager chatManager = ChatManager.getInstanceFor(connection);
chatManager.addListener(new IncomingChatMessageListener() {
@Override
void newIncomingMessage(EntityBareJid from, Message message, Chat chat) {
System.out.println("New message from " + from ": " + message.getBody());
}
});
try {
newChat.sendMessage("Howdy!");
}
catch (XMPPException e) {
System.out.println("Error Delivering block");
EntityBareJid jid = JidCreate.entityBareFrom("jsmith@jivesoftware.com");
Chat chat = chatManager.chatWith(jid);
chat.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:
before sending it, use
`Chat.sendMessage(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");
newChat.sendMessage(newMessage);
chat.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
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 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());
// 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.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