001/** 002 * 003 * Copyright the original author or authors 004 * 005 * Licensed under the Apache License, Version 2.0 (the "License"); 006 * you may not use this file except in compliance with the License. 007 * You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.jivesoftware.smackx.pubsub; 018 019import org.jivesoftware.smack.packet.Message; 020 021import org.jivesoftware.smackx.pubsub.provider.ItemProvider; 022 023/** 024 * This class represents an item that has been, or will be published to a 025 * PubSub node. An <tt>Item</tt> has several properties that are dependent 026 * on the configuration of the node to which it has been or will be published. 027 * 028 * <h3>An Item received from a node (via {@link LeafNode#getItems()} or {@link LeafNode#addItemEventListener(org.jivesoftware.smackx.pubsub.listener.ItemEventListener)}</h3> 029 * <ul> 030 * <li>Will always have an id (either user or server generated) unless node configuration has both 031 * {@link ConfigureForm#isPersistItems()} and {@link ConfigureForm#isDeliverPayloads()}set to false. 032 * <li>Will have a payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 033 * to true, otherwise it will be null. 034 * </ul> 035 * 036 * <h3>An Item created to send to a node (via {@link LeafNode#send()} or {@link LeafNode#publish()}</h3> 037 * <ul> 038 * <li>The id is optional, since the server will generate one if necessary, but should be used if it is 039 * meaningful in the context of the node. This value must be unique within the node that it is sent to, since 040 * resending an item with the same id will overwrite the one that already exists if the items are persisted. 041 * <li>Will require payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 042 * to true. 043 * </ul> 044 * 045 * <p> 046 * To customise the payload object being returned from the {@link PayloadItem#getPayload()} method, you can 047 * add a custom parser as explained in {@link ItemProvider}. 048 * </p> 049 * 050 * @author Robin Collier 051 */ 052public class Item extends NodeExtension 053{ 054 private String id; 055 056 /** 057 * Create an empty <tt>Item</tt> with no id. This is a valid item for nodes which are configured 058 * so that {@link ConfigureForm#isDeliverPayloads()} is false. In most cases an id will be generated by the server. 059 * For nodes configured with {@link ConfigureForm#isDeliverPayloads()} and {@link ConfigureForm#isPersistItems()} 060 * set to false, no <tt>Item</tt> is sent to the node, you have to use {@link LeafNode#send()} or {@link LeafNode#publish()} 061 * methods in this case. 062 */ 063 public Item() 064 { 065 super(PubSubElementType.ITEM); 066 } 067 068 /** 069 * Create an <tt>Item</tt> with an id but no payload. This is a valid item for nodes which are configured 070 * so that {@link ConfigureForm#isDeliverPayloads()} is false. 071 * 072 * @param itemId The id if the item. It must be unique within the node unless overwriting and existing item. 073 * Passing null is the equivalent of calling {@link #Item()}. 074 */ 075 public Item(String itemId) 076 { 077 // The element type is actually irrelevant since we override getNamespace() to return null 078 super(PubSubElementType.ITEM); 079 id = itemId; 080 } 081 082 /** 083 * Create an <tt>Item</tt> with an id and a node id. 084 * <p> 085 * <b>Note:</b> This is not valid for publishing an item to a node, only receiving from 086 * one as part of {@link Message}. If used to create an Item to publish 087 * (via {@link LeafNode#publish(Item)}, the server <i>may</i> return an 088 * error for an invalid packet. 089 * 090 * @param itemId The id of the item. 091 * @param nodeId The id of the node which the item was published to. 092 */ 093 public Item(String itemId, String nodeId) 094 { 095 super(PubSubElementType.ITEM_EVENT, nodeId); 096 id = itemId; 097 } 098 099 /** 100 * Get the item id. Unique to the node it is associated with. 101 * 102 * @return The id 103 */ 104 public String getId() 105 { 106 return id; 107 } 108 109 @Override 110 public String getNamespace() 111 { 112 return null; 113 } 114 115 @Override 116 public String toXML() 117 { 118 StringBuilder builder = new StringBuilder("<item"); 119 120 if (id != null) 121 { 122 builder.append(" id='"); 123 builder.append(id); 124 builder.append('\''); 125 } 126 127 if (getNode() != null) { 128 builder.append(" node='"); 129 builder.append(getNode()); 130 builder.append('\''); 131 } 132 builder.append("/>"); 133 134 return builder.toString(); 135 } 136 137 @Override 138 public String toString() 139 { 140 return getClass().getName() + " | Content [" + toXML() + "]"; 141 } 142}