From 56b5eae48072a05da28c35aff5fe719e057b13ad Mon Sep 17 00:00:00 2001 From: steckbrief Date: Thu, 26 May 2016 20:34:05 +0200 Subject: Fixed javadoc of PubSub Element Generation/Parsing --- .../xmpp/pubsub/PubSubPacket.java | 43 +++++++++++++++++++- .../xmpp/pubsub/PubSubPacketGenerator.java | 46 +++++++++++++++++++++- .../xmpp/pubsub/PubSubPacketParser.java | 30 ++++++++++++-- 3 files changed, 114 insertions(+), 5 deletions(-) diff --git a/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacket.java b/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacket.java index fea1383c..fe485de0 100644 --- a/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacket.java +++ b/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacket.java @@ -4,28 +4,69 @@ import de.thedevstack.conversationsplus.xml.Element; import de.thedevstack.conversationsplus.xmpp.stanzas.IqPacket; /** - * Created by tzur on 15.01.2016. + * Representation of a PubSub IQ packet as defined in XEP-0060. + *
One example: + * 
+ *   
+ *      
+ *          
+ *      
+ *   
+ *
+ * @see http://xmpp.org/extensions/xep-0060.html */ public class PubSubPacket extends IqPacket { + /** + * The namespace of pubsub. + */ public static final String NAMESPACE = "http://jabber.org/protocol/pubsub"; + /** + * The name of the root element. + */ public static final String ELEMENT_NAME = "pubsub"; + /** + * The PubSub element - everything which is added to this packet is a child of this element. + */ private Element pubSubElement; + /** + * Instantiate the PubSubPacket for the given type. + * @param type the IqPacket.TYPE + */ public PubSubPacket(IqPacket.TYPE type) { super(type); this.pubSubElement = super.addChild(PubSubPacket.ELEMENT_NAME, PubSubPacket.NAMESPACE); } + /** + * Adds an element to the PubSub element instead of the IqPacket. + * @param child the children to be added + * @return the added children + */ @Override public Element addChild(Element child) { return this.pubSubElement.addChild(child); } + /** + * Adds an element to the PubSub element instead of the IqPacket. + * @param name name of the children to be added + * @return the added children + */ @Override public Element addChild(String name) { return this.pubSubElement.addChild(name); } + /** + * Adds an element to the PubSub element instead of the IqPacket. + * @param name name of the children to be added + * @param xmlns namespace of the children to be added + * @return the added children + */ @Override public Element addChild(String name, String xmlns) { return this.pubSubElement.addChild(name, xmlns); diff --git a/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketGenerator.java b/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketGenerator.java index 1eb44b5e..a93c37aa 100644 --- a/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketGenerator.java +++ b/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketGenerator.java @@ -4,10 +4,32 @@ import de.thedevstack.conversationsplus.xml.Element; import de.thedevstack.conversationsplus.xmpp.stanzas.IqPacket; /** - * Created by tzur on 15.01.2016. + * Generates the IQ packets for Pubsub Subscription as defined in XEP-0060. + * @see http://xmpp.org/extensions/xep-0060.html */ public final class PubSubPacketGenerator { + /** + * Generates a pubsub publish packet. + * The attributes from and id are not set in here - this is added while sending the packet. + * 
+     * 
+     *   
+     *     
+     *       
+     *         ...
+     *       
+     *     
+     *   
+     * 
+     *
+ * @param nodeName the name of the publish node + * @param item the item element + * @return the generated PubSubPacket + */ public static PubSubPacket generatePubSubPublishPacket(String nodeName, Element item) { final PubSubPacket pubsub = new PubSubPacket(IqPacket.TYPE.SET); final Element publish = pubsub.addChild("publish"); @@ -16,6 +38,25 @@ public final class PubSubPacketGenerator { return pubsub; } + /** + * Generates a pubsub retrieve packet. + * The attributes from and id are not set in here - this is added while sending the packet. + * 
+     * 
+     *   
+     *     
+     *       
+     *     
+     *   
+     * 
+     *
+ * @param nodeName + * @param item + * @return + */ public static PubSubPacket generatePubSubRetrievePacket(String nodeName, Element item) { final PubSubPacket pubsub = new PubSubPacket(IqPacket.TYPE.GET); final Element items = pubsub.addChild("items"); @@ -26,6 +67,9 @@ public final class PubSubPacketGenerator { return pubsub; } + /** + * Utility class - avoid instantiation + */ private PubSubPacketGenerator() { // Avoid instantiation } diff --git a/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketParser.java b/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketParser.java index 682803c4..0f803b56 100644 --- a/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketParser.java +++ b/src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketParser.java @@ -4,16 +4,28 @@ import de.thedevstack.conversationsplus.xml.Element; import de.thedevstack.conversationsplus.xmpp.stanzas.IqPacket; /** - * Created by tzur on 15.01.2016. + * Parses the IQ Packets for handling pubsub + * as defined in XEP-0060. + * @see http://xmpp.org/extensions/xep-0060.html */ -public class PubSubPacketParser { +public final class PubSubPacketParser { + /** + * Finds the pubsub element within an IQ packet. + * @param packet the retrieved IQ packet + * @return the {@value PubSubPacket#ELEMENT_NAME} Element or null if the IqPacket is null or the IQ packet does not contain an pubsub element. + */ public static Element findPubSubPacket(IqPacket packet){ if (null == packet) { return null; } - return packet.findChild("pubsub", "http://jabber.org/protocol/pubsub"); + return packet.findChild(PubSubPacket.ELEMENT_NAME, PubSubPacket.NAMESPACE); } + /** + * Finds the "items" element within an pubSubPacket element. + * @param pubSubPacket the pubSubPacket element + * @return the items Element or null if the pubSubPacket is null or the pubSubPacket does not contain an items element. + */ public static Element findItemsFromPubSubElement(Element pubSubPacket) { if (null == pubSubPacket) { return null; @@ -21,7 +33,19 @@ public class PubSubPacketParser { return pubSubPacket.findChild("items"); } + /** + * Finds the "items" element within an pubSubPacket element. + * @param packet the IqPacket element + * @return the items Element or null if the IqPacket is null or the IQ packet does not contain an pubsub element with an items element. + */ public static Element findItems(IqPacket packet) { return PubSubPacketParser.findItemsFromPubSubElement(PubSubPacketParser.findPubSubPacket(packet)); } + + /** + * Utility class - avoid instantiation + */ + private PubSubPacketParser() { + // Avoid instantiation + } } -- cgit v1.2.3