From 58e430af42ede00c0dc0f9330737b5f2fa4991a3 Mon Sep 17 00:00:00 2001 From: Florian Schmaus Date: Tue, 16 Sep 2014 22:14:10 +0200 Subject: [PATCH] PacketExtension.from(Packet), deprecate getFrom() add 'from(Packet)' to DataForm --- documentation/developer/stanzas.md | 25 +++++++++++++++++++ .../carbons/packet/CarbonExtension.java | 16 ++++++++++++ .../smackx/caps/EntityCapsManager.java | 2 +- .../smackx/delay/packet/DelayInformation.java | 16 ++++++++++++ .../smackx/forward/Forwarded.java | 16 ++++++++++++ .../muc/packet/GroupChatInvitation.java | 16 ++++++++++++ .../smackx/muc/packet/MUCInitialPresence.java | 12 +++++++++ .../smackx/muc/packet/MUCUser.java | 12 +++++++++ .../smackx/receipts/DeliveryReceipt.java | 14 ++++++++++- .../receipts/DeliveryReceiptRequest.java | 14 ++++++++++- .../smackx/rsm/packet/RSMSet.java | 4 +++ .../smackx/search/ReportedData.java | 7 ++---- .../org/jivesoftware/smackx/xdata/Form.java | 7 ++---- .../smackx/xdata/packet/DataForm.java | 10 ++++++++ 14 files changed, 158 insertions(+), 13 deletions(-) create mode 100644 documentation/developer/stanzas.md diff --git a/documentation/developer/stanzas.md b/documentation/developer/stanzas.md new file mode 100644 index 000000000..9f1eea6be --- /dev/null +++ b/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)`. + + + + + + diff --git a/smack-experimental/src/main/java/org/jivesoftware/smackx/carbons/packet/CarbonExtension.java b/smack-experimental/src/main/java/org/jivesoftware/smackx/carbons/packet/CarbonExtension.java index 9590367c8..1864194c2 100644 --- a/smack-experimental/src/main/java/org/jivesoftware/smackx/carbons/packet/CarbonExtension.java +++ b/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. + *

+ * Only {@link Message} instances can contain a Carbon extensions. + *

+ * + * @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); diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/caps/EntityCapsManager.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/caps/EntityCapsManager.java index 09bbabae6..ab1a10d87 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/caps/EntityCapsManager.java +++ b/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 diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/delay/packet/DelayInformation.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/delay/packet/DelayInformation.java index c27c4fbb5..1b3309953 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/delay/packet/DelayInformation.java +++ b/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); } } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/forward/Forwarded.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/forward/Forwarded.java index f34c0a306..4e3570dcf 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/forward/Forwarded.java +++ b/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); } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/GroupChatInvitation.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/GroupChatInvitation.java index 156507c67..5e74d4f30 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/GroupChatInvitation.java +++ b/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); } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCInitialPresence.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCInitialPresence.java index 260c26ebc..5053bf884 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCInitialPresence.java +++ b/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); } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCUser.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCUser.java index f5ed8fe85..6f46253ef 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/muc/packet/MUCUser.java +++ b/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); } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceipt.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceipt.java index febbde7af..1289966b1 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceipt.java +++ b/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); } /** diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceiptRequest.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceiptRequest.java index 2831ccd2f..dd1953129 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/receipts/DeliveryReceiptRequest.java +++ b/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); } /** diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/rsm/packet/RSMSet.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/rsm/packet/RSMSet.java index 8c9f88c18..532fa3b42 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/rsm/packet/RSMSet.java +++ b/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); + } } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/search/ReportedData.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/search/ReportedData.java index dbb553f36..95451fad6 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/search/ReportedData.java +++ b/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"); - if (packetExtension != null) { - // Check if the existing DataForm is a result of a search - DataForm dataForm = (DataForm) packetExtension; + DataForm dataForm = DataForm.from(packet); + if (dataForm != null) { if (dataForm.getReportedData() != null) return new ReportedData(dataForm); } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/Form.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/Form.java index 06ec091b6..2c45fec80 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/Form.java +++ b/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"); - if (packetExtension != null) { - // Check if the existing DataForm is not a result of a search - DataForm dataForm = (DataForm) packetExtension; + DataForm dataForm = DataForm.from(packet); + if (dataForm != null) { if (dataForm.getReportedData() == null) return new Form(dataForm); } diff --git a/smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/packet/DataForm.java b/smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/packet/DataForm.java index d39cbf656..23d9e52ce 100644 --- a/smack-extensions/src/main/java/org/jivesoftware/smackx/xdata/packet/DataForm.java +++ b/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