Home | History | Annotate | Download | only in pubsub 
      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 	 */
     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 	 */
     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 	 */
     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 	 */
     94 	public String getId()
     95 	{
     96 		return id;
     97 	}
     98 
     99 	@Override
    100 	public String getNamespace()
    101 	{
    102 		return null;
    103 	}
    104 
    105 	@Override
    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
    128 	public String toString()
    129 	{
    130 		return getClass().getName() + " | Content [" + toXML() + "]";
    131 	}
    132 }
    133