org.xmpp.packet
Class Roster

java.lang.Object
  extended by org.xmpp.packet.Packet
      extended by org.xmpp.packet.IQ
          extended by org.xmpp.packet.Roster

@NotThreadSafe
public class Roster
extends IQ

Roster packet. The roster is a list of JIDs (typically other users) that the user wishes to track the presence of. Each roster item is keyed by JID and contains a nickname (optional), subscription type, and list of groups (optional).

Author:
Matt Tucker

Nested Class Summary
static class Roster.Ask
          Type-safe enumeration for the roster ask type.
static class Roster.Item
          Item in a roster, which represents an individual contact.
static class Roster.Subscription
          Type-safe enumeration for the roster subscription type.
 
Nested classes/interfaces inherited from class org.xmpp.packet.IQ
IQ.Type
 
Field Summary
 
Fields inherited from class org.xmpp.packet.Packet
docFactory, element, fromJID, toJID
 
Constructor Summary
Roster()
          Constructs a new Roster with an automatically generated ID and a type of IQ.Type.get.
Roster(org.dom4j.Element element)
          Constructs a new Roster using an existing Element.
Roster(IQ.Type type)
          Constructs a new Roster using the specified type.
Roster(IQ.Type type, java.lang.String ID)
          Constructs a new Roster using the specified type and ID.
 
Method Summary
 Roster.Item addItem(JID jid, Roster.Subscription subscription)
          Adds a new item to the roster.
 Roster.Item addItem(JID jid, java.lang.String name, Roster.Ask ask, Roster.Subscription subscription, java.util.Collection<java.lang.String> groups)
          Adds a new item to the roster.
 Roster.Item addItem(java.lang.String jid, Roster.Subscription subscription)
          Adds a new item to the roster.
 Roster createCopy()
          Returns a deep copy of this Roster.
 java.util.Collection<Roster.Item> getItems()
          Returns an unmodifiable copy of the Items in the roster packet.
 void removeItem(JID jid)
          Removes an item from this roster.
 
Methods inherited from class org.xmpp.packet.IQ
addExtension, createResultIQ, deleteExtension, getChildElement, getExtension, getType, isRequest, isResponse, setChildElement, setChildElement, setType
 
Methods inherited from class org.xmpp.packet.Packet
getElement, getError, getFrom, getID, getTo, setError, setError, setFrom, setFrom, setID, setTo, setTo, toString, toXML
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Roster

public Roster()
Constructs a new Roster with an automatically generated ID and a type of IQ.Type.get.


Roster

public Roster(IQ.Type type)
Constructs a new Roster using the specified type. A packet ID will be automatically generated.

Parameters:
type - the IQ type.

Roster

public Roster(IQ.Type type,
              java.lang.String ID)
Constructs a new Roster using the specified type and ID.

Parameters:
type - the IQ type.
ID - the packet ID of the IQ.

Roster

public Roster(org.dom4j.Element element)
Constructs a new Roster using an existing Element. This is useful for parsing incoming roster Elements into Roster objects.

Parameters:
element - the Roster Element.
Method Detail

addItem

public Roster.Item addItem(java.lang.String jid,
                           Roster.Subscription subscription)
Adds a new item to the roster. The name and groups are set to null If the roster packet already contains an item using the same JID, the information in the existing item will be overwritten with the new information.

The XMPP specification recommends that if the roster item is associated with another instant messaging user (human), that the JID be in bare form (e.g. user@domain). Use the toBareJID() method for a bare JID.

Parameters:
jid - the JID.
subscription - the subscription type.
Returns:
the newly created item.

addItem

public Roster.Item addItem(JID jid,
                           Roster.Subscription subscription)
Adds a new item to the roster. The name and groups are set to null If the roster packet already contains an item using the same JID, the information in the existing item will be overwritten with the new information.

The XMPP specification recommends that if the roster item is associated with another instant messaging user (human), that the JID be in bare form (e.g. user@domain). Use the toBareJID() method for a bare JID.

Parameters:
jid - the JID.
subscription - the subscription type.
Returns:
the newly created item.

addItem

public Roster.Item addItem(JID jid,
                           java.lang.String name,
                           Roster.Ask ask,
                           Roster.Subscription subscription,
                           java.util.Collection<java.lang.String> groups)
Adds a new item to the roster. If the roster packet already contains an item using the same JID, the information in the existing item will be overwritten with the new information.

The XMPP specification recommends that if the roster item is associated with another instant messaging user (human), that the JID be in bare form (e.g. user@domain). Use the toBareJID() method for a bare JID.

Parameters:
jid - the JID.
name - the nickname.
ask - the ask type.
subscription - the subscription type.
groups - a Collection of groups.
Returns:
the newly created item.

removeItem

public void removeItem(JID jid)
Removes an item from this roster.

Parameters:
jid - the JID of the item to remove.

getItems

public java.util.Collection<Roster.Item> getItems()
Returns an unmodifiable copy of the Items in the roster packet.

Returns:
an unmodifable copy of the Items in the roster packet.

createCopy

public Roster createCopy()
Returns a deep copy of this Roster.

Overrides:
createCopy in class IQ
Returns:
a deep copy of this Roster.


Copyright © 2009-2010 Ignite Realtime. All Rights Reserved.