net.java.sip.communicator.service.protocol
Interface Contact

All Known Subinterfaces:

ContactSSH

All Known Implementing Classes:

ContactDictImpl, ContactGibberishImpl, ContactIcqImpl, ContactJabberImpl, ContactMsnImpl, ContactRssImpl, ContactSipImpl, ContactSSHImpl, ContactYahooImpl, ContactZeroconfImpl, MockContact, VolatileContactJabberImpl

public interface Contact

This class represents the notion of a Contact or Buddy, that is widely used in instant messaging today. From a protocol point of view, a contact is generally considered to be another user of the service that proposes the protocol. Instances of Contact could be used for delivery of presence notifications or when addressing instant messages.

Author:

Emil Ivov

Method Summary

String	getAddress() Returns a String that can be used for identifying the contact.
String	getDisplayName() Returns a String that could be used by any user interacting modules for referring to this contact.
byte[]	getImage() Returns a byte array containing an image (most often a photo or an avatar) that the contact uses as a representation.
ContactGroup	getParentContactGroup() Returns a reference to the contact group that this contact is currently a child of or null if the underlying protocol does not support persistent presence.
String	getPersistentData() Returns a String that can be used to create a unresolved instance of this contact.
PresenceStatus	getPresenceStatus() Returns the status of the contact as per the last status update we've received for it.
ProtocolProviderService	getProtocolProvider() Returns a reference to the protocol provider that created the contact.
String	getStatusMessage() Return the current status message of this contact.
boolean	isPersistent() Determines whether or not this contact is being stored by the server.
boolean	isResolved() Determines whether or not this contact has been resolved against the server.

Method Detail

getAddress

String getAddress()

Returns a String that can be used for identifying the contact. The exact contents of the string depends on the protocol. In the case of SIP, for example, that would be the SIP uri (e.g. sip:alice@biloxi.com) in the case of icq - a UIN (12345653) and for AIM a screenname (mysname). Jabber (and hence Google) would be having e-mail like addresses.

Returns:

a String id representing and uniquely identifying the contact.

getDisplayName

String getDisplayName()

Returns a String that could be used by any user interacting modules for referring to this contact. An alias is not necessarily unique but is often more human readable than an address (or id).

Returns:

a String that can be used for referring to this contact when interacting with the user.

getImage

byte[] getImage()

Returns a byte array containing an image (most often a photo or an avatar) that the contact uses as a representation.

Returns:

byte[] an image representing the contact.

getPresenceStatus

PresenceStatus getPresenceStatus()

Returns the status of the contact as per the last status update we've received for it. Note that this method is not to perform any network operations and will simply return the status received in the last status update message. If you want a reliable way of retrieving someone's status, you should use the queryContactStatus() method in OperationSetPresence.

Returns:

the PresenceStatus that we've received in the last status update pertaining to this contact.

getParentContactGroup

ContactGroup getParentContactGroup()

Returns a reference to the contact group that this contact is currently a child of or null if the underlying protocol does not support persistent presence.

Returns:

a reference to the contact group that this contact is currently a child of or null if the underlying protocol does not support persistent presence.

getProtocolProvider

ProtocolProviderService getProtocolProvider()

Returns a reference to the protocol provider that created the contact.

Returns:

a reference to an instance of the ProtocolProviderService

isPersistent

boolean isPersistent()

Determines whether or not this contact is being stored by the server. Non persistent contacts are common in the case of simple, non-persistent presence operation sets. They could however also be seen in persistent presence operation sets when for example we have received an event from someone not on our contact list. Non persistent contacts are volatile even when coming from a persistent presence op. set. They would only exist until the application is closed and will not be there next time it is loaded.

Returns:

true if the contact is persistent and false otherwise.

isResolved

boolean isResolved()

Determines whether or not this contact has been resolved against the server. Unresolved contacts are used when initially loading a contact list that has been stored in a local file until the presence operation set has managed to retrieve all the contact list from the server and has properly mapped contacts to their on-line buddies.

Returns:

true if the contact has been resolved (mapped against a buddy) and false otherwise.

getPersistentData

String getPersistentData()

Returns a String that can be used to create a unresolved instance of this contact. Unresolved contacts are created through the createUnresolvedContact() method in the persistent presence operation set. The method may also return null if no such data is required and the contact address is sufficient for restoring the contact.

Returns:

A String that could be used to create a unresolved instance of this contact during a next run of the application, before establishing network connectivity or null if no such data is required.

getStatusMessage

String getStatusMessage()

Return the current status message of this contact.

Returns:

the current status message