Add support for XEP-0334: Message Processing Hints

Fixes SMACK-758

documentation/extensions/index.md

@@ -87,6 +87,7 @@ Experimental Smack Extensions and currently supported XEPs of smack-experimental
 | [Internet of Things - Control](iot.md)      | [XEP-0325](http://xmpp.org/extensions/xep-0325.html) | Describes how to control devices or actuators in an XMPP-based sensor netowrk. |
 | [HTTP over XMPP transport](hoxt.md)         | [XEP-0332](http://xmpp.org/extensions/xep-0332.html) | Allows to transport HTTP communication over XMPP peer-to-peer networks. |
 | Chat Markers         			  			  | [XEP-0333](http://xmpp.org/extensions/xep-0333.html) | A solution of marking the last received, displayed and acknowledged message in a chat. |
+| Message Processing Hints                    | [XEP-0334](http://xmpp.org/extensions/xep-0334.html) | Hints to entities routing or receiving a message. |
 | JSON Containers                             | [XEP-0335](http://xmpp.org/extensions/xep-0335.html) | Encapsulation of JSON data within XMPP Stanzas. |
 | [Internet of Things - Discovery](iot.md)    | [XEP-0347](http://xmpp.org/extensions/xep-0347.html) | Describes how Things can be installed and discovered by their owners. |
 | Client State Indication                     | [XEP-0352](http://xmpp.org/extensions/xep-0352.html) | A way for the client to indicate its active/inactive state. |

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/MessageProcessingHintsManager.java

@@ -0,0 +1,71 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints;
+
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+
+import org.jivesoftware.smack.packet.Message;
+import org.jivesoftware.smackx.hints.element.MessageProcessingHintType;
+import org.jivesoftware.smackx.hints.element.NoCopyHint;
+import org.jivesoftware.smackx.hints.element.NoPermanentStoreHint;
+import org.jivesoftware.smackx.hints.element.NoStoreHint;
+import org.jivesoftware.smackx.hints.element.StoreHint;
+
+public class MessageProcessingHintsManager {
+
+    public static Set<MessageProcessingHintType> getHintsFrom(Message message) {
+        Set<MessageProcessingHintType> hints = null;
+
+        boolean noCopyHint = NoCopyHint.hasHint(message);
+        if (noCopyHint) {
+            hints = new HashSet<>(MessageProcessingHintType.values().length);
+            hints.add(MessageProcessingHintType.no_copy);
+        }
+
+        boolean noPermanentStoreHint = NoPermanentStoreHint.hasHint(message);
+        if (noPermanentStoreHint) {
+            if (hints == null) {
+                hints = new HashSet<>(MessageProcessingHintType.values().length);
+            }
+            hints.add(MessageProcessingHintType.no_permanent_store);
+        }
+
+        boolean noStoreHint = NoStoreHint.hasHint(message);
+        if (noStoreHint) {
+            if (hints == null) {
+                hints = new HashSet<>(MessageProcessingHintType.values().length);
+            }
+            hints.add(MessageProcessingHintType.no_store);
+        }
+
+        boolean storeHint = StoreHint.hasHint(message);
+        if (storeHint) {
+            if (hints == null) {
+                hints = new HashSet<>(MessageProcessingHintType.values().length);
+            }
+            hints.add(MessageProcessingHintType.store);
+        }
+
+        if (hints == null) {
+            return Collections.emptySet();
+        }
+
+        return hints;
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/element/MessageProcessingHint.java

@@ -0,0 +1,32 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.element;
+
+import org.jivesoftware.smack.packet.ExtensionElement;
+
+public abstract class MessageProcessingHint implements ExtensionElement {
+
+    public static final String NAMESPACE = "urn:xmpp:hints";
+
+    @Override
+    public final String getNamespace() {
+        return NAMESPACE;
+    }
+
+    public abstract MessageProcessingHintType getHintType();
+
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/element/MessageProcessingHintType.java

@@ -0,0 +1,27 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.element;
+
+public enum MessageProcessingHintType {
+
+    no_permanent_store,
+    no_store,
+    no_copy,
+    store,
+    ;
+
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/element/NoCopyHint.java

@@ -0,0 +1,61 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.element;
+
+import org.jivesoftware.smack.packet.Message;
+
+/**
+ * A "no copy" hint. Messages with this hint should not be copied to addresses other than the one to which it is addressed. 
+ *
+ * @see <a href="https://xmpp.org/extensions/xep-0334.html#no-copy">XEP-0344 § 4.3 No copies</a>
+ */
+public final class NoCopyHint extends MessageProcessingHint {
+
+    public static final NoCopyHint INSTANCE = new NoCopyHint();
+
+    public static final String ELEMENT = "no-copy";
+
+    private NoCopyHint() {
+    }
+
+    @Override
+    public String getElementName() {
+        return ELEMENT;
+    }
+
+    @Override
+    public String toXML() {
+        return '<' + ELEMENT + " xmlns='" + NAMESPACE + "'/>";
+    }
+
+    @Override
+    public MessageProcessingHintType getHintType() {
+        return MessageProcessingHintType.no_copy;
+    }
+
+    public static NoCopyHint from(Message message) {
+        return message.getExtension(ELEMENT, NAMESPACE);
+    }
+
+    public static boolean hasHint(Message message) {
+        return from(message) != null;
+    }
+
+    public static void set(Message message) {
+        message.addExtension(INSTANCE);
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/element/NoPermanentStoreHint.java

@@ -0,0 +1,69 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.element;
+
+import org.jivesoftware.smack.packet.Message;
+
+/**
+ * A "no permanent store" hint. Messages with this hint should not be stored in permanent stores or archives.
+ *
+ * @see <a href="https://xmpp.org/extensions/xep-0334.html#no-permanent-store">XEP-0334 § 4.1 No permanent store</a>
+ */
+public final class NoPermanentStoreHint extends MessageProcessingHint {
+
+    public static final NoPermanentStoreHint INSTANCE = new NoPermanentStoreHint();
+
+    public static final String ELEMENT = "no-permanent-store";
+
+    private NoPermanentStoreHint() {
+    }
+
+    @Override
+    public String getElementName() {
+        return ELEMENT;
+    }
+
+    @Override
+    public String toXML() {
+        return '<' + ELEMENT + " xmlns='" + NAMESPACE + "'/>";
+    }
+
+    @Override
+    public MessageProcessingHintType getHintType() {
+        return MessageProcessingHintType.no_permanent_store;
+    }
+
+    public static NoPermanentStoreHint from(Message message) {
+        return message.getExtension(ELEMENT, NAMESPACE);
+    }
+
+    public static boolean hasHint(Message message) {
+        return from(message) != null;
+    }
+
+    public static void set(Message message) {
+        if (StoreHint.hasHint(message)) {
+            // No need to set the no-permanent-store hint when a no-store hint is already set.
+            return;
+        }
+        setExplicitly(message);
+    }
+
+    public static void setExplicitly(Message message) {
+        message.addExtension(INSTANCE);
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/element/NoStoreHint.java

@@ -0,0 +1,61 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.element;
+
+import org.jivesoftware.smack.packet.Message;
+
+/**
+ * A "no store" hint. Messages with this hint should not be stored in stores or archives.
+ *
+ * <a href="https://xmpp.org/extensions/xep-0334.html#no-store">XEP-0334 § 4.2 No store</a>
+ */
+public final class NoStoreHint extends MessageProcessingHint {
+
+    public static final NoStoreHint INSTANCE = new NoStoreHint();
+
+    public static final String ELEMENT = "no-store";
+
+    private NoStoreHint() {
+    }
+
+    @Override
+    public String getElementName() {
+        return ELEMENT;
+    }
+
+    @Override
+    public String toXML() {
+        return '<' + ELEMENT + " xmlns='" + NAMESPACE + "'/>";
+    }
+
+    @Override
+    public MessageProcessingHintType getHintType() {
+        return MessageProcessingHintType.no_store;
+    }
+
+    public static NoStoreHint from(Message message) {
+        return message.getExtension(ELEMENT, NAMESPACE);
+    }
+
+    public static boolean hasHint(Message message) {
+        return from(message) != null;
+    }
+
+    public static void set(Message message) {
+        message.addExtension(INSTANCE);
+    }
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/element/StoreHint.java

@@ -0,0 +1,61 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.element;
+
+import org.jivesoftware.smack.packet.Message;
+
+/**
+ * A "store" hint. Messages with this hint should be stored in permanent stores or archives.
+ *
+ * @see <a href="https://xmpp.org/extensions/xep-0334.html#sect-idm140684698220992">XEP-0334 § 4.4 Store</a>
+ */
+public final class StoreHint extends MessageProcessingHint {
+
+    public static final StoreHint INSTANCE = new StoreHint();
+
+    public static final String ELEMENT = "no-store";
+
+    private StoreHint() {
+    }
+
+    @Override
+    public String getElementName() {
+        return ELEMENT;
+    }
+
+    @Override
+    public String toXML() {
+        return '<' + ELEMENT + " xmlns='" + NAMESPACE + "'/>";
+    }
+
+    @Override
+    public MessageProcessingHintType getHintType() {
+        return MessageProcessingHintType.store;
+    }
+
+    public static StoreHint from(Message message) {
+        return message.getExtension(ELEMENT, NAMESPACE);
+    }
+
+    public static boolean hasHint(Message message) {
+        return from(message) != null;
+    }
+
+    public static void set(Message message) {
+        message.addExtension(INSTANCE);
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.
+ */
+/**
+ * XMPP extension elements for XEP-0334: Message Processing Hints.
+ */
+package org.jivesoftware.smackx.hints.element;

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

@@ -0,0 +1,20 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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-0334: Message Processing Hints.
+  */
+package org.jivesoftware.smackx.hints;

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/provider/MessageProcessingHintProvider.java

@@ -0,0 +1,31 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.provider;
+
+import org.jivesoftware.smack.provider.ExtensionElementProvider;
+import org.jivesoftware.smackx.hints.element.MessageProcessingHint;
+import org.xmlpull.v1.XmlPullParser;
+
+public abstract class MessageProcessingHintProvider<H extends MessageProcessingHint> extends ExtensionElementProvider<H> {
+
+    @Override
+    public H parse(XmlPullParser parser, int initialDepth) throws Exception {
+        return getHint();
+    }
+
+    protected abstract H getHint();
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/provider/NoCopyHintProvider.java

@@ -0,0 +1,28 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.provider;
+
+import org.jivesoftware.smackx.hints.element.NoCopyHint;
+
+public class NoCopyHintProvider extends MessageProcessingHintProvider<NoCopyHint> {
+
+    @Override
+    protected NoCopyHint getHint() {
+        return NoCopyHint.INSTANCE;
+    }
+
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/provider/NoPermanentStoreHintProvider.java

@@ -0,0 +1,28 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.provider;
+
+import org.jivesoftware.smackx.hints.element.NoPermanentStoreHint;
+
+public class NoPermanentStoreHintProvider extends MessageProcessingHintProvider<NoPermanentStoreHint> {
+
+    @Override
+    protected NoPermanentStoreHint getHint() {
+        return NoPermanentStoreHint.INSTANCE;
+    }
+
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/provider/NoStoreHintProvider.java

@@ -0,0 +1,28 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.provider;
+
+import org.jivesoftware.smackx.hints.element.NoStoreHint;
+
+public class NoStoreHintProvider extends MessageProcessingHintProvider<NoStoreHint> {
+
+    @Override
+    protected NoStoreHint getHint() {
+        return NoStoreHint.INSTANCE;
+    }
+
+}

smack-experimental/src/main/java/org/jivesoftware/smackx/hints/provider/StoreHintProvider.java

@@ -0,0 +1,28 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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.hints.provider;
+
+import org.jivesoftware.smackx.hints.element.StoreHint;
+
+public class StoreHintProvider extends MessageProcessingHintProvider<StoreHint> {
+
+    @Override
+    protected StoreHint getHint() {
+        return StoreHint.INSTANCE;
+    }
+
+}

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

@@ -0,0 +1,20 @@
+/**
+ *
+ * Copyright 2017 Florian Schmaus
+ *
+ * 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 Provider for XEP-0334: Message Processing Hints.
+ */
+package org.jivesoftware.smackx.hints.provider;

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

@@ -233,6 +233,28 @@
       <className>org.jivesoftware.smackx.chat_markers.provider.AcknowledgedProvider</className>
     </extensionProvider>
 
+    <!-- XEP-0334: Message Processing Hints -->
+    <extensionProvider>
+      <elementName>no-copy</elementName>
+      <namespace>urn:xmpp:hints</namespace>
+      <className>org.jivesoftware.smackx.hints.provider.NoCopyHintProvider</className>
+    </extensionProvider>
+    <extensionProvider>
+      <elementName>no-permanent-store</elementName>
+      <namespace>urn:xmpp:hints</namespace>
+      <className>org.jivesoftware.smackx.hints.provider.NoPermanentStoreHintProvider</className>
+    </extensionProvider>
+    <extensionProvider>
+      <elementName>no-store</elementName>
+      <namespace>urn:xmpp:hints</namespace>
+      <className>org.jivesoftware.smackx.hints.provider.NoStoreHintProvider</className>
+    </extensionProvider>
+    <extensionProvider>
+      <elementName>store</elementName>
+      <namespace>urn:xmpp:hints</namespace>
+      <className>org.jivesoftware.smackx.hints.provider.StoreHintProvider</className>
+    </extensionProvider>
+g
     <!-- XEP-0363: HTTP File Upload -->
     <iqProvider>
       <elementName>slot</elementName>