org.jivesoftware.openfire.roster
Class RosterItem

java.lang.Object
  org.jivesoftware.openfire.roster.RosterItem

All Implemented Interfaces:

Externalizable, Serializable, Cacheable

public class RosterItem
extends Object
implements Cacheable, Externalizable

Represents a single roster item for a User's Roster.

The server doesn't need to know anything about roster groups so they are not stored with easy retrieval or manipulation in mind. The important data elements of a roster item (beyond the jid adddress of the roster entry) includes:

• nick - A nickname for the user when used in this roster
• sub - A subscription type: to, from, none, both
• ask - An optional subscription ask status: subscribe, unsubscribe
• groups - A list of groups to organize roster entries under (e.g. friends, co-workers, etc)

Author:

Gaston Dombiak

See Also:

Serialized Form

Nested Class Summary

static class	RosterItem.AskType
static class	RosterItem.RecvType
static class	RosterItem.SubType

Field Summary

static RosterItem.AskType	ASK_NONE The roster item has no pending subscription requests.
static RosterItem.AskType	ASK_SUBSCRIBE The roster item has been asked for permission to subscribe to their presence but no response has been received.
static RosterItem.AskType	ASK_UNSUBSCRIBE The roster owner has asked to the roster item to unsubscribe from it's presence but has not received confirmation.
protected RosterItem.AskType	askStatus
protected List<String>	groups
protected Set<String>	invisibleSharedGroups
protected JID	jid
protected String	nickname
static RosterItem.RecvType	RECV_NONE There are no subscriptions that have been received but not presented to the user.
static RosterItem.RecvType	RECV_SUBSCRIBE The server has received a subscribe request, but has not forwarded it to the user.
static RosterItem.RecvType	RECV_UNSUBSCRIBE The server has received an unsubscribe request, but has not forwarded it to the user.
protected RosterItem.RecvType	recvStatus
protected Set<String>	sharedGroups
static RosterItem.SubType	SUB_BOTH The roster item and owner have a mutual subscription.
static RosterItem.SubType	SUB_FROM The roster item has a subscription to the roster owner's presence.
static RosterItem.SubType	SUB_NONE No subscription is established.
static RosterItem.SubType	SUB_REMOVE Indicates the roster item should be removed.
static RosterItem.SubType	SUB_TO The roster owner has a subscription to the roster item's presence.
protected RosterItem.SubType	subStatus

Constructor Summary

RosterItem()
Constructor added for Externalizable.

RosterItem(JID jid, RosterItem.SubType subStatus, RosterItem.AskType askStatus, RosterItem.RecvType recvStatus, String nickname, List<String> groups)

RosterItem(long id, JID jid, RosterItem.SubType subStatus, RosterItem.AskType askStatus, RosterItem.RecvType recvStatus, String nickname, List<String> groups)

RosterItem(Roster.Item item)
Create a roster item from the data in another one.

Method Summary

void	addInvisibleSharedGroup(Group sharedGroup) Adds a new group to the list shared groups that won't be sent to the user.
void	addSharedGroup(Group sharedGroup) Adds a new group to the shared groups list.
RosterItem.AskType	getAskStatus() Obtain the current ask status of the item.
int	getCachedSize() Returns the approximate size of the Object in bytes.
List<String>	getGroups() Returns the groups for the item.
long	getID() Returns the roster ID associated with this particular roster item.
Collection<Group>	getInvisibleSharedGroups() Returns the invisible shared groups for the item.
JID	getJid() Obtain the address of the item.
String	getNickname() Obtain the current nickname for the item.
RosterItem.RecvType	getRecvStatus() Obtain the current recv status of the item.
Collection<Group>	getSharedGroups() Returns the shared groups for the item.
RosterItem.SubType	getSubStatus() Obtain the current subscription status of the item.
boolean	isOnlyShared() Returns true if this item belongs ONLY to shared groups.
boolean	isShared() Returns true if this item belongs to a shared group.
void	readExternal(ObjectInput in)
void	removeSharedGroup(Group sharedGroup) Removes a group from the shared groups list.
void	setAsCopyOf(Roster.Item item) Update the cached item as a copy of the given item.
void	setAskStatus(RosterItem.AskType askStatus) Set the current ask status of the item.
void	setGroups(List<String> groups) Set the current groups for the item.
void	setID(long rosterID) Sets the roster ID associated with this particular roster item.
void	setNickname(String nickname) Set the current nickname for the item.
void	setRecvStatus(RosterItem.RecvType recvStatus) Set the current recv status of the item.
void	setSubStatus(RosterItem.SubType subStatus) Set the current subscription status of the item.
void	writeExternal(ObjectOutput out)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SUB_REMOVE

public static final RosterItem.SubType SUB_REMOVE

Indicates the roster item should be removed.

SUB_NONE

public static final RosterItem.SubType SUB_NONE

No subscription is established.

SUB_TO

public static final RosterItem.SubType SUB_TO

The roster owner has a subscription to the roster item's presence.

SUB_FROM

public static final RosterItem.SubType SUB_FROM

The roster item has a subscription to the roster owner's presence.

SUB_BOTH

public static final RosterItem.SubType SUB_BOTH

The roster item and owner have a mutual subscription.

ASK_NONE

public static final RosterItem.AskType ASK_NONE

The roster item has no pending subscription requests.

ASK_SUBSCRIBE

public static final RosterItem.AskType ASK_SUBSCRIBE

The roster item has been asked for permission to subscribe to their presence but no response has been received.

ASK_UNSUBSCRIBE

public static final RosterItem.AskType ASK_UNSUBSCRIBE

The roster owner has asked to the roster item to unsubscribe from it's presence but has not received confirmation.

RECV_NONE

