ItemsExtension.java

  1. /**
  2.  *
  3.  * Copyright the original author or authors
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.jivesoftware.smackx.pubsub;

  18. import java.util.List;

  19. import org.jivesoftware.smack.packet.ExtensionElement;
  20. import org.jivesoftware.smack.packet.NamedElement;
  21. import org.jivesoftware.smack.packet.XmlElement;
  22. import org.jivesoftware.smack.util.XmlStringBuilder;

  23. /**
  24.  * This class is used for multiple purposes.
  25.  * <ul>
  26.  * <li>It can represent an event containing a list of items that have been published
  27.  * <li>It can represent an event containing a list of retracted (deleted) items.
  28.  * <li>It can represent a request to delete a list of items.
  29.  * <li>It can represent a request to get existing items.
  30.  * </ul>
  31.  *
  32.  * <p><b>Please note, this class is used for internal purposes, and is not required for usage of
  33.  * pubsub functionality.</b></p>
  34.  *
  35.  * @author Robin Collier
  36.  */
  37. public class ItemsExtension extends NodeExtension implements EmbeddedPacketExtension {
  38.     protected ItemsElementType type;
  39.     protected Boolean notify;
  40.     protected List<? extends NamedElement> items;

  41.     public enum ItemsElementType {
  42.         /** An items element, which has an optional <b>max_items</b> attribute when requesting items. */
  43.         items(PubSubElementType.ITEMS, "max_items"),

  44.         /** A retract element, which has an optional <b>notify</b> attribute when publishing deletions. */
  45.         retract(PubSubElementType.RETRACT, "notify");

  46.         private final PubSubElementType elem;
  47.         private final String att;

  48.         ItemsElementType(PubSubElementType nodeElement, String attribute) {
  49.             elem = nodeElement;
  50.             att = attribute;
  51.         }

  52.         public PubSubElementType getNodeElement() {
  53.             return elem;
  54.         }

  55.         public String getElementAttribute() {
  56.             return att;
  57.         }
  58.     }

  59.     /**
  60.      * Construct an instance with a list representing items that have been published or deleted.
  61.      *
  62.      * <p>Valid scenarios are:</p>
  63.      * <ul>
  64.      * <li>Request items from node - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and an
  65.      * optional value for the <b>max_items</b> attribute.
  66.      * <li>Request to delete items - itemsType = {@link ItemsElementType#retract}, items = list of {@link Item} containing
  67.      * only id's and an optional value for the <b>notify</b> attribute.
  68.      * <li>Items published event - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and
  69.      * attributeValue = <code>null</code>
  70.      * <li>Items deleted event -  itemsType = {@link ItemsElementType#items}, items = list of {@link RetractItem} and
  71.      * attributeValue = <code>null</code>
  72.      * </ul>
  73.      *
  74.      * @param itemsType Type of representation
  75.      * @param nodeId The node to which the items are being sent or deleted
  76.      * @param items The list of {@link Item} or {@link RetractItem}
  77.      */
  78.     public ItemsExtension(ItemsElementType itemsType, String nodeId, List<? extends NamedElement> items) {
  79.         super(itemsType.getNodeElement(), nodeId);
  80.         type = itemsType;
  81.         this.items = items;
  82.     }

  83.     /**
  84.      * Construct an instance with a list representing items that have been published or deleted.
  85.      *
  86.      * <p>Valid scenarios are:</p>
  87.      * <ul>
  88.      * <li>Request items from node - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and an
  89.      * optional value for the <b>max_items</b> attribute.
  90.      * <li>Request to delete items - itemsType = {@link ItemsElementType#retract}, items = list of {@link Item} containing
  91.      * only id's and an optional value for the <b>notify</b> attribute.
  92.      * <li>Items published event - itemsType = {@link ItemsElementType#items}, items = list of {@link Item} and
  93.      * attributeValue = <code>null</code>
  94.      * <li>Items deleted event -  itemsType = {@link ItemsElementType#items}, items = list of {@link RetractItem} and
  95.      * attributeValue = <code>null</code>
  96.      * </ul>
  97.      *
  98.      * @param nodeId The node to which the items are being sent or deleted
  99.      * @param items The list of {@link Item} or {@link RetractItem}
  100.      * @param notify TODO javadoc me please
  101.      */
  102.     public ItemsExtension(String nodeId, List<? extends ExtensionElement> items, boolean notify) {
  103.         super(ItemsElementType.retract.getNodeElement(), nodeId);
  104.         type = ItemsElementType.retract;
  105.         this.items = items;
  106.         this.notify = notify;
  107.     }

  108.     /**
  109.      * Get the type of element.
  110.      *
  111.      * @return The element type
  112.      */
  113.     public ItemsElementType getItemsElementType() {
  114.         return type;
  115.     }

  116.     @Override
  117.     @SuppressWarnings("unchecked")
  118.     public List<XmlElement> getExtensions() {
  119.         return (List<XmlElement>) getItems();
  120.     }

  121.     /**
  122.      * Gets the items related to the type of request or event.
  123.      *
  124.      * @return List of {@link Item}, {@link RetractItem}, or null
  125.      */
  126.     // TODO: Shouldn't this return List<Item>? Why is RetractItem not a subtype of item?
  127.     public List<? extends NamedElement> getItems() {
  128.         return items;
  129.     }

  130.     /**
  131.      * Gets the value of the optional attribute related to the {@link ItemsElementType}.
  132.      *
  133.      * @return The attribute value
  134.      */
  135.     public boolean getNotify() {
  136.         return notify;
  137.     }

  138.     @Override
  139.     protected void addXml(XmlStringBuilder xml) {
  140.         if ((items == null) || (items.size() == 0)) {
  141.             xml.closeEmptyElement();
  142.             return;
  143.         }

  144.         if (notify != null) {
  145.             xml.attribute(type.getElementAttribute(), notify);
  146.             xml.rightAngleBracket();
  147.         } else {
  148.             xml.rightAngleBracket();
  149.             xml.append(items);
  150.         }

  151.         xml.closeElement(this);
  152.     }

  153.     @Override
  154.     public String toString() {
  155.         return getClass().getName() + "Content [" + toXML() + "]";
  156.     }

  157. }