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; 020import org.jivesoftware.smack.packet.ExtensionElement; 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.</li> 032 * <li>Will have a payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 033 * to true, otherwise it will be null.</li> 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.</li> 041 * <li>Will require payload if the node configuration has {@link ConfigureForm#isDeliverPayloads()} set 042 * to true.</li> 043 * </ul> 044 * 045 * <p>To customise the payload object being returned from the {@link #getPayload()} method, you can 046 * add a custom parser as explained in {@link ItemProvider}.</p> 047 * 048 * @author Robin Collier 049 */ 050public class PayloadItem<E extends ExtensionElement> extends Item 051{ 052 private E payload; 053 054 /** 055 * Create an <tt>Item</tt> with no id and a payload The id will be set by the server. 056 * 057 * @param payloadExt A {@link ExtensionElement} which represents the payload data. 058 */ 059 public PayloadItem(E payloadExt) 060 { 061 super(); 062 063 if (payloadExt == null) 064 throw new IllegalArgumentException("payload cannot be 'null'"); 065 payload = payloadExt; 066 } 067 068 /** 069 * Create an <tt>Item</tt> with an id and payload. 070 * 071 * @param itemId The id of this item. It can be null if we want the server to set the id. 072 * @param payloadExt A {@link ExtensionElement} which represents the payload data. 073 */ 074 public PayloadItem(String itemId, E payloadExt) 075 { 076 super(itemId); 077 078 if (payloadExt == null) 079 throw new IllegalArgumentException("payload cannot be 'null'"); 080 payload = payloadExt; 081 } 082 083 /** 084 * Create an <tt>Item</tt> with an id, node id and payload. 085 * 086 * <p> 087 * <b>Note:</b> This is not valid for publishing an item to a node, only receiving from 088 * one as part of {@link Message}. If used to create an Item to publish 089 * (via {@link LeafNode#publish(Item)}, the server <i>may</i> return an 090 * error for an invalid packet. 091 * </p> 092 * 093 * @param itemId The id of this item. 094 * @param nodeId The id of the node the item was published to. 095 * @param payloadExt A {@link ExtensionElement} which represents the payload data. 096 */ 097 public PayloadItem(String itemId, String nodeId, E payloadExt) 098 { 099 super(itemId, nodeId); 100 101 if (payloadExt == null) 102 throw new IllegalArgumentException("payload cannot be 'null'"); 103 payload = payloadExt; 104 } 105 106 /** 107 * Get the payload associated with this <tt>Item</tt>. Customising the payload 108 * parsing from the server can be accomplished as described in {@link ItemProvider}. 109 * 110 * @return The payload as a {@link ExtensionElement}. 111 */ 112 public E getPayload() 113 { 114 return payload; 115 } 116 117 @Override 118 public String toXML() 119 { 120 StringBuilder builder = new StringBuilder("<item"); 121 122 if (getId() != null) 123 { 124 builder.append(" id='"); 125 builder.append(getId()); 126 builder.append('\''); 127 } 128 129 if (getNode() != null) { 130 builder.append(" node='"); 131 builder.append(getNode()); 132 builder.append('\''); 133 } 134 builder.append('>'); 135 builder.append(payload.toXML()); 136 builder.append("</item>"); 137 138 return builder.toString(); 139 } 140 141 @Override 142 public String toString() 143 { 144 return getClass().getName() + " | Content [" + toXML() + "]"; 145 } 146}