vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-11-25 13:32:07 +01:00
Code Issues Releases Wiki Activity

Fixed documentation in PayloadItem.java and ItemsExtension.java

Browse source 
Made the formatting similar to that in Item.java
This commit is contained in:
Craig 2016-04-07 10:54:07 -04:00 committed by Florian Schmaus
parent b59356c9bf
commit 189982a9ba
2 changed files with 23 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
smack-extensions/src/main/java/org/jivesoftware/smackx/pubsub/ItemsExtension.java
View file

@ -21,14 +21,16 @@ import java.util.List;
import org.jivesoftware.smack.packet.ExtensionElement;
/**
* This class is used to for multiple purposes.
* This class is used for multiple purposes.
* <ul>
* <li>It can represent an event containing a list of items that have been published
* <li>It can represent an event containing a list of retracted (deleted) items.
* <li>It can represent a request to delete a list of items.
* <li>It can represent a request to get existing items.
* </ul>
*
* <p><b>Please note, this class is used for internal purposes, and is not required for usage of
* pubsub functionality.</b>
* pubsub functionality.</b></p>
*
* @author Robin Collier
*/
@ -69,7 +71,8 @@ public class ItemsExtension extends NodeExtension implements EmbeddedPacketExten
/**
* Construct an instance with a list representing items that have been published or deleted.
*
* <p>Valid scenarios are:
* <p>Valid scenarios are:</p>
* <ul>
* <li>Request items from node - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and an
* optional value for the <b>max_items</b> attribute.
* <li>Request to delete items - itemsType = {@link ItemsElementType#retract}, items = list of {@link Item} containing
@ -78,6 +81,7 @@ public class ItemsExtension extends NodeExtension implements EmbeddedPacketExten
* attributeValue = <code>null</code>
* <li>Items deleted event - itemsType = {@link ItemsElementType#items}, items = list of {@link RetractItem} and
* attributeValue = <code>null</code>
* </ul>
*
* @param itemsType Type of representation
* @param nodeId The node to which the items are being sent or deleted
@ -93,7 +97,8 @@ public class ItemsExtension extends NodeExtension implements EmbeddedPacketExten
/**
* Construct an instance with a list representing items that have been published or deleted.
*
* <p>Valid scenarios are:
* <p>Valid scenarios are:</p>
* <ul>
* <li>Request items from node - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and an
* optional value for the <b>max_items</b> attribute.
* <li>Request to delete items - itemsType = {@link ItemsElementType#retract}, items = list of {@link Item} containing
@ -101,7 +106,8 @@ public class ItemsExtension extends NodeExtension implements EmbeddedPacketExten
* <li>Items published event - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and
* attributeValue = <code>null</code>
* <li>Items deleted event - itemsType = {@link ItemsElementType#items}, items = list of {@link RetractItem} and
* attributeValue = <code>null</code>
* attributeValue = <code>null</code>
* </ul>
*
* @param nodeId The node to which the items are being sent or deleted
* @param items The list of {@link Item} or {@link RetractItem}

19
smack-extensions/src/main/java/org/jivesoftware/smackx/pubsub/PayloadItem.java
View file

@ -25,21 +25,25 @@ import org.jivesoftware.smackx.pubsub.provider.ItemProvider;
* pubsub node. An <tt>Item</tt> has several properties that are dependent
* on the configuration of the node to which it has been or will be published.
*
* <h1>An Item received from a node (via {@link LeafNode#getItems()} or {@link LeafNode#addItemEventListener(org.jivesoftware.smackx.pubsub.listener.ItemEventListener)}</b>
* <h3>An Item received from a node (via {@link LeafNode#getItems()} or {@link LeafNode#addItemEventListener(org.jivesoftware.smackx.pubsub.listener.ItemEventListener)}</h3>
* <ul>
* <li>Will always have an id (either user or server generated) unless node configuration has both
* {@link ConfigureForm#isPersistItems()} and {@link ConfigureForm#isDeliverPayloads()}set to false.
* {@link ConfigureForm#isPersistItems()} and {@link ConfigureForm#isDeliverPayloads()}set to false.</li>
* <li>Will have a payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set
* to true, otherwise it will be null.
* to true, otherwise it will be null.</li>
* </ul>
*
* <h1>An Item created to send to a node (via {@link LeafNode#send()} or {@link LeafNode#publish()}</b>
* <h3>An Item created to send to a node (via {@link LeafNode#send()} or {@link LeafNode#publish()}</h3>
* <ul>
* <li>The id is optional, since the server will generate one if necessary, but should be used if it is
* meaningful in the context of the node. This value must be unique within the node that it is sent to, since
* resending an item with the same id will overwrite the one that already exists if the items are persisted.
* resending an item with the same id will overwrite the one that already exists if the items are persisted.</li>
* <li>Will require payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set
* to true.
* to true.</li>
* </ul>
*
* <p>To customise the payload object being returned from the {@link #getPayload()} method, you can
* add a custom parser as explained in {@link ItemProvider}.
* add a custom parser as explained in {@link ItemProvider}.</p>
*
* @author Robin Collier
*/
@ -84,6 +88,7 @@ public class PayloadItem<E extends ExtensionElement> extends Item
* one as part of {@link Message}. If used to create an Item to publish
* (via {@link LeafNode#publish(Item)}, the server <i>may</i> return an
* error for an invalid packet.
* </p>
*
* @param itemId The id of this item.
* @param nodeId The id of the node the item was published to.