1 /** 2 * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); 3 * you may not use this file except in compliance with the License. 4 * You may obtain a copy of the License at 5 * 6 * http://www.apache.org/licenses/LICENSE-2.0 7 * 8 * Unless required by applicable law or agreed to in writing, software 9 * distributed under the License is distributed on an "AS IS" BASIS, 10 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11 * See the License for the specific language governing permissions and 12 * limitations under the License. 13 */ 14 package org.jivesoftware.smackx.pubsub; 15 16 import org.jivesoftware.smack.packet.Message; 17 import org.jivesoftware.smackx.pubsub.provider.ItemProvider; 18 19 /** 20 * This class represents an item that has been, or will be published to a 21 * pubsub node. An <tt>Item</tt> has several properties that are dependent 22 * on the configuration of the node to which it has been or will be published. 23 * 24 * <h1>An Item received from a node (via {@link LeafNode#getItems()} or {@link LeafNode#addItemEventListener(org.jivesoftware.smackx.pubsub.listener.ItemEventListener)}</b> 25 * <li>Will always have an id (either user or server generated) unless node configuration has both 26 * {@link ConfigureForm#isPersistItems()} and {@link ConfigureForm#isDeliverPayloads()}set to false. 27 * <li>Will have a payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 28 * to true, otherwise it will be null. 29 * 30 * <h1>An Item created to send to a node (via {@link LeafNode#send()} or {@link LeafNode#publish()}</b> 31 * <li>The id is optional, since the server will generate one if necessary, but should be used if it is 32 * meaningful in the context of the node. This value must be unique within the node that it is sent to, since 33 * resending an item with the same id will overwrite the one that already exists if the items are persisted. 34 * <li>Will require payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 35 * to true. 36 * 37 * <p>To customise the payload object being returned from the {@link #getPayload()} method, you can 38 * add a custom parser as explained in {@link ItemProvider}. 39 * 40 * @author Robin Collier 41 */ 42 public class Item extends NodeExtension 43 { 44 private String id; 45 46 /** 47 * Create an empty <tt>Item</tt> with no id. This is a valid item for nodes which are configured 48 * so that {@link ConfigureForm#isDeliverPayloads()} is false. In most cases an id will be generated by the server. 49 * For nodes configured with {@link ConfigureForm#isDeliverPayloads()} and {@link ConfigureForm#isPersistItems()} 50 * set to false, no <tt>Item</tt> is sent to the node, you have to use {@link LeafNode#send()} or {@link LeafNode#publish()} 51 * methods in this case. 52 */ Item()53 public Item() 54 { 55 super(PubSubElementType.ITEM); 56 } 57 58 /** 59 * Create an <tt>Item</tt> with an id but no payload. This is a valid item for nodes which are configured 60 * so that {@link ConfigureForm#isDeliverPayloads()} is false. 61 * 62 * @param itemId The id if the item. It must be unique within the node unless overwriting and existing item. 63 * Passing null is the equivalent of calling {@link #Item()}. 64 */ Item(String itemId)65 public Item(String itemId) 66 { 67 // The element type is actually irrelevant since we override getNamespace() to return null 68 super(PubSubElementType.ITEM); 69 id = itemId; 70 } 71 72 /** 73 * Create an <tt>Item</tt> with an id and a node id. 74 * <p> 75 * <b>Note:</b> This is not valid for publishing an item to a node, only receiving from 76 * one as part of {@link Message}. If used to create an Item to publish 77 * (via {@link LeafNode#publish(Item)}, the server <i>may</i> return an 78 * error for an invalid packet. 79 * 80 * @param itemId The id of the item. 81 * @param nodeId The id of the node which the item was published to. 82 */ Item(String itemId, String nodeId)83 public Item(String itemId, String nodeId) 84 { 85 super(PubSubElementType.ITEM_EVENT, nodeId); 86 id = itemId; 87 } 88 89 /** 90 * Get the item id. Unique to the node it is associated with. 91 * 92 * @return The id 93 */ getId()94 public String getId() 95 { 96 return id; 97 } 98 99 @Override getNamespace()100 public String getNamespace() 101 { 102 return null; 103 } 104 105 @Override toXML()106 public String toXML() 107 { 108 StringBuilder builder = new StringBuilder("<item"); 109 110 if (id != null) 111 { 112 builder.append(" id='"); 113 builder.append(id); 114 builder.append("'"); 115 } 116 117 if (getNode() != null) { 118 builder.append(" node='"); 119 builder.append(getNode()); 120 builder.append("'"); 121 } 122 builder.append("/>"); 123 124 return builder.toString(); 125 } 126 127 @Override toString()128 public String toString() 129 { 130 return getClass().getName() + " | Content [" + toXML() + "]"; 131 } 132 } 133