org.xmpp.packet

Class Roster

java.lang.Object

org.xmpp.packet.Packet

org.xmpp.packet.IQ

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

Nested Classes

Modifier and Type	Class and Description
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

Constructors

Constructor and Description
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, String ID) Constructs a new Roster using the specified type and ID.

Method Summary

Modifier and Type	Method and Description
Roster.Item	addItem(JID jid, Roster.Subscription subscription) Adds a new item to the roster.
Roster.Item	addItem(JID jid, String name, Roster.Ask ask, Roster.Subscription subscription, Collection<String> groups) Adds a new item to the roster.
Roster.Item	addItem(String jid, Roster.Subscription subscription) Adds a new item to the roster.
Roster	createCopy() Returns a deep copy of this Roster.
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,
              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(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,
                           String name,
                           Roster.Ask ask,
                           Roster.Subscription subscription,
                           Collection<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 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.