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}