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.ExtensionElement; 020import org.jivesoftware.smack.packet.Message; 021 022import org.jivesoftware.smackx.pubsub.provider.ItemProvider; 023 024/** 025 * This class represents an item that has been, or will be published to a 026 * pubsub node. An <tt>Item</tt> has several properties that are dependent 027 * on the configuration of the node to which it has been or will be published. 028 * 029 * <h3>An Item received from a node (via {@link LeafNode#getItems()} or {@link LeafNode#addItemEventListener(org.jivesoftware.smackx.pubsub.listener.ItemEventListener)}</h3> 030 * <ul> 031 * <li>Will always have an id (either user or server generated) unless node configuration has both 032 * {@link ConfigureForm#isPersistItems()} and {@link ConfigureForm#isDeliverPayloads()}set to false.</li> 033 * <li>Will have a payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 034 * to true, otherwise it will be null.</li> 035 * </ul> 036 * 037 * <h3>An Item created to send to a node (via {@link LeafNode#send()} or {@link LeafNode#publish()}</h3> 038 * <ul> 039 * <li>The id is optional, since the server will generate one if necessary, but should be used if it is 040 * meaningful in the context of the node. This value must be unique within the node that it is sent to, since 041 * resending an item with the same id will overwrite the one that already exists if the items are persisted.</li> 042 * <li>Will require payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 043 * to true.</li> 044 * </ul> 045 * 046 * <p>To customise the payload object being returned from the {@link #getPayload()} method, you can 047 * add a custom parser as explained in {@link ItemProvider}.</p> 048 * 049 * @author Robin Collier 050 */ 051public class PayloadItem<E extends ExtensionElement> extends Item 052{ 053 private final E payload; 054 055 /** 056 * Create an <tt>Item</tt> with no id and a payload The id will be set by the server. 057 * 058 * @param payloadExt A {@link ExtensionElement} which represents the payload data. 059 */ 060 public PayloadItem(E payloadExt) 061 { 062 super(); 063 064 if (payloadExt == null) 065 throw new IllegalArgumentException("payload cannot be 'null'"); 066 payload = payloadExt; 067 } 068 069 /** 070 * Create an <tt>Item</tt> with an id and payload. 071 * 072 * @param itemId The id of this item. It can be null if we want the server to set the id. 073 * @param payloadExt A {@link ExtensionElement} which represents the payload data. 074 */ 075 public PayloadItem(String itemId, E payloadExt) 076 { 077 super(itemId); 078 079 if (payloadExt == null) 080 throw new IllegalArgumentException("payload cannot be 'null'"); 081 payload = payloadExt; 082 } 083 084 /** 085 * Create an <tt>Item</tt> with an id, node id and payload. 086 * 087 * <p> 088 * <b>Note:</b> This is not valid for publishing an item to a node, only receiving from 089 * one as part of {@link Message}. If used to create an Item to publish 090 * (via {@link LeafNode#publish(Item)}, the server <i>may</i> return an 091 * error for an invalid packet. 092 * </p> 093 * 094 * @param itemId The id of this item. 095 * @param nodeId The id of the node the item was published to. 096 * @param payloadExt A {@link ExtensionElement} which represents the payload data. 097 */ 098 public PayloadItem(String itemId, String nodeId, E payloadExt) 099 { 100 super(itemId, nodeId); 101 102 if (payloadExt == null) 103 throw new IllegalArgumentException("payload cannot be 'null'"); 104 payload = payloadExt; 105 } 106 107 /** 108 * Get the payload associated with this <tt>Item</tt>. Customising the payload 109 * parsing from the server can be accomplished as described in {@link ItemProvider}. 110 * 111 * @return The payload as a {@link ExtensionElement}. 112 */ 113 public E getPayload() 114 { 115 return payload; 116 } 117 118 @Override 119 public String toXML() 120 { 121 StringBuilder builder = new StringBuilder("<item"); 122 123 if (getId() != null) 124 { 125 builder.append(" id='"); 126 builder.append(getId()); 127 builder.append('\''); 128 } 129 130 if (getNode() != null) { 131 builder.append(" node='"); 132 builder.append(getNode()); 133 builder.append('\''); 134 } 135 builder.append('>'); 136 builder.append(payload.toXML()); 137 builder.append("</item>"); 138 139 return builder.toString(); 140 } 141 142 @Override 143 public String toString() 144 { 145 return getClass().getName() + " | Content [" + toXML() + "]"; 146 } 147}