org.jivesoftware.xiff.im
class Roster
Object
|
+--org.jivesoftware.xiff.im.Roster
class Roster extends Object
Manages a user's server-side instant messaging roster (or "buddy list"). By default, this class uses an internal data provider to keep track of roster data locally and provides a "read-only" form of the Data Provider API for external use. Non-read operations are performed using alternative, roster-specific methods. You can also use your own, external data provider if you choose, by using the
setExternalDataProvider() method. This is most useful for applications where the data provider might need to be a class other than an array with the Data Provider API decorations, like in the case of a Macromedia Central LCDataProvider. Overall, however, its probably a rare occurence. - Author:Sean Voisen
- Since:2.0.0
Property Summary
The instance of the XMPPConnection class to use for the roster to use for sending and receiving data.
(Read-only) The number of items in the roster.
Method Summary
public addContact (
id: String, displayName: String, group: String, requestSubscription: Boolean
): Void
Adds a contact to the roster. Remember: All roster data is managed on the server-side, so this contact is added to the server-side roster first, and upon successful addition, reflected in the local client-side copy of the roster.
Revokes an existing presence subscription or denies a subscription request. If a user has sent you a subscription request you can use this method to deny that request. Otherwise, if a user already has a granted presence subscription, you can use this method to revoke that subscription.
Fetches the roster data from the server. Once the data has been fetched, the Roster's data provider is populated appropriately. If the Roster-XMPPConnection class dependency has been set up before logging in, then this method will be called automatically because the Roster listens for "login" events from the XMPPConnection.
Gets all of the locally-cached information for a certain contact by in the roster.
Gets a roster item at a specific index. Part of the "read-only" implementation of the DataProvider API. Roster items are generic objects with the following attributes:
jid, displayName, group, subscribeType, status, show, and priority. Gets the ID of a roster item at a particular index. Part of the "read-only" implementation of the DataProvider API.
Grants a user or service authorization for subscribing to your presence. Once authorization is granted, the user can see whether you are offline, online, away, etc. Subscriptions can be revoked at any time using the
denySubscription() method. Removes a contact from the roster and revokes all presence subscriptions for that contact. This method will only attempt action if the contact you are trying to remove is currently on the roster in the first place.
Requests subscription authorization with a user or service. In the XMPP-world, you cannot receive notifications on changes to a contact's presence until that contact has authorized you to subscribe to his/her/its presence.
Allows use of an external data provider instead of the one used internally by the class by default. This is useful in the case of a Macromedia Central application where the data provider might need to be an instance of an LCDataProvider. The data provider should either implement the Data Provider API interface, or the interface for Central's LCDataProvider.
Sets your current presence status. Calling this method notifies others who are subscribed to your presence of a presence change. You should use this to change your status to away, extended-away, etc. There are static variables that you can use defined in the presence class for the
show parameter: Presence.SHOW_AWAYPresence.SHOW_CHATPresence.SHOW_DNDPresence.SHOW_NORMALPresence.SHOW_XA
Sorts items in the roster using a specific comparison function as passed to the method. Part of the "read-only" implementation of the DataProvider API. For more information, consult the DataProvider documentation.
Sorts items in the roster by a specific field name.
Updates the information for an existing contact. You can use this method to change the display name or associated group for a contact in your roster.
Field Documentation
Property Documentation
connection
public connection: XMPPConnection (read, write)
The instance of the XMPPConnection class to use for the roster to use for sending and receiving data.
Constructor Documentation
Method Documentation
addContact
public function addContact (
id: String,
displayName: String,
group: String,
requestSubscription: Boolean): Void
displayName: String,
group: String,
requestSubscription: Boolean): Void
Adds a contact to the roster. Remember: All roster data is managed on the server-side, so this contact is added to the server-side roster first, and upon successful addition, reflected in the local client-side copy of the roster.
- Parameters:
id The JID of the contact to add displayName A friendly name for use when displaying this contact in the roster group (Optional) The name of the group that this contact should be added to. (Used for organization in the roster listing. requestSubscription (Optional) Determines whether a subscription request should be sent to this user. Most of the time you will want this parameter to be true. You will be unable to view the contacts presence status until a subscription request is granted. - Example:This example adds a contact to the roster and simultaneously requests a presence subscription with the new contact.
myRoster.addContact( "homer@springfield.com", "Homer", "Drinking Buddies", true );
denySubscription
public function denySubscription (
to: String): Void
Revokes an existing presence subscription or denies a subscription request. If a user has sent you a subscription request you can use this method to deny that request. Otherwise, if a user already has a granted presence subscription, you can use this method to revoke that subscription.
- Parameters:
to The JID of the user or service that you are denying subscription
fetchRoster
public function fetchRoster (
): Void
Fetches the roster data from the server. Once the data has been fetched, the Roster's data provider is populated appropriately. If the Roster-XMPPConnection class dependency has been set up before logging in, then this method will be called automatically because the Roster listens for "login" events from the XMPPConnection.
getContactInformation
public function getContactInformation (
jid: String): Object
Gets all of the locally-cached information for a certain contact by in the roster.
- Parameters:
jid The JID of the contact to lookup. - Returns:An object with the attributes
jid,displayName,subscribeType,group,status,showandpriority.
getItemAt
public function getItemAt (
index: Number): Object
Gets a roster item at a specific index. Part of the "read-only" implementation of the DataProvider API. Roster items are generic objects with the following attributes:
jid, displayName, group, subscribeType, status, show, and priority. - Parameters:
index The index of the item to get - Returns:An object representing the roster item retrieved. Null, if none is found at the index provided.
getItemID
public function getItemID (
index: Number): Number
Gets the ID of a roster item at a particular index. Part of the "read-only" implementation of the DataProvider API.
- Parameters:
index The index of the item whose ID you wish to retrieve - Returns:The item ID
grantSubscription
public function grantSubscription (
to: String,
requestAfterGrant: Boolean): Void
requestAfterGrant: Boolean): Void
Grants a user or service authorization for subscribing to your presence. Once authorization is granted, the user can see whether you are offline, online, away, etc. Subscriptions can be revoked at any time using the
denySubscription() method. - Parameters:
to The JID of the user or service to grant subscription to requestAfterGrant Whether or not a reciprocal subscription request should be sent to the grantee, so that you may, in turn, subscribe to his/her/its presence.
removeContact
public function removeContact (
id: String): Void
Removes a contact from the roster and revokes all presence subscriptions for that contact. This method will only attempt action if the contact you are trying to remove is currently on the roster in the first place.
- Parameters:
id The JID of the contact to remove
requestSubscription
public function requestSubscription (
id: String): Void
Requests subscription authorization with a user or service. In the XMPP-world, you cannot receive notifications on changes to a contact's presence until that contact has authorized you to subscribe to his/her/its presence.
- Parameters:
id The JID of the user or service that you wish to subscribe to - See also:
setExternalDataProvider
public function setExternalDataProvider (
externalDP: Object): Void
Allows use of an external data provider instead of the one used internally by the class by default. This is useful in the case of a Macromedia Central application where the data provider might need to be an instance of an LCDataProvider. The data provider should either implement the Data Provider API interface, or the interface for Central's LCDataProvider.
- Parameters:
externalDP A reference to the external data provider
setPresence
public function setPresence (
show: String,
status: String,
priority: Number): Void
status: String,
priority: Number): Void
Sets your current presence status. Calling this method notifies others who are subscribed to your presence of a presence change. You should use this to change your status to away, extended-away, etc. There are static variables that you can use defined in the presence class for the
show parameter: Presence.SHOW_AWAYPresence.SHOW_CHATPresence.SHOW_DNDPresence.SHOW_NORMALPresence.SHOW_XA
- Parameters:
show The show type for your presence. This represents what others should see - whether you are offline, online, away, etc. status The status message associated with the show value priority (Optional) A priority number for the presence - See also:
sortItems
public function sortItems (
compareFunc,
optionFlags): Void
optionFlags): Void
Sorts items in the roster using a specific comparison function as passed to the method. Part of the "read-only" implementation of the DataProvider API. For more information, consult the DataProvider documentation.
- Parameters:
compareFunc The function to use for comparison optionFlags The option flags
sortItemsBy
public function sortItemsBy (
fieldName,
order): Void
order): Void
Sorts items in the roster by a specific field name.
- Parameters:
fieldName The field name to sort by order The sort order, either ascending or descending - "ASC" or "DSC". - Example:The following example sorts roster items by their display name in ascending order.
myRoster.sortItemsBy( "displayName", "ASC" );
updateContact
public function updateContact (
id: String,
newName: String,
newGroup: String): Void
newName: String,
newGroup: String): Void
Updates the information for an existing contact. You can use this method to change the display name or associated group for a contact in your roster.
- Parameters:
id The JID of the contact to update newName The new display name for this contact newGroup The new group to associate the contact with
- Roster.as, Last Modified: 4/20/2005 10:41:24 AM