Merge pull request #368 from vanitasvitae/fallbackIndication

XEP-0428: Fallback Indication

documentation/extensions/index.md

@@ -122,6 +122,7 @@ Experimental Smack Extensions and currently supported XEPs of smack-experimental
 | [Message Markup](messagemarkup.md)                        | [XEP-0394](https://xmpp.org/extensions/xep-0394.html)  | 0.1.0     | Style message bodies while keeping body and markup information separated. |
 | DNS Queries over XMPP (DoX)                               | [XEP-0418](https://xmpp.org/extensions/xep-0418.html)  | 0.1.0     | Send DNS queries and responses over XMPP. |
 | Message Fastening                                         | [XEP-0422](https://xmpp.org/extensions/xep-0422.html)  | 0.1.1     | Mark payloads on a message to be logistically fastened to a previous message. |
+| Fallback Indication                                       | [XEP-0428](https://xmpp.org/extensions/xep-0428.html)  | 0.1.0     | Declare body elements of a message as ignorable fallback for naive legacy clients. |
 
 Unofficial XMPP Extensions
 --------------------------

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/FallbackIndicationListener.java

@@ -0,0 +1,33 @@
+/**
+ *
+ * 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.fallback_indication;
+
+import org.jivesoftware.smack.packet.Message;
+import org.jivesoftware.smackx.fallback_indication.element.FallbackIndicationElement;
+
+public interface FallbackIndicationListener {
+
+    /**
+     * Listener method that gets called when a {@link Message} containing a {@link FallbackIndicationElement} is received.
+     *
+     * @param message message
+     * @param indicator Fallback Indication
+     * @param fallbackBody body that is marked as fallback
+     */
+    void onFallbackIndicationReceived(Message message, FallbackIndicationElement indicator, String fallbackBody);
+
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/FallbackIndicationManager.java

@@ -0,0 +1,174 @@
+/**
+ *
+ * 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.fallback_indication;
+
+import java.util.Map;
+import java.util.Set;
+import java.util.WeakHashMap;
+import java.util.concurrent.CopyOnWriteArraySet;
+
+import org.jivesoftware.smack.AsyncButOrdered;
+import org.jivesoftware.smack.ConnectionCreationListener;
+import org.jivesoftware.smack.Manager;
+import org.jivesoftware.smack.SmackException;
+import org.jivesoftware.smack.StanzaListener;
+import org.jivesoftware.smack.XMPPConnection;
+import org.jivesoftware.smack.XMPPConnectionRegistry;
+import org.jivesoftware.smack.XMPPException;
+import org.jivesoftware.smack.filter.AndFilter;
+import org.jivesoftware.smack.filter.StanzaExtensionFilter;
+import org.jivesoftware.smack.filter.StanzaFilter;
+import org.jivesoftware.smack.filter.StanzaTypeFilter;
+import org.jivesoftware.smack.packet.Message;
+import org.jivesoftware.smack.packet.MessageBuilder;
+import org.jivesoftware.smack.packet.Stanza;
+import org.jivesoftware.smackx.disco.ServiceDiscoveryManager;
+import org.jivesoftware.smackx.fallback_indication.element.FallbackIndicationElement;
+
+import org.jxmpp.jid.BareJid;
+import org.jxmpp.jid.EntityBareJid;
+
+/**
+ * Smacks API for XEP-0428: Fallback Indication.
+ * In some scenarios it might make sense to mark the body of a message as fallback for legacy clients.
+ * Examples are encryption mechanisms where the sender might include a hint for legacy clients stating that the
+ * body (eg. "This message is encrypted") should be ignored.
+ *
+ * @see <a href="https://xmpp.org/extensions/xep-0428.html">XEP-0428: Fallback Indication</a>
+ */
+public final class FallbackIndicationManager extends Manager {
+
+    private static final Map<XMPPConnection, FallbackIndicationManager> INSTANCES = new WeakHashMap<>();
+
+    static {
+        XMPPConnectionRegistry.addConnectionCreationListener(new ConnectionCreationListener() {
+            @Override
+            public void connectionCreated(XMPPConnection connection) {
+                getInstanceFor(connection);
+            }
+        });
+    }
+
+    private final Set<FallbackIndicationListener> listeners = new CopyOnWriteArraySet<>();
+    private final AsyncButOrdered<BareJid> asyncButOrdered = new AsyncButOrdered<>();
+    private final StanzaFilter fallbackIndicationElementFilter = new AndFilter(StanzaTypeFilter.MESSAGE,
+            new StanzaExtensionFilter(FallbackIndicationElement.ELEMENT, FallbackIndicationElement.NAMESPACE));
+
+    private final StanzaListener fallbackIndicationElementListener = new StanzaListener() {
+        @Override
+        public void processStanza(Stanza packet) {
+            Message message = (Message) packet;
+            FallbackIndicationElement indicator = FallbackIndicationElement.fromMessage(message);
+            String body = message.getBody();
+            asyncButOrdered.performAsyncButOrdered(message.getFrom().asBareJid(), () -> {
+                for (FallbackIndicationListener l : listeners) {
+                    l.onFallbackIndicationReceived(message, indicator, body);
+                }
+            });
+        }
+    };
+
+    private FallbackIndicationManager(XMPPConnection connection) {
+        super(connection);
+        connection.addAsyncStanzaListener(fallbackIndicationElementListener, fallbackIndicationElementFilter);
+        ServiceDiscoveryManager.getInstanceFor(connection).addFeature(FallbackIndicationElement.NAMESPACE);
+    }
+
+    public static synchronized FallbackIndicationManager getInstanceFor(XMPPConnection connection) {
+        FallbackIndicationManager manager = INSTANCES.get(connection);
+        if (manager == null) {
+            manager = new FallbackIndicationManager(connection);
+            INSTANCES.put(connection, manager);
+        }
+        return manager;
+    }
+
+    /**
+     * Determine, whether or not a user supports Fallback Indications.
+     *
+     * @param jid BareJid of the user.
+     * @return feature support
+     *
+     * @throws XMPPException.XMPPErrorException if a protocol level error happens
+     * @throws SmackException.NotConnectedException if the connection is not connected
+     * @throws InterruptedException if the thread is being interrupted
+     * @throws SmackException.NoResponseException if the server doesn't send a response in time
+     */
+    public boolean userSupportsFallbackIndications(EntityBareJid jid)
+            throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException,
+            SmackException.NoResponseException {
+        return ServiceDiscoveryManager.getInstanceFor(connection())
+                .supportsFeature(jid, FallbackIndicationElement.NAMESPACE);
+    }
+
+    /**
+     * Determine, whether or not the server supports Fallback Indications.
+     *
+     * @return server side feature support
+     *
+     * @throws XMPPException.XMPPErrorException if a protocol level error happens
+     * @throws SmackException.NotConnectedException if the connection is not connected
+     * @throws InterruptedException if the thread is being interrupted
+     * @throws SmackException.NoResponseException if the server doesn't send a response in time
+     */
+    public boolean serverSupportsFallbackIndications()
+            throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException,
+            SmackException.NoResponseException {
+        return ServiceDiscoveryManager.getInstanceFor(connection())
+                .serverSupportsFeature(FallbackIndicationElement.NAMESPACE);
+    }
+
+    /**
+     * Set the body of the message to the provided fallback message and add a {@link FallbackIndicationElement}.
+     *
+     * @param messageBuilder message builder
+     * @param fallbackMessageBody fallback message body
+     * @return builder with set body and added fallback element
+     */
+    public MessageBuilder addFallbackIndicationWithBody(MessageBuilder messageBuilder, String fallbackMessageBody) {
+        return addFallbackIndication(messageBuilder).setBody(fallbackMessageBody);
+    }
+
+    /**
+     * Add a {@link FallbackIndicationElement} to the provided message builder.
+     *
+     * @param messageBuilder message builder
+     * @return message builder with added fallback element
+     */
+    public MessageBuilder addFallbackIndication(MessageBuilder messageBuilder) {
+        return messageBuilder.addExtension(new FallbackIndicationElement());
+    }
+
+    /**
+     * Register a {@link FallbackIndicationListener} that gets notified whenever a message that contains a
+     * {@link FallbackIndicationElement} is received.
+     *
+     * @param listener listener to be registered.
+     */
+    public synchronized void addFallbackIndicationListener(FallbackIndicationListener listener) {
+        listeners.add(listener);
+    }
+
+    /**
+     * Unregister a {@link FallbackIndicationListener}.
+     *
+     * @param listener listener to be unregistered.
+     */
+    public synchronized void removeFallbackIndicationListener(FallbackIndicationListener listener) {
+        listeners.remove(listener);
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/element/FallbackIndicationElement.java

@@ -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.fallback_indication.element;
+
+import org.jivesoftware.smack.packet.ExtensionElement;
+import org.jivesoftware.smack.packet.Message;
+import org.jivesoftware.smack.packet.XmlEnvironment;
+import org.jivesoftware.smack.util.XmlStringBuilder;
+
+public class FallbackIndicationElement implements ExtensionElement {
+
+    public static final String NAMESPACE = "urn:xmpp:fallback:0";
+    public static final String ELEMENT = "fallback";
+
+    public static final FallbackIndicationElement INSTANCE = new FallbackIndicationElement();
+
+    @Override
+    public String getNamespace() {
+        return NAMESPACE;
+    }
+
+    @Override
+    public String getElementName() {
+        return ELEMENT;
+    }
+
+    @Override
+    public XmlStringBuilder toXML(XmlEnvironment xmlEnvironment) {
+        return new XmlStringBuilder(this).closeEmptyElement();
+    }
+
+    public static boolean hasFallbackIndication(Message message) {
+        return message.hasExtension(ELEMENT, NAMESPACE);
+    }
+
+    public static FallbackIndicationElement fromMessage(Message message) {
+        return message.getExtension(FallbackIndicationElement.class);
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/element/package-info.java

@@ -0,0 +1,22 @@
+/**
+ *
+ * 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.
+ */
+
+/**
+ * Smack's API for XEP-0428: Fallback Indication.
+ * Extension Elements.
+ */
+package org.jivesoftware.smackx.fallback_indication.element;

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/package-info.java

@@ -0,0 +1,21 @@
+/**
+ *
+ * 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.
+ */
+
+/**
+ * Smack's API for XEP-0428: Fallback Indication.
+ */
+package org.jivesoftware.smackx.fallback_indication;

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/provider/FallbackIndicationElementProvider.java

@@ -0,0 +1,35 @@
+/**
+ *
+ * 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.fallback_indication.provider;
+
+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.xml.XmlPullParser;
+import org.jivesoftware.smack.xml.XmlPullParserException;
+import org.jivesoftware.smackx.fallback_indication.element.FallbackIndicationElement;
+
+public class FallbackIndicationElementProvider extends ExtensionElementProvider<FallbackIndicationElement> {
+
+    @Override
+    public FallbackIndicationElement parse(XmlPullParser parser, int initialDepth, XmlEnvironment xmlEnvironment)
+            throws XmlPullParserException, IOException, SmackParsingException {
+        return FallbackIndicationElement.INSTANCE;
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/fallback_indication/provider/package-info.java

@@ -0,0 +1,22 @@
+/**
+ *
+ * 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.
+ */
+
+/**
+ * Smack's API for XEP-0428: Fallback Indication.
+ * Element Providers.
+ */
+package org.jivesoftware.smackx.fallback_indication.provider;

smack-experimental/src/main/resources/org.jivesoftware.smack.experimental/experimental.providers

@@ -299,6 +299,13 @@
       <className>org.jivesoftware.smackx.message_fastening.provider.FasteningElementProvider</className>
     </extensionProvider>
 
+    <!-- XEP-0428: Fallback Indication -->
+    <extensionProvider>
+      <elementName>fallback</elementName>
+      <namespace>urn:xmpp:fallback:0</namespace>
+      <className>org.jivesoftware.smackx.fallback_indication.provider.FallbackIndicationElementProvider</className>
+    </extensionProvider>
+
     <!-- XEP-xxxx: Multi-User Chat Light -->
     <iqProvider>
         <elementName>query</elementName>

smack-experimental/src/test/java/org/jivesoftware/smackx/fallback_indication/FallbackIndicationTest.java

@@ -0,0 +1,42 @@
+/**
+ *
+ * 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.fallback_indication;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import org.jivesoftware.smack.packet.Message;
+import org.jivesoftware.smack.packet.MessageBuilder;
+
+import org.jivesoftware.smackx.fallback_indication.element.FallbackIndicationElement;
+
+import org.junit.jupiter.api.Test;
+
+public class FallbackIndicationTest {
+
+    @Test
+    public void testFallbackIndicationElementFromMessageTest() {
+        Message messageWithoutFallback = MessageBuilder.buildMessage()
+                        .build();
+        assertNull(FallbackIndicationElement.fromMessage(messageWithoutFallback));
+
+        Message messageWithFallback = MessageBuilder.buildMessage()
+                        .addExtension(new FallbackIndicationElement())
+                        .build();
+        assertNotNull(FallbackIndicationElement.fromMessage(messageWithFallback));
+    }
+}