Improved Support: XEP-0249: Direct MUC Invitations

This commit is contained in:
Paul Schaub 2020-07-18 12:55:26 +02:00
parent b7fe56fb9b
commit 036ab79ada
Signed by: vanitasvitae
GPG Key ID: 62BEE9264BF17311
9 changed files with 382 additions and 52 deletions

View File

@ -84,12 +84,12 @@ Smack Extensions and currently supported XEPs of smack-extensions
| Attention | [XEP-0224](https://xmpp.org/extensions/xep-0224.html) | n/a | Getting attention of another user. |
| Bits of Binary | [XEP-0231](https://xmpp.org/extensions/xep-0231.html) | n/a | Including or referring to small bits of binary data in an XML stanza. |
| Software Information | [XEP-0232](https://xmpp.org/extensions/xep-0232.html) | 0.3 | Allows an entity to provide detailed data about itself in Service Discovery responses. |
| Direct MUC Invitations | [XEP-0249](https://xmpp.org/extensions/xep-0249.html) | 1.2 | Invite other users to group chats. |
| Best Practices for Resource Locking | [XEP-0296](https://xmpp.org/extensions/xep-0296.html) | n/a | Specifies best practices to be followed by Jabber/XMPP clients about when to lock into, and unlock away from, resources. |
| Stanza Forwarding | [XEP-0297](https://xmpp.org/extensions/xep-0297.html) | n/a | Allows forwarding of Stanzas. |
| Last Message Correction | [XEP-0308](https://xmpp.org/extensions/xep-0308.html) | n/a | Provides a method for indicating that a message is a correction of the last sent message. |
| Last User Interaction in Presence | [XEP-0319](https://xmpp.org/extensions/xep-0319.html) | n/a | Communicate time of last user interaction via XMPP presence notifications. |
| Data Forms Geolocation Element | [XEP-0350](https://xmpp.org/extensions/xep-0350.html) | n/a | Allows to include XEP-0080 gelocation data in XEP-0004 data forms. |
| [Group Chat Invitations](invitation.md) | n/a | n/a | Send invitations to other users to join a group chat room. |
| [Jive Properties](properties.md) | n/a | n/a | TODO |

View File

@ -10,6 +10,7 @@ group chat room.
* Listen for Invitations
**XEP related:** N/A -- this protocol is outdated now that the Multi-User Chat (MUC) XEP is available ([XEP-45](http://www.xmpp.org/extensions/xep-0045.html)). However, most existing clients still use this older protocol. Once MUC support becomes more widespread, this API may be deprecated.
**XEP related:** Now there is support for XEP-0249: Direct MUC Invitations.
Inviting Other Users
--------------------

View File

@ -0,0 +1,25 @@
/**
*
* Copyright 2020 Paul Schaub.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.smackx.muc;
import org.jivesoftware.smack.packet.Stanza;
import org.jivesoftware.smackx.muc.packet.GroupChatInvitation;
public interface DirectMucInvitationListener {
void invitationReceived(GroupChatInvitation invitation, Stanza stanza);
}

View File

@ -0,0 +1,115 @@
/**
*
* Copyright 2020 Paul Schaub.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.smackx.muc;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.WeakHashMap;
import org.jivesoftware.smack.Manager;
import org.jivesoftware.smack.SmackException;
import org.jivesoftware.smack.XMPPConnection;
import org.jivesoftware.smack.XMPPConnectionRegistry;
import org.jivesoftware.smack.XMPPException;
import org.jivesoftware.smack.filter.StanzaExtensionFilter;
import org.jivesoftware.smack.packet.Message;
import org.jivesoftware.smack.packet.MessageBuilder;
import org.jivesoftware.smackx.disco.ServiceDiscoveryManager;
import org.jivesoftware.smackx.muc.packet.GroupChatInvitation;
import org.jxmpp.jid.EntityBareJid;
/**
* Smacks API for XEP-0249: Direct MUC Invitations.
* Use this instead of {@link org.jivesoftware.smackx.muc.packet.MUCUser.Invite}.
*
* To invite a user to a group chat, use {@link #inviteToMuc(MultiUserChat, EntityBareJid)}.
*
* In order to listen for incoming invitations, register a {@link DirectMucInvitationListener} using
* {@link #addInvitationListener(DirectMucInvitationListener)}.
*
* @see <a href="https://xmpp.org/extensions/xep-0249.html">Direct MUC Invitations</a>
*/
public final class DirectMucInvitationManager extends Manager {
private static final Map<XMPPConnection, DirectMucInvitationManager> INSTANCES = new WeakHashMap<>();
private final List<DirectMucInvitationListener> directMucInvitationListeners = new ArrayList<>();
private final ServiceDiscoveryManager serviceDiscoveryManager;
static {
XMPPConnectionRegistry.addConnectionCreationListener(DirectMucInvitationManager::getInstanceFor);
}
public static synchronized DirectMucInvitationManager getInstanceFor(XMPPConnection connection) {
DirectMucInvitationManager manager = INSTANCES.get(connection);
if (manager == null) {
manager = new DirectMucInvitationManager(connection);
INSTANCES.put(connection, manager);
}
return manager;
}
private DirectMucInvitationManager(XMPPConnection connection) {
super(connection);
serviceDiscoveryManager = ServiceDiscoveryManager.getInstanceFor(connection);
registerExtensionElementListener();
serviceDiscoveryManager.addFeature(GroupChatInvitation.NAMESPACE);
}
private void registerExtensionElementListener() {
connection().addAsyncStanzaListener(stanza -> {
GroupChatInvitation invitation = stanza.getExtension(GroupChatInvitation.class);
for (DirectMucInvitationListener listener : directMucInvitationListeners) {
listener.invitationReceived(invitation, stanza);
}
}, new StanzaExtensionFilter(GroupChatInvitation.ELEMENT, GroupChatInvitation.NAMESPACE));
}
public void inviteToMuc(MultiUserChat muc, EntityBareJid user)
throws SmackException.NotConnectedException, InterruptedException {
inviteToMuc(muc, user, null, null, false, null);
}
public void inviteToMuc(MultiUserChat muc, EntityBareJid user, String password, String reason, boolean _continue, String thread)
throws SmackException.NotConnectedException, InterruptedException {
inviteToMuc(user, new GroupChatInvitation(muc.getRoom(), password, reason, _continue, thread));
}
public void inviteToMuc(EntityBareJid jid, GroupChatInvitation invitation) throws SmackException.NotConnectedException, InterruptedException {
Message invitationMessage = MessageBuilder.buildMessage()
.to(jid)
.addExtension(invitation)
.build();
connection().sendStanza(invitationMessage);
}
public boolean userSupportsInvitations(EntityBareJid jid)
throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException,
SmackException.NoResponseException {
return ServiceDiscoveryManager.getInstanceFor(connection()).supportsFeature(jid, GroupChatInvitation.NAMESPACE);
}
public synchronized void addInvitationListener(DirectMucInvitationListener listener) {
this.directMucInvitationListeners.add(listener);
}
public synchronized void removeInvitationListener(DirectMucInvitationListener listener) {
this.directMucInvitationListeners.remove(listener);
}
}

View File

@ -79,6 +79,10 @@ import org.jxmpp.util.cache.ExpirationCache;
* further attempts will be made for the other rooms.
* </p>
*
* Note:
* For inviting other users to a group chat or listening for such invitations, take a look at the
* {@link DirectMucInvitationManager} which provides an implementation of XEP-0249: Direct MUC Invitations.
*
* @see <a href="http://xmpp.org/extensions/xep-0045.html">XEP-0045: Multi-User Chat</a>
*/
public final class MultiUserChatManager extends Manager {

View File

@ -1,6 +1,6 @@
/**
*
* Copyright 2003-2007 Jive Software.
* Copyright 2003-2007 Jive Software, 2020 Paul Schaub.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@ -17,46 +17,28 @@
package org.jivesoftware.smackx.muc.packet;
import java.io.IOException;
import javax.xml.namespace.QName;
import org.jivesoftware.smack.packet.ExtensionElement;
import org.jivesoftware.smack.packet.Stanza;
import org.jivesoftware.smack.packet.XmlEnvironment;
import org.jivesoftware.smack.provider.ExtensionElementProvider;
import org.jivesoftware.smack.util.EqualsUtil;
import org.jivesoftware.smack.util.HashCode;
import org.jivesoftware.smack.util.Objects;
import org.jivesoftware.smack.util.XmlStringBuilder;
import org.jivesoftware.smack.xml.XmlPullParser;
import org.jivesoftware.smack.xml.XmlPullParserException;
import org.jxmpp.jid.EntityBareJid;
import org.jxmpp.jid.impl.JidCreate;
/**
* A group chat invitation stanza extension, which is used to invite other
* users to a group chat room. To invite a user to a group chat room, address
* a new message to the user and set the room name appropriately, as in the
* following code example:
* users to a group chat room.
*
* <pre>
* Message message = new Message("user@chat.example.com");
* message.setBody("Join me for a group chat!");
* message.addExtension(new GroupChatInvitation("room@chat.example.com"););
* con.sendStanza(message);
* </pre>
*
* To listen for group chat invitations, use a StanzaExtensionFilter for the
* <code>x</code> element name and <code>jabber:x:conference</code> namespace, as in the
* following code example:
*
* <pre>
* PacketFilter filter = new StanzaExtensionFilter("x", "jabber:x:conference");
* // Create a stanza collector or stanza listeners using the filter...
* </pre>
*
* <b>Note</b>: this protocol is outdated now that the Multi-User Chat (MUC) XEP is available
* (<a href="http://www.xmpp.org/extensions/jep-0045.html">XEP-45</a>). However, most
* existing clients still use this older protocol. Once MUC support becomes more
* widespread, this API may be deprecated.
* This implementation now conforms to XEP-0249: Direct MUC Invitations,
* while staying backwards compatible to legacy MUC invitations.
*
* @author Matt Tucker
* @author Paul Schaub
*/
public class GroupChatInvitation implements ExtensionElement {
@ -69,10 +51,19 @@ public class GroupChatInvitation implements ExtensionElement {
* Namespace of the stanza extension.
*/
public static final String NAMESPACE = "jabber:x:conference";
public static final QName QNAME = new QName(NAMESPACE, ELEMENT);
private final String roomAddress;
public static final String ATTR_CONTINUE = "continue";
public static final String ATTR_JID = "jid";
public static final String ATTR_PASSWORD = "password";
public static final String ATTR_REASON = "reason";
public static final String ATTR_THREAD = "thread";
private final EntityBareJid roomAddress;
private final String password;
private final String reason;
private final boolean _continue;
private final String thread;
/**
* Creates a new group chat invitation to the specified room address.
@ -81,9 +72,23 @@ public class GroupChatInvitation implements ExtensionElement {
* <code>chat.example.com</code>.
*
* @param roomAddress the address of the group chat room.
* @deprecated use {@link #GroupChatInvitation(EntityBareJid)} instead.
*/
@Deprecated
public GroupChatInvitation(String roomAddress) {
this.roomAddress = roomAddress;
this(JidCreate.entityBareFromOrThrowUnchecked(roomAddress));
}
public GroupChatInvitation(EntityBareJid roomAddress) {
this(roomAddress, null, null, false, null);
}
public GroupChatInvitation(EntityBareJid mucJid, String password, String reason, boolean _continue, String thread) {
this.roomAddress = Objects.requireNonNull(mucJid);
this.password = password;
this.reason = reason;
this._continue = _continue;
this.thread = thread;
}
/**
@ -91,12 +96,62 @@ public class GroupChatInvitation implements ExtensionElement {
* are in the form <code>room@service</code>, where <code>service</code> is
* the name of group chat server, such as <code>chat.example.com</code>.
*
* TODO: Remove in Smack 4.5
* @deprecated use {@link #getRoomAddressJid()} instead.
* @return the address of the group chat room.
*/
@Deprecated
public String getRoomAddress() {
return roomAddress.asEntityBareJidString();
}
/**
* Returns the address of the group chat room as an {@link EntityBareJid}.
*
* @return room address
*/
public EntityBareJid getRoomAddressJid() {
return roomAddress;
}
/**
* Returns the password which is used to join the room.
* This value can be null if no password is required.
*
* @return password
*/
public String getPassword() {
return password;
}
/**
* Return the reason of invitation.
*
* @return reason
*/
public String getReason() {
return reason;
}
/**
* Returns true if the invitation represents the continuation of a one-to-one chat.
* The chat continues the thread returned by {@link #getThread()}.
*
* @return true if this is a continued one-to-one chat, false otherwise.
*/
public boolean isContinue() {
return _continue;
}
/**
* In case of a continuation, this returns the thread name of the one-to-one chat that is being continued.
*
* @return thread
*/
public String getThread() {
return thread;
}
@Override
public String getElementName() {
return ELEMENT;
@ -108,11 +163,35 @@ public class GroupChatInvitation implements ExtensionElement {
}
@Override
public XmlStringBuilder toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) {
XmlStringBuilder xml = new XmlStringBuilder(this);
xml.attribute("jid", getRoomAddress());
xml.closeEmptyElement();
return xml;
public XmlStringBuilder toXML(XmlEnvironment xmlEnvironment) {
return new XmlStringBuilder(this)
.optBooleanAttribute(ATTR_CONTINUE, isContinue())
.attribute(ATTR_JID, getRoomAddressJid())
.optAttribute(ATTR_PASSWORD, getPassword())
.optAttribute(ATTR_REASON, getReason())
.optAttribute(ATTR_THREAD, getThread())
.closeEmptyElement();
}
@Override
public boolean equals(Object obj) {
return EqualsUtil.equals(this, obj, (equalsBuilder, other) -> equalsBuilder
.append(getRoomAddressJid(), other.getRoomAddressJid())
.append(getPassword(), other.getPassword())
.append(getReason(), other.getReason())
.append(isContinue(), other.isContinue())
.append(getThread(), other.getThread()));
}
@Override
public int hashCode() {
return HashCode.builder()
.append(getRoomAddressJid())
.append(getPassword())
.append(getReason())
.append(isContinue())
.append(getThread())
.build();
}
/**
@ -123,17 +202,4 @@ public class GroupChatInvitation implements ExtensionElement {
public static GroupChatInvitation from(Stanza packet) {
return packet.getExtension(GroupChatInvitation.class);
}
public static class Provider extends ExtensionElementProvider<GroupChatInvitation> {
@Override
public GroupChatInvitation parse(XmlPullParser parser,
int initialDepth, XmlEnvironment xmlEnvironment) throws XmlPullParserException,
IOException {
String roomAddress = parser.getAttributeValue("", "jid");
// Advance to end of extension.
parser.next();
return new GroupChatInvitation(roomAddress);
}
}
}

View File

@ -0,0 +1,53 @@
/**
*
* Copyright 2020 Paul Schaub.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.smackx.muc.provider;
import static org.jivesoftware.smackx.muc.packet.GroupChatInvitation.ATTR_CONTINUE;
import static org.jivesoftware.smackx.muc.packet.GroupChatInvitation.ATTR_JID;
import static org.jivesoftware.smackx.muc.packet.GroupChatInvitation.ATTR_PASSWORD;
import static org.jivesoftware.smackx.muc.packet.GroupChatInvitation.ATTR_REASON;
import static org.jivesoftware.smackx.muc.packet.GroupChatInvitation.ATTR_THREAD;
import java.io.IOException;
import org.jivesoftware.smack.packet.XmlEnvironment;
import org.jivesoftware.smack.parsing.SmackParsingException;
import org.jivesoftware.smack.provider.ExtensionElementProvider;
import org.jivesoftware.smack.util.ParserUtils;
import org.jivesoftware.smack.xml.XmlPullParser;
import org.jivesoftware.smack.xml.XmlPullParserException;
import org.jivesoftware.smackx.muc.packet.GroupChatInvitation;
import org.jxmpp.jid.EntityBareJid;
public class GroupChatInvitationProvider extends ExtensionElementProvider<GroupChatInvitation> {
public static final GroupChatInvitationProvider TEST_PROVIDER = new GroupChatInvitationProvider();
@Override
public GroupChatInvitation parse(XmlPullParser parser, int initialDepth, XmlEnvironment xmlEnvironment)
throws XmlPullParserException, IOException, SmackParsingException {
EntityBareJid roomJid = ParserUtils.getBareJidAttribute(parser, ATTR_JID);
String password = parser.getAttributeValue(ATTR_PASSWORD);
String reason = parser.getAttributeValue(ATTR_REASON);
boolean isContinue = ParserUtils.getBooleanAttribute(parser, ATTR_CONTINUE, false);
String thread = parser.getAttributeValue(ATTR_THREAD);
return new GroupChatInvitation(roomJid, password, reason, isContinue, thread);
}
}

View File

@ -510,7 +510,7 @@
<extensionProvider>
<elementName>x</elementName>
<namespace>jabber:x:conference</namespace>
<className>org.jivesoftware.smackx.muc.packet.GroupChatInvitation$Provider</className>
<className>org.jivesoftware.smackx.muc.provider.GroupChatInvitationProvider</className>
</extensionProvider>
<!-- XEP-0297: Stanza Forwarding -->

View File

@ -0,0 +1,66 @@
/**
*
* Copyright 2020 Paul Schaub.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jivesoftware.smackx.muc.packet;
import static org.jivesoftware.smack.test.util.XmlAssertUtil.assertXmlSimilar;
import static org.junit.jupiter.api.Assertions.assertEquals;
import java.io.IOException;
import org.jivesoftware.smack.parsing.SmackParsingException;
import org.jivesoftware.smack.test.util.TestUtils;
import org.jivesoftware.smack.xml.XmlPullParserException;
import org.jivesoftware.smackx.muc.provider.GroupChatInvitationProvider;
import org.junit.jupiter.api.Test;
import org.jxmpp.jid.EntityBareJid;
import org.jxmpp.jid.impl.JidCreate;
public class GroupChatInvitationElementTest {
private static final EntityBareJid mucJid = JidCreate.entityBareFromOrThrowUnchecked("darkcave@macbeth.shakespeare.lit");
@Test
public void serializeFullElement() throws XmlPullParserException, IOException, SmackParsingException {
final String expectedXml = "" +
"<x xmlns='jabber:x:conference'\n" +
" continue='true'\n" +
" jid='darkcave@macbeth.shakespeare.lit'\n" +
" password='cauldronburn'\n" +
" reason='Hey Hecate, this is the place for all good witches!'\n" +
" thread='e0ffe42b28561960c6b12b944a092794b9683a38'/>";
GroupChatInvitation invitation = new GroupChatInvitation(mucJid, "cauldronburn",
"Hey Hecate, this is the place for all good witches!", true,
"e0ffe42b28561960c6b12b944a092794b9683a38");
assertXmlSimilar(expectedXml, invitation.toXML());
GroupChatInvitation parsed = GroupChatInvitationProvider.TEST_PROVIDER.parse(TestUtils.getParser(expectedXml));
assertEquals(invitation, parsed);
}
@Test
public void serializeMinimalElementTest() throws XmlPullParserException, IOException, SmackParsingException {
final String expectedXml = "<x xmlns='jabber:x:conference' jid='darkcave@macbeth.shakespeare.lit'/>";
GroupChatInvitation invitation = new GroupChatInvitation(mucJid);
assertXmlSimilar(expectedXml, invitation.toXML());
GroupChatInvitation parsed = GroupChatInvitationProvider.TEST_PROVIDER.parse(TestUtils.getParser(expectedXml));
assertEquals(invitation, parsed);
}
}