PacketExtension.from(Packet), deprecate getFrom()

add 'from(Packet)' to DataForm

documentation/developer/stanzas.md

@@ -0,0 +1,25 @@
+Developer Documentation: Stanzas and PacketExtensions
+
+PacketExtension
+===============
+
+The static `from(Packet)` Method
+--------------------------------
+
+Every PacketExtension class must have a static `from()` method that retrieves that extension for a given Stanza (if any).
+
+Sample Code
+
+```java
+public static RSMSet from(Packet) {
+  return packet.getExtension(ELEMENT, NAMESPACE);
+}
+```
+
+Sometimes certain PacketExtension's are only found in one stanza type, in that case, specify the parameter type. For example `public static CarbonExtension getFrom(Message)`.
+
+
+
+
+
+

smack-experimental/src/main/java/org/jivesoftware/smackx/carbons/packet/CarbonExtension.java

@@ -95,8 +95,24 @@ public class CarbonExtension implements PacketExtension {
      * @param msg Message object to check for carbons
      *
      * @return a Carbon if available, null otherwise.
+     * @deprecated use {@link #from(Message)} instead
      */
+    @Deprecated
     public static CarbonExtension getFrom(Message msg) {
+        return from(msg);
+    }
+
+    /**
+     * Obtain a Carbon from a message, if available.
+     * <p>
+     * Only {@link Message} instances can contain a Carbon extensions.
+     * </p>
+     *
+     * @param msg Message object to check for carbons
+     *
+     * @return a Carbon if available, null otherwise.
+     */
+    public static CarbonExtension from(Message msg) {
         CarbonExtension cc = msg.getExtension(Direction.received.name(), NAMESPACE);
         if (cc == null)
             cc = msg.getExtension(Direction.sent.name(), NAMESPACE);

smack-extensions/src/main/java/org/jivesoftware/smackx/caps/EntityCapsManager.java

@@ -594,7 +594,7 @@ public class EntityCapsManager extends Manager {
         if (md == null)
             return null;
 
-        DataForm extendedInfo = (DataForm) discoverInfo.getExtension(DataForm.ELEMENT, DataForm.NAMESPACE);
+        DataForm extendedInfo =  DataForm.from(discoverInfo);
 
         // 1. Initialize an empty string S ('sb' in this method).
         StringBuilder sb = new StringBuilder(); // Use StringBuilder as we don't

smack-extensions/src/main/java/org/jivesoftware/smackx/delay/packet/DelayInformation.java

@@ -107,7 +107,23 @@ public class DelayInformation implements PacketExtension {
         return xml;
     }
 
+    /**
+     * 
+     * @param packet
+     * @return the DelayInformation or null
+     * @deprecated use {@link #from(Packet)} instead
+     */
+    @Deprecated
     public static DelayInformation getFrom(Packet packet) {
+        return from(packet);
+    }
+
+    /**
+     * 
+     * @param packet
+     * @return the DelayInformation or null
+     */
+    public static DelayInformation from(Packet packet) {
         return packet.getExtension(ELEMENT, NAMESPACE);
     }
 }

smack-extensions/src/main/java/org/jivesoftware/smackx/forward/Forwarded.java

@@ -73,7 +73,23 @@ public class Forwarded implements PacketExtension {
         return xml;
     }
 
+    /**
+     * 
+     * @param packet
+     * @return the Forwarded extension or null
+     * @deprecated use {@link #from(Packet)} instead
+     */
+    @Deprecated
     public static Forwarded getFrom(Packet packet) {
+        return from(packet);
+    }
+
+    /**
+     * 
+     * @param packet
+     * @return the Forwarded extension or null
+     */
+    public static Forwarded from(Packet packet) {
         return packet.getExtension(ELEMENT, NAMESPACE);
     }
 

smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/GroupChatInvitation.java

@@ -105,7 +105,23 @@ public class GroupChatInvitation implements PacketExtension {
         return xml;
     }
 
+    /**
+     * 
+     * @param packet
+     * @return the GroupChatInvitation or null
+     * @deprecated use {@link #from(Packet)} instead
+     */
+    @Deprecated
     public static GroupChatInvitation getFrom(Packet packet) {
+        return from(packet);
+    }
+
+    /**
+     * 
+     * @param packet
+     * @return the GroupChatInvitation or null
+     */
+    public static GroupChatInvitation from(Packet packet) {
         return packet.getExtension(ELEMENT, NAMESPACE);
     }
 

smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCInitialPresence.java

@@ -108,8 +108,20 @@ public class MUCInitialPresence implements PacketExtension {
      *
      * @param packet
      * @return the MUCInitialPresence PacketExtension or {@code null}
+     * @deprecated use {@link #from(Packet)} instead
      */
+    @Deprecated
     public static MUCInitialPresence getFrom(Packet packet) {
+        return from(packet);
+    }
+
+    /**
+     * Retrieve the MUCInitialPresence PacketExtension from packet, if any.
+     *
+     * @param packet
+     * @return the MUCInitialPresence PacketExtension or {@code null}
+     */
+    public static MUCInitialPresence from(Packet packet) {
         return packet.getExtension(ELEMENT, NAMESPACE);
     }
 

smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCUser.java

@@ -206,8 +206,20 @@ public class MUCUser implements PacketExtension {
      *
      * @param packet
      * @return the MUCUser PacketExtension or {@code null}
+     * @deprecated use {@link #from(Packet)} instead
      */
+    @Deprecated
     public static MUCUser getFrom(Packet packet) {
+        return from(packet);
+    }
+
+    /**
+     * Retrieve the MUCUser PacketExtension from packet, if any.
+     *
+     * @param packet
+     * @return the MUCUser PacketExtension or {@code null}
+     */
+    public static MUCUser from(Packet packet) {
         return packet.getExtension(ELEMENT, NAMESPACE);
     }
 

smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceipt.java

@@ -69,9 +69,21 @@ public class DeliveryReceipt implements PacketExtension
      *
      * @param p the packet
      * @return the {@link DeliveryReceipt} extension or {@code null}
+     * @deprecated use {@link #from(Packet)} instead
      */
+    @Deprecated
     public static DeliveryReceipt getFrom(Packet p) {
-        return p.getExtension(ELEMENT, NAMESPACE);
+        return from(p);
+    }
+
+    /**
+     * Get the {@link DeliveryReceipt} extension of the packet, if any.
+     *
+     * @param packet the packet
+     * @return the {@link DeliveryReceipt} extension or {@code null}
+     */
+    public static DeliveryReceipt from(Packet packet) {
+        return packet.getExtension(ELEMENT, NAMESPACE);
     }
 
     /**

smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceiptRequest.java

@@ -51,9 +51,21 @@ public class DeliveryReceiptRequest implements PacketExtension
      *
      * @param p the packet
      * @return the {@link DeliveryReceiptRequest} extension or {@code null}
+     * @deprecated use {@link #from(Packet)} instead
      */
+    @Deprecated
     public static DeliveryReceiptRequest getFrom(Packet p) {
-        return p.getExtension(ELEMENT, DeliveryReceipt.NAMESPACE);
+        return from(p);
+    }
+
+    /**
+     * Get the {@link DeliveryReceiptRequest} extension of the packet, if any.
+     *
+     * @param packet the packet
+     * @return the {@link DeliveryReceiptRequest} extension or {@code null}
+     */
+    public static DeliveryReceiptRequest from(Packet packet) {
+        return packet.getExtension(ELEMENT, DeliveryReceipt.NAMESPACE);
     }
 
     /**

smack-extensions/src/main/java/org/jivesoftware/smackx/rsm/packet/RSMSet.java

@@ -16,6 +16,7 @@
  */
 package org.jivesoftware.smackx.rsm.packet;
 
+import org.jivesoftware.smack.packet.Packet;
 import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smack.util.XmlStringBuilder;
 
@@ -142,4 +143,7 @@ public class RSMSet implements PacketExtension {
         return xml;
     }
 
+    public static RSMSet from(Packet packet) {
+        return (RSMSet) packet.getExtension(ELEMENT, NAMESPACE);
+    }
 }

smack-extensions/src/main/java/org/jivesoftware/smackx/search/ReportedData.java

@@ -17,7 +17,6 @@
 package org.jivesoftware.smackx.search;
 
 import org.jivesoftware.smack.packet.Packet;
-import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smackx.xdata.FormField;
 import org.jivesoftware.smackx.xdata.packet.DataForm;
 import org.jivesoftware.smackx.xdata.packet.DataForm.Item;
@@ -46,10 +45,8 @@ public class ReportedData {
      */
     public static ReportedData getReportedDataFrom(Packet packet) {
         // Check if the packet includes the DataForm extension
-        PacketExtension packetExtension = packet.getExtension("x","jabber:x:data");
+        DataForm dataForm = DataForm.from(packet);
-        if (packetExtension != null) {
+        if (dataForm != null) {
-            // Check if the existing DataForm is a result of a search
-            DataForm dataForm = (DataForm) packetExtension;
             if (dataForm.getReportedData() != null)
                 return new ReportedData(dataForm);
         }

smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/Form.java

@@ -22,7 +22,6 @@ import java.util.List;
 import java.util.StringTokenizer;
 
 import org.jivesoftware.smack.packet.Packet;
-import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smackx.xdata.packet.DataForm;
 
 /**
@@ -61,10 +60,8 @@ public class Form {
      */
     public static Form getFormFrom(Packet packet) {
         // Check if the packet includes the DataForm extension
-        PacketExtension packetExtension = packet.getExtension("x","jabber:x:data");
+        DataForm dataForm = DataForm.from(packet);
-        if (packetExtension != null) {
+        if (dataForm != null) {
-            // Check if the existing DataForm is not a result of a search
-            DataForm dataForm = (DataForm) packetExtension;
             if (dataForm.getReportedData() == null)
                 return new Form(dataForm);
         }

smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/packet/DataForm.java

@@ -18,6 +18,7 @@
 package org.jivesoftware.smackx.xdata.packet;
 
 import org.jivesoftware.smack.packet.Element;
+import org.jivesoftware.smack.packet.Packet;
 import org.jivesoftware.smack.packet.PacketExtension;
 import org.jivesoftware.smack.util.XmlStringBuilder;
 import org.jivesoftware.smackx.xdata.FormField;
@@ -249,6 +250,15 @@ public class DataForm implements PacketExtension {
         return buf;
     }
 
+    /**
+     * 
+     * @param packet
+     * @return the DataForm or null
+     */
+    public static DataForm from(Packet packet) {
+        return (DataForm) packet.getExtension(ELEMENT, NAMESPACE);
+    }
+
     /**
      * 
      * Represents the fields that will be returned from a search. This information is useful when