public static final RosterItem.RecvType RECV_NONE

There are no subscriptions that have been received but not presented to the user.

RECV_SUBSCRIBE

public static final RosterItem.RecvType RECV_SUBSCRIBE

The server has received a subscribe request, but has not forwarded it to the user.

RECV_UNSUBSCRIBE

public static final RosterItem.RecvType RECV_UNSUBSCRIBE

The server has received an unsubscribe request, but has not forwarded it to the user.

recvStatus

protected RosterItem.RecvType recvStatus

jid

protected JID jid

nickname

protected String nickname

groups

protected List<String> groups

sharedGroups

protected Set<String> sharedGroups

invisibleSharedGroups

protected Set<String> invisibleSharedGroups

subStatus

protected RosterItem.SubType subStatus

askStatus

protected RosterItem.AskType askStatus

Constructor Detail

RosterItem

public RosterItem()

Constructor added for Externalizable. Do not use this constructor.

RosterItem

public RosterItem(long id,
                  JID jid,
                  RosterItem.SubType subStatus,
                  RosterItem.AskType askStatus,
                  RosterItem.RecvType recvStatus,
                  String nickname,
                  List<String> groups)

RosterItem

public RosterItem(JID jid,
                  RosterItem.SubType subStatus,
                  RosterItem.AskType askStatus,
                  RosterItem.RecvType recvStatus,
                  String nickname,
                  List<String> groups)

RosterItem

public RosterItem(Roster.Item item)

Create a roster item from the data in another one.

Parameters:

item - Item that contains the info of the roster item.

Method Detail

getSubStatus

public RosterItem.SubType getSubStatus()

Obtain the current subscription status of the item.

Returns:

The subscription status of the item

setSubStatus

public void setSubStatus(RosterItem.SubType subStatus)

Set the current subscription status of the item.

Parameters:

subStatus - The subscription status of the item

getAskStatus

public RosterItem.AskType getAskStatus()

Obtain the current ask status of the item.

Returns:

The ask status of the item

setAskStatus

public void setAskStatus(RosterItem.AskType askStatus)

Set the current ask status of the item.

Parameters:

askStatus - The ask status of the item

getRecvStatus

public RosterItem.RecvType getRecvStatus()

Obtain the current recv status of the item.

Returns:

The recv status of the item

setRecvStatus

public void setRecvStatus(RosterItem.RecvType recvStatus)

Set the current recv status of the item.

Parameters:

recvStatus - The recv status of the item

getJid

public JID getJid()

Obtain the address of the item.

Returns:

The address of the item

getNickname

public String getNickname()

Obtain the current nickname for the item.

Returns:

The subscription status of the item

setNickname

public void setNickname(String nickname)

Set the current nickname for the item.

Parameters:

nickname - The subscription status of the item

getGroups

public List<String> getGroups()

Returns the groups for the item. Shared groups won't be included in the answer.

Returns:

The groups for the item.

setGroups

public void setGroups(List<String> groups)
               throws SharedGroupException

Set the current groups for the item.

Parameters:

groups - The new lists of groups the item belongs to.

Throws:

SharedGroupException - if trying to remove shared group.

getSharedGroups

public Collection<Group> getSharedGroups()

Returns the shared groups for the item.

Returns:

The shared groups this item belongs to.

getInvisibleSharedGroups

public Collection<Group> getInvisibleSharedGroups()

Returns the invisible shared groups for the item. These groups are for internal use and help track the reason why a roster item has a presence subscription of type FROM when using shared groups.

Returns:

The shared groups this item belongs to.

addSharedGroup

public void addSharedGroup(Group sharedGroup)

Adds a new group to the shared groups list.

Parameters:

sharedGroup - The shared group to add to the list of shared groups.

addInvisibleSharedGroup

public void addInvisibleSharedGroup(Group sharedGroup)

Adds a new group to the list shared groups that won't be sent to the user. These groups are for internal use and help track the reason why a roster item has a presence subscription of type FROM when using shared groups.

Parameters:

sharedGroup - The shared group to add to the list of shared groups.

removeSharedGroup

public void removeSharedGroup(Group sharedGroup)

Removes a group from the shared groups list.

Parameters:

sharedGroup - The shared group to remove from the list of shared groups.

isShared

public boolean isShared()

Returns true if this item belongs to a shared group. Return true even if the item belongs to a personal group and a shared group.

Returns:

true if this item belongs to a shared group.

isOnlyShared

public boolean isOnlyShared()

Returns true if this item belongs ONLY to shared groups. This means that the the item is considered to be "only shared" if it doesn't belong to a personal group but only to shared groups.

Returns:

true if this item belongs ONLY to shared groups.

getID

public long getID()

Returns the roster ID associated with this particular roster item. A value of zero means that the roster item is not being persisted in the backend store.

Databases can use the roster ID as the key in locating roster items.

Returns:

The roster ID

setID

public void setID(long rosterID)

Sets the roster ID associated with this particular roster item. A value of zero means that the roster item is not being persisted in the backend store.

Databases can use the roster ID as the key in locating roster items.

Parameters:

rosterID - The roster ID.

setAsCopyOf

public void setAsCopyOf(Roster.Item item)
                 throws SharedGroupException

Update the cached item as a copy of the given item.

A convenience for getting the item and setting each attribute.

Parameters:

item - The item who's settings will be copied into the cached copy

Throws:

SharedGroupException - if trying to remove shared group.

getCachedSize

public int getCachedSize()

Description copied from interface: Cacheable

Returns the approximate size of the Object in bytes. The size should be considered to be a best estimate of how much memory the Object occupies and may be based on empirical trials or dynamic calculations.

Specified by:

getCachedSize in interface Cacheable

Returns:

the size of the Object in bytes.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException