001: /**
002: * $RCSfile$
003: * $Revision: $
004: * $Date: $
005: *
006: * Copyright (C) 2007 Jive Software. All rights reserved.
007: *
008: * This software is published under the terms of the GNU Public License (GPL),
009: * a copy of which is included in this distribution.
010: */package org.jivesoftware.openfire.disco;
011:
012: import org.dom4j.DocumentHelper;
013: import org.dom4j.Element;
014: import org.jivesoftware.openfire.resultsetmanager.Result;
015: import org.xmpp.packet.JID;
016:
017: /**
018: * An item is associated with an XMPP Entity, usually thought of a children of
019: * the parent entity and normally are addressable as a JID.<p>
020: *
021: * An item associated with an entity may not be addressable as a JID. In order
022: * to handle such items, Service Discovery uses an optional 'node' attribute
023: * that supplements the 'jid' attribute.
024: *
025: * @author Gaston Dombiak
026: */
027: public class DiscoItem implements Result {
028:
029: private final JID jid;
030: private final String name;
031: private final String node;
032: private final String action;
033: private final Element element;
034:
035: public DiscoItem(Element element) {
036: this .element = element;
037: jid = new JID(element.attributeValue("jid"));
038: action = element.attributeValue("action");
039: name = element.attributeValue("name");
040: node = element.attributeValue("node");
041: }
042:
043: /**
044: * Creates a new DiscoItem instance.
045: *
046: * @param jid
047: * specifies the Jabber ID of the item "owner" or location
048: * (required).
049: * @param name
050: * specifies a natural-language name for the item (can be null).
051: * @param node
052: * specifies the particular node associated with the JID of the
053: * item "owner" or location (can be null).
054: * @param action
055: * specifies the action to be taken for the item.
056: * @throws IllegalArgumentException
057: * If a required parameter was null, or if the supplied 'action'
058: * parameter has another value than 'null', "update" or
059: * "remove".
060: */
061: public DiscoItem(JID jid, String name, String node, String action) {
062: if (jid == null) {
063: throw new IllegalArgumentException(
064: "Argument 'jid' cannot be null.");
065: }
066:
067: if (action != null && !action.equals("update")
068: && !action.equals("remove")) {
069: throw new IllegalArgumentException(
070: "Argument 'jid' cannot have any other value than null, \"update\" or \"remove\".");
071: }
072:
073: this .jid = jid;
074: this .name = name;
075: this .node = node;
076: this .action = action;
077:
078: element = DocumentHelper.createElement("item");
079: element.addAttribute("jid", jid.toString());
080: if (action != null) {
081: element.addAttribute("action", action);
082: }
083: if (name != null) {
084: element.addAttribute("name", name);
085: }
086: if (node != null) {
087: element.addAttribute("node", node);
088: }
089: }
090:
091: /**
092: * <p>
093: * Returns the entity's ID.
094: * </p>
095: *
096: * @return the entity's ID.
097: */
098: public JID getJID() {
099: return jid;
100: }
101:
102: /**
103: * <p>
104: * Returns the node attribute that supplements the 'jid' attribute. A node
105: * is merely something that is associated with a JID and for which the JID
106: * can provide information.
107: * </p>
108: * <p>
109: * Node attributes SHOULD be used only when trying to provide or query
110: * information which is not directly addressable.
111: * </p>
112: *
113: * @return the node attribute that supplements the 'jid' attribute
114: */
115: public String getNode() {
116: return node;
117: }
118:
119: /**
120: * <p>
121: * Returns the entity's name. The entity's name specifies in
122: * natural-language the name for the item.
123: * </p>
124: *
125: * @return the entity's name.
126: */
127: public String getName() {
128: return name;
129: }
130:
131: /**
132: * <p>
133: * Returns the action (i.e. update or remove) that indicates what must be
134: * done with this item or null if none. An "update" action requests the
135: * server to create or update the item. Whilst a "remove" action requests to
136: * remove the item.
137: * </p>
138: *
139: * @return the action (i.e. update or remove) that indicates what must be
140: * done with this item or null if none.
141: */
142: public String getAction() {
143: return action;
144: }
145:
146: /**
147: * Returns a dom4j element that represents this DiscoItem object.
148: *
149: * @return element representing this object.
150: */
151: public Element getElement() {
152: return element;
153: }
154:
155: /*
156: * (non-Javadoc)
157: *
158: * @see org.jivesoftware.util.resultsetmanager.Result#getUID()
159: */
160: public String getUID() {
161: final StringBuilder sb = new StringBuilder(jid.toString());
162: if (name != null) {
163: sb.append(name);
164: }
165: if (node != null) {
166: sb.append(node);
167: }
168: if (action != null) {
169: sb.append(action);
170: }
171:
172: return sb.toString();
173: }
174: }
|