001/**
002 *
003 * Copyright 2003-2007 Jive Software.
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.disco.packet;
018
019import java.util.ArrayList;
020import java.util.Collection;
021import java.util.Collections;
022import java.util.HashSet;
023import java.util.LinkedList;
024import java.util.List;
025import java.util.Set;
026
027import org.jivesoftware.smack.XMPPConnection;
028import org.jivesoftware.smack.packet.IQ;
029import org.jivesoftware.smack.packet.IqData;
030import org.jivesoftware.smack.util.EqualsUtil;
031import org.jivesoftware.smack.util.HashCode;
032import org.jivesoftware.smack.util.StringUtils;
033import org.jivesoftware.smack.util.XmlStringBuilder;
034
035import org.jxmpp.util.XmppStringUtils;
036
037/**
038 * A DiscoverInfo IQ packet, which is used by XMPP clients to request and receive information
039 * to/from other XMPP entities.<p>
040 *
041 * The received information may contain one or more identities of the requested XMPP entity, and
042 * a list of supported features by the requested XMPP entity.
043 *
044 * @author Gaston Dombiak
045 */
046public class DiscoverInfo extends IQ implements DiscoverInfoView {
047
048    public static final String ELEMENT = QUERY_ELEMENT;
049    public static final String NAMESPACE = "http://jabber.org/protocol/disco#info";
050
051    private final List<Feature> features = new ArrayList<>();
052    private final Set<Feature> featuresSet = new HashSet<>();
053    private final List<Identity> identities = new ArrayList<>();
054    private final Set<String> identitiesSet = new HashSet<>();
055    private String node;
056    private boolean containsDuplicateFeatures;
057
058    DiscoverInfo(DiscoverInfoBuilder builder, boolean validate) {
059        super(builder, ELEMENT, NAMESPACE);
060
061        features.addAll(builder.getFeatures());
062        identities.addAll(builder.getIdentities());
063        node = builder.getNode();
064
065
066        for (Feature feature : features) {
067            boolean featureIsNew = featuresSet.add(feature);
068            if (!featureIsNew) {
069                containsDuplicateFeatures = true;
070            }
071        }
072
073        for (Identity identity : identities) {
074            identitiesSet.add(identity.getKey());
075        }
076
077        if (!validate) {
078            return;
079        }
080
081        if (containsDuplicateFeatures) {
082            throw new IllegalArgumentException("The disco#info request contains duplicate features.");
083        }
084    }
085
086    /**
087     * Deprecated.
088     *
089     * @deprecated use {@link DiscoverInfoBuilder} instead.
090     */
091    @Deprecated
092    // TODO: Remove in Smack 4.5.
093    public DiscoverInfo() {
094        super(ELEMENT, NAMESPACE);
095    }
096
097    /**
098     * Copy constructor.
099     *
100     * @param d TODO javadoc me please
101     */
102    public DiscoverInfo(DiscoverInfo d) {
103        super(d);
104
105        // Set node
106        node = d.getNode();
107
108        // Copy features
109        features.addAll(d.features);
110        featuresSet.addAll(d.featuresSet);
111
112        // Copy identities
113        identities.addAll(d.identities);
114        identitiesSet.addAll(d.identitiesSet);
115    }
116
117    /**
118     * Adds a new feature to the discovered information.
119     *
120     * @param feature the discovered feature
121     * @return true if the feature did not already exist.
122     * @deprecated use {@link DiscoverInfoBuilder#addFeature(String)} instead.
123     */
124    @Deprecated
125    // TODO: Remove in Smack 4.5.
126    public boolean addFeature(String feature) {
127        return addFeature(new Feature(feature));
128    }
129
130    /**
131     * Adds a collection of features to the packet. Does noting if featuresToAdd is null.
132     *
133     * @param featuresToAdd TODO javadoc me please
134     * @deprecated use {@link DiscoverInfoBuilder#addFeatures(Collection)} instead.
135     */
136    @Deprecated
137    // TODO: Remove in Smack 4.5.
138    public void addFeatures(Collection<String> featuresToAdd) {
139        if (featuresToAdd == null) return;
140        for (String feature : featuresToAdd) {
141            addFeature(feature);
142        }
143    }
144
145    /**
146     * Deprecated.
147     *
148     * @param feature the future.
149     * @return true if the feature is new.
150     * @deprecated use {@link DiscoverInfoBuilder#addFeature(DiscoverInfo.Feature)} instead.
151     */
152    @Deprecated
153    // TODO: Remove in Smack 4.5.
154    public boolean addFeature(Feature feature) {
155        features.add(feature);
156        boolean featureIsNew = featuresSet.add(feature);
157        if (!featureIsNew) {
158            containsDuplicateFeatures = true;
159        }
160        return featureIsNew;
161    }
162
163    @Override
164    public List<Feature> getFeatures() {
165        return Collections.unmodifiableList(features);
166    }
167
168    /**
169     * Adds a new identity of the requested entity to the discovered information.
170     *
171     * @param identity the discovered entity's identity
172     * @deprecated use {@link DiscoverInfoBuilder#addIdentity(DiscoverInfo.Identity)} instead.
173     */
174    @Deprecated
175    // TODO: Remove in Smack 4.5.
176    public void addIdentity(Identity identity) {
177        identities.add(identity);
178        identitiesSet.add(identity.getKey());
179    }
180
181    /**
182     * Adds identities to the DiscoverInfo stanza.
183     *
184     * @param identitiesToAdd TODO javadoc me please
185     * @deprecated use {@link DiscoverInfoBuilder#addIdentities(Collection)} instead.
186     */
187    @Deprecated
188    // TODO: Remove in Smack 4.5.
189    public void addIdentities(Collection<Identity> identitiesToAdd) {
190        if (identitiesToAdd == null) return;
191        for (Identity identity : identitiesToAdd) {
192            addIdentity(identity);
193        }
194    }
195
196    @Override
197    public List<Identity> getIdentities() {
198        return Collections.unmodifiableList(identities);
199    }
200
201    /**
202     * Returns true if this DiscoverInfo contains at least one Identity of the given category and type.
203     *
204     * @param category the category to look for.
205     * @param type the type to look for.
206     * @return true if this DiscoverInfo contains a Identity of the given category and type.
207     */
208    public boolean hasIdentity(String category, String type) {
209        String key = XmppStringUtils.generateKey(category, type);
210        return identitiesSet.contains(key);
211    }
212
213    /**
214     * Returns all Identities of the given category and type of this DiscoverInfo.
215     *
216     * @param category category the category to look for.
217     * @param type type the type to look for.
218     * @return a list of Identites with the given category and type.
219     */
220    public List<Identity> getIdentities(String category, String type) {
221        List<Identity> res = new ArrayList<>(identities.size());
222        for (Identity identity : identities) {
223            if (identity.getCategory().equals(category) && identity.getType().equals(type)) {
224                res.add(identity);
225            }
226        }
227        return res;
228    }
229
230    @Override
231    public String getNode() {
232        return node;
233    }
234
235    /**
236     * Sets the node attribute that supplements the 'jid' attribute. A node is merely
237     * something that is associated with a JID and for which the JID can provide information.<p>
238     *
239     * Node attributes SHOULD be used only when trying to provide or query information which
240     * is not directly addressable.
241     *
242     * @param node the node attribute that supplements the 'jid' attribute
243     * @deprecated use {@link DiscoverInfoBuilder#setNode(String)} instead.
244     */
245    @Deprecated
246    // TODO: Remove in Smack 4.5.
247    public void setNode(String node) {
248        this.node = StringUtils.requireNullOrNotEmpty(node, "The node can not be the empty string");
249    }
250
251    /**
252     * Returns true if the specified feature is part of the discovered information.
253     *
254     * @param feature the feature to check
255     * @return true if the requests feature has been discovered
256     */
257    public boolean containsFeature(CharSequence feature) {
258        return features.contains(new Feature(feature));
259    }
260
261    @Override
262    protected IQChildElementXmlStringBuilder getIQChildElementBuilder(IQChildElementXmlStringBuilder xml) {
263        xml.optAttribute("node", getNode());
264        xml.rightAngleBracket();
265        for (Identity identity : identities) {
266            xml.append(identity.toXML());
267        }
268        for (Feature feature : features) {
269            xml.append(feature.toXML());
270        }
271
272        return xml;
273    }
274
275    /**
276     * Test if a DiscoverInfo response contains duplicate identities.
277     *
278     * @return true if duplicate identities where found, otherwise false
279     */
280    public boolean containsDuplicateIdentities() {
281        List<Identity> checkedIdentities = new LinkedList<>();
282        for (Identity i : identities) {
283            for (Identity i2 : checkedIdentities) {
284                if (i.equals(i2))
285                    return true;
286            }
287            checkedIdentities.add(i);
288        }
289        return false;
290    }
291
292    /**
293     * Test if a DiscoverInfo response contains duplicate features.
294     *
295     * @return true if duplicate identities where found, otherwise false
296     */
297    public boolean containsDuplicateFeatures() {
298        return containsDuplicateFeatures;
299    }
300
301    public DiscoverInfoBuilder asBuilder(String stanzaId) {
302        return new DiscoverInfoBuilder(this, stanzaId);
303    }
304
305    /**
306     * Deprecated, do not use.
307     *
308     * @deprecated use {@link #asBuilder(String)} instead.
309     */
310    // TODO: Remove in Smack 4.5.
311    @Deprecated
312    @Override
313    public DiscoverInfo clone() {
314        return new DiscoverInfo(this);
315    }
316
317    public static DiscoverInfoBuilder builder(XMPPConnection connection) {
318        return new DiscoverInfoBuilder(connection);
319    }
320
321    public static DiscoverInfoBuilder builder(IqData iqData) {
322        return new DiscoverInfoBuilder(iqData);
323    }
324
325    public static DiscoverInfoBuilder builder(String stanzaId) {
326        return new DiscoverInfoBuilder(stanzaId);
327    }
328
329    /**
330     * Represents the identity of a given XMPP entity. An entity may have many identities but all
331     * the identities SHOULD have the same name.<p>
332     *
333     * Refer to <a href="https://xmpp.org/registrar/disco-categories.html">XMPP Registry for Service Discovery Identities</a>
334     * in order to get the official registry of values for the <i>category</i> and <i>type</i>
335     * attributes.
336     *
337     */
338    public static final class Identity implements Comparable<Identity> {
339
340        private final String category;
341        private final String type;
342        private final String key;
343        private final String name;
344        private final String lang; // 'xml:lang;
345
346        /**
347         * Creates a new identity for an XMPP entity.
348         *
349         * @param category the entity's category (required as per XEP-30).
350         * @param type the entity's type (required as per XEP-30).
351         */
352        public Identity(String category, String type) {
353            this(category, type, null, null);
354        }
355
356        /**
357         * Creates a new identity for an XMPP entity.
358         * 'category' and 'type' are required by
359         * <a href="http://xmpp.org/extensions/xep-0030.html#schemas">XEP-30 XML Schemas</a>
360         *
361         * @param category the entity's category (required as per XEP-30).
362         * @param name the entity's name.
363         * @param type the entity's type (required as per XEP-30).
364         */
365        public Identity(String category, String name, String type) {
366            this(category, type, name, null);
367        }
368
369        /**
370         * Creates a new identity for an XMPP entity.
371         * 'category' and 'type' are required by
372         * <a href="http://xmpp.org/extensions/xep-0030.html#schemas">XEP-30 XML Schemas</a>
373         *
374         * @param category the entity's category (required as per XEP-30).
375         * @param type the entity's type (required as per XEP-30).
376         * @param name the entity's name.
377         * @param lang the entity's lang.
378         */
379        public Identity(String category, String type, String name, String lang) {
380            this.category = StringUtils.requireNotNullNorEmpty(category, "category cannot be null");
381            this.type = StringUtils.requireNotNullNorEmpty(type, "type cannot be null");
382            this.key = XmppStringUtils.generateKey(category, type);
383            this.name = name;
384            this.lang = lang;
385        }
386
387        /**
388         * Returns the entity's category. To get the official registry of values for the
389         * 'category' attribute refer to <a href="https://xmpp.org/registrar/disco-categories.html">XMPP Registry for Service Discovery Identities</a>.
390         *
391         * @return the entity's category.
392         */
393        public String getCategory() {
394            return category;
395        }
396
397        /**
398         * Returns the identity's name.
399         *
400         * @return the identity's name.
401         */
402        public String getName() {
403            return name;
404        }
405
406        /**
407         * Returns the entity's type. To get the official registry of values for the
408         * 'type' attribute refer to <a href="https://xmpp.org/registrar/disco-categories.html">XMPP Registry for Service Discovery Identities</a>.
409         *
410         * @return the entity's type.
411         */
412        public String getType() {
413            return type;
414        }
415
416        /**
417         * Returns the identities natural language if one is set.
418         *
419         * @return the value of xml:lang of this Identity
420         */
421        public String getLanguage() {
422            return lang;
423        }
424
425        private String getKey() {
426            return key;
427        }
428
429        /**
430         * Returns true if this identity is of the given category and type.
431         *
432         * @param category the category.
433         * @param type the type.
434         * @return true if this identity is of the given category and type.
435         */
436        public boolean isOfCategoryAndType(String category, String type) {
437            return this.category.equals(category) && this.type.equals(type);
438        }
439
440        public XmlStringBuilder toXML() {
441            XmlStringBuilder xml = new XmlStringBuilder();
442            xml.halfOpenElement("identity");
443            xml.xmllangAttribute(lang);
444            xml.attribute("category", category);
445            xml.optAttribute("name", name);
446            xml.optAttribute("type", type);
447            xml.closeEmptyElement();
448            return xml;
449        }
450
451        /**
452         * Check equality for Identity  for category, type, lang and name
453         * in that order as defined by
454         * <a href="http://xmpp.org/extensions/xep-0115.html#ver-proc">XEP-0015 5.4 Processing Method (Step 3.3)</a>.
455         *
456         */
457        @Override
458        public boolean equals(Object obj) {
459            return EqualsUtil.equals(this, obj, (e, o) -> {
460                e.append(key, o.key)
461                 .append(lang, o.lang)
462                 .append(name, o.name);
463            });
464        }
465
466        private final HashCode.Cache hashCodeCache = new HashCode.Cache();
467
468        @Override
469        public int hashCode() {
470            return hashCodeCache.getHashCode(c ->
471                c.append(key)
472                 .append(lang)
473                 .append(name)
474            );
475        }
476
477        /**
478         * Compares this identity with another one. The comparison order is: Category, Type, Lang.
479         * If all three are identical the other Identity is considered equal. Name is not used for
480         * comparison, as defined by XEP-0115
481         *
482         * @param other TODO javadoc me please
483         * @return a negative integer, zero, or a positive integer as this object is less than,
484         *         equal to, or greater than the specified object.
485         */
486        @Override
487        public int compareTo(DiscoverInfo.Identity other) {
488            String otherLang = other.lang == null ? "" : other.lang;
489            String thisLang = lang == null ? "" : lang;
490
491            // This can be removed once the deprecated constructor is removed.
492            String otherType = other.type == null ? "" : other.type;
493            String thisType = type == null ? "" : type;
494
495            if (category.equals(other.category)) {
496                if (thisType.equals(otherType)) {
497                    if (thisLang.equals(otherLang)) {
498                        // Don't compare on name, XEP-30 says that name SHOULD
499                        // be equals for all identities of an entity
500                        return 0;
501                    } else {
502                        return thisLang.compareTo(otherLang);
503                    }
504                } else {
505                    return thisType.compareTo(otherType);
506                }
507            } else {
508                return category.compareTo(other.category);
509            }
510        }
511
512        @Override
513        public String toString() {
514            return toXML().toString();
515        }
516    }
517
518    /**
519     * Represents the features offered by the item. This information helps the requester to determine
520     * what actions are possible with regard to this item (registration, search, join, etc.)
521     * as well as specific feature types of interest, if any (e.g., for the purpose of feature
522     * negotiation).
523     */
524    public static final class Feature {
525
526        private final String variable;
527
528        public Feature(Feature feature) {
529            this.variable = feature.variable;
530        }
531
532        public Feature(CharSequence variable) {
533            this(variable.toString());
534        }
535
536        /**
537         * Creates a new feature offered by an XMPP entity or item.
538         *
539         * @param variable the feature's variable.
540         */
541        public Feature(String variable) {
542            this.variable = StringUtils.requireNotNullNorEmpty(variable, "variable cannot be null");
543        }
544
545        /**
546         * Returns the feature's variable.
547         *
548         * @return the feature's variable.
549         */
550        public String getVar() {
551            return variable;
552        }
553
554        public XmlStringBuilder toXML() {
555            XmlStringBuilder xml = new XmlStringBuilder();
556            xml.halfOpenElement("feature");
557            xml.attribute("var", variable);
558            xml.closeEmptyElement();
559            return xml;
560        }
561
562        @Override
563        public boolean equals(Object obj) {
564            return EqualsUtil.equals(this, obj, (e, o) -> {
565                e.append(variable, o.variable);
566            });
567        }
568
569        @Override
570        public int hashCode() {
571            return variable.hashCode();
572        }
573
574        @Override
575        public String toString() {
576            return toXML().toString();
577        }
578    }
579}