Merge remote-tracking branch 'remotes/origin/trz/rename' into trz/rebase

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 961277cb..31186191 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 eu.siacs.conversations.xml.Element;
 import eu.siacs.conversations.xmpp.stanzas.IqPacket;
 
 /**
- * Created by tzur on 15.01.2016.
+ * Representation of a PubSub IQ packet as defined in XEP-0060.
+ * <br>One example:
+ * <pre>
+ *   <iq type='get'
+ *       from='romeo@montague.lit'
+ *       to='pubsub.shakespeare.lit'
+ *       id='items1'>
+ *      <pubsub xmlns='http://jabber.org/protocol/pubsub'>
+ *          <items node='urn:xmpp:pubsub:subscription'/>
+ *      </pubsub>
+ *   </iq>
+ * </pre>
+ * @see <a href="http://xmpp.org/extensions/xep-0330.html">http://xmpp.org/extensions/xep-0060.html</a>
  */
 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 398ec032..f72bf777 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 eu.siacs.conversations.xml.Element;
 import eu.siacs.conversations.xmpp.stanzas.IqPacket;
 
 /**
- * Created by tzur on 15.01.2016.
+ * Generates the IQ packets for Pubsub Subscription as defined in XEP-0060.
+ * @see <a href="http://xmpp.org/extensions/xep-0060.html">http://xmpp.org/extensions/xep-0060.html</a>
  */
 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.
+     * <pre>
+     * <iq type='set'
+     *     from='hamlet@denmark.lit/blogbot'
+     *     to='pubsub.shakespeare.lit'
+     *     id='publish1'>
+     *   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
+     *     <publish node='princely_musings'>
+     *       <item id='bnd81g37d61f49fgn581'>
+     *         ...
+     *       </item>
+     *     </publish>
+     *   </pubsub>
+     * </iq>
+     * </pre>
+     * @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.
+     * <pre>
+     * <iq type='get'
+     *     from='romeo@montague.lit/home'
+     *     to='juliet@capulet.lit'
+     *     id='retrieve1'>
+     *   <pubsub xmlns='http://jabber.org/protocol/pubsub'>
+     *     <items node='urn:xmpp:avatar:data'>
+     *       <item id='111f4b3c50d7b0df729d299bc6f8e9ef9066971f'/>
+     *     </items>
+     *   </pubsub>
+     * </iq>
+     * </pre>
+     * @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 394fb5b2..c8df0d5e 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 eu.siacs.conversations.xml.Element;
 import eu.siacs.conversations.xmpp.stanzas.IqPacket;
 
 /**
- * Created by tzur on 15.01.2016.
+ * Parses the IQ Packets for handling pubsub
+ * as defined in XEP-0060.
+ * @see <a href="http://xmpp.org/extensions/xep-0060.html">http://xmpp.org/extensions/xep-0060.html</a>
  */
-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 <code>null</code> 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 <code>null</code> 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 <code>null</code> 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
+    }
 }