aboutsummaryrefslogtreecommitdiffstats
path: root/src/main
diff options
context:
space:
mode:
authorsteckbrief <steckbrief@chefmail.de>2016-05-26 20:34:05 +0200
committersteckbrief <steckbrief@chefmail.de>2016-05-26 20:34:05 +0200
commit56b5eae48072a05da28c35aff5fe719e057b13ad (patch)
treef394420a6ea9f450841603e43b9075c36837ca59 /src/main
parent10e607ac51dcc42fa1b54bacb698beed43750de7 (diff)
Fixed javadoc of PubSub Element Generation/Parsing
Diffstat (limited to 'src/main')
-rw-r--r--src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacket.java43
-rw-r--r--src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketGenerator.java46
-rw-r--r--src/main/java/de/thedevstack/conversationsplus/xmpp/pubsub/PubSubPacketParser.java30
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.
+ * <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 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 <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 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 <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
+ }
}