Package rocks.xmpp.im.roster.model

Class Contact

java.lang.Object

rocks.xmpp.im.roster.model.Contact

All Implemented Interfaces:

Comparable<Contact>, Addressable, RosterItem, SubscriptionState

public final class Contact
extends Object
implements RosterItem, Comparable<Contact>

A contact in the user's roster.

2.1.2. Roster Items

The <query/> element inside a roster set contains one <item/> child, and a roster result typically contains multiple <item/> children. Each <item/> element describes a unique "roster item" (sometimes also called a "contact").

This class is immutable.

Nested Class Summary

Nested classes/interfaces inherited from interface rocks.xmpp.im.roster.model.SubscriptionState

SubscriptionState.Subscription

Constructor Summary

Constructors

Constructor	Description
Contact(Jid jid)	Creates a new contact associated with the given JID.
Contact(Jid jid, String name)	Creates a new contact associated with the given JID and name.
Contact(Jid jid, String name, Boolean isPending, Boolean approved, SubscriptionState.Subscription subscription, Collection<String> groups)	Creates a new contact associated with the given JID, name and groups.
Contact(Jid jid, String name, String... groups)	Creates a new contact associated with the given JID, name and groups.
Contact(Jid jid, String name, Collection<String> groups)	Creates a new contact associated with the given JID, name and groups.
Contact(RosterItem rosterItem)	Creates a new contact from a roster item.

Method Summary

Modifier and Type	Method	Description
int	compareTo(Contact o)	Compares two contacts with each other by first comparing their names, then their subscription states and eventually their pending states.
boolean	equals(Object o)
List<String>	getGroups()	Gets the groups of the contact.
Jid	getJid()	Gets the JID of the contact.
String	getName()	Gets the name of the contact.
SubscriptionState.Subscription	getSubscription()	Gets the subscription attribute.
int	hashCode()
boolean	isApproved()	Gets the subscription pre-approval status.
boolean	isPendingIn()	Roster items on the XMPP layer don't have a notion of a "Pending In" subscription state, therefore this methods always returns false.
boolean	isPendingOut()	Gets the pending state of the contact.
static Contact	removeContact(Jid jid)	Creates a new contact to send to the server for removal.
String	toString()
Contact	withGroups(String... groups)	Creates an identical contact with only the groups changed.
Contact	withGroups(Collection<String> groups)	Creates an identical contact with only the groups changed.
Contact	withName(String name)	Creates an identical contact with only the name changed.
Contact	withoutGroups()	Creates an identical contact without groups.
Contact	withoutName()	Creates an identical contact without name.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Contact

public Contact(Jid jid)

Creates a new contact associated with the given JID.

Parameters:

jid - The JID.

Contact

public Contact(Jid jid,
               String name)

Creates a new contact associated with the given JID and name.

Parameters:

jid - The JID.

name - The name.

Contact

public Contact(Jid jid,
               String name,
               String... groups)

Creates a new contact associated with the given JID, name and groups.

Parameters:

jid - The JID.

name - The name.

groups - The groups for this contact.

Contact

public Contact(Jid jid,
               String name,
               Collection<String> groups)

Creates a new contact associated with the given JID, name and groups.

Parameters:

jid - The JID.

name - The name.

groups - The groups for this contact.

Contact

public Contact(RosterItem rosterItem)

Creates a new contact from a roster item.

Parameters:

rosterItem - The roster item.

Contact

public Contact(Jid jid,
               String name,
               Boolean isPending,
               Boolean approved,
               SubscriptionState.Subscription subscription,
               Collection<String> groups)

Creates a new contact associated with the given JID, name and groups.

Parameters:

jid - The JID.

name - The name.

isPending - Indicates, whether the contact's subscription approval is pending.

approved - Indicates, whether the contact is pre-approved.

subscription - The subscription.

groups - The groups for this contact.

Method Detail

removeContact

public static Contact removeContact(Jid jid)

Creates a new contact to send to the server for removal.

Parameters:

jid - Jid of the contact to be removed.

Returns:

a contact with only the Jid and SubscriptionState.Subscription.REMOVE set.

withName

public Contact withName(String name)

Creates an identical contact with only the name changed.

Parameters:

name - The name.

Returns:

A new contact object with only the name changed.

withoutName

public Contact withoutName()

Creates an identical contact without name.

Returns:

A new contact object with only the name changed.

withGroups

public Contact withGroups(Collection<String> groups)

Creates an identical contact with only the groups changed.

Parameters:

groups - the new groups.

Returns:

a new contact with only the groups changed.

withGroups

public Contact withGroups(String... groups)

Creates an identical contact with only the groups changed.

Parameters:

groups - the new groups.

Returns:

a new contact with only the groups changed.

withoutGroups

public Contact withoutGroups()

Creates an identical contact without groups.

Returns:

a new contact with no groups.

getJid

public final Jid getJid()

Gets the JID of the contact.

Specified by:

getJid in interface Addressable

Returns:

The JID.

getName

public final String getName()

Gets the name of the contact.

2.1.2.4. Name Attribute

The 'name' attribute of the <item/> element specifies the "handle" to be associated with the JID, as determined by the user (not the contact). Although the value of the 'name' attribute MAY have meaning to a human user, it is opaque to the server. However, the 'name' attribute MAY be used by the server for matching purposes within the context of various XMPP extensions (one possible comparison method is that described for XMPP resourceparts in [XMPP-ADDR]).

It is OPTIONAL for a client to include the 'name' attribute when adding or updating a roster item.

Specified by:

getName in interface RosterItem

Returns:

The name.

getSubscription

public final SubscriptionState.Subscription getSubscription()

Gets the subscription attribute.

Specified by:

getSubscription in interface SubscriptionState

Returns:

The subscription attribute.

isPendingOut

public final boolean isPendingOut()

Gets the pending state of the contact.

2.1.2.2. Ask Attribute

The 'ask' attribute of the <item/> element with a value of "subscribe" is used to signal various subscription sub-states that include a "Pending Out" aspect as described under Section 3.1.2.

A server SHOULD include the 'ask' attribute to inform the client of "Pending Out" sub-states. A client MUST NOT include the 'ask' attribute in the roster sets it sends to the server, but instead MUST use presence stanzas of type "subscribe" and "unsubscribe" to manage such sub-states as described under Section 3.1.2.

Specified by:

isPendingOut in interface SubscriptionState

Returns:

True, if a subscription request for the contact is pending, i.e. the contact has not yet approved or denied a subscription request.

isPendingIn

public final boolean isPendingIn()

Roster items on the XMPP layer don't have a notion of a "Pending In" subscription state, therefore this methods always returns false. Pending-in subscription states are not represented in the user's roster at all.

Specified by:

isPendingIn in interface SubscriptionState

Returns:

Always false.

isApproved

public final boolean isApproved()

Gets the subscription pre-approval status.

2.1.2.1. Approved Attribute

The boolean 'approved' attribute with a value of "true" is used to signal subscription pre-approval as described under Section 3.4

Specified by:

isApproved in interface RosterItem

Returns:

True, if the contact is pre approved.

getGroups

public final List<String> getGroups()

Gets the groups of the contact.

Specified by:

getGroups in interface RosterItem

Returns:

The groups.

equals

public final boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

compareTo

public final int compareTo(Contact o)

Compares two contacts with each other by first comparing their names, then their subscription states and eventually their pending states.

Specified by:

compareTo in interface Comparable<Contact>

Parameters:

o - The other contact.

Returns:

The result of the comparison.

toString

public final String toString()

Overrides:

toString in class Object