Contact.java

/*
 * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
package net.java.sip.communicator.service.protocol;



/**
 * 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
 */
public interface Contact
{
    /**
     * 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.
     * @return a String id representing and uniquely identifying the contact.
     */
    public String getAddress();

    /**
     * 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).
     * @return a String that can be used for referring to this contact when
     * interacting with the user.
     */
    public String getDisplayName();

    /**
     * Returns a byte array containing an image (most often a photo or an avatar)
     * that the contact uses as a representation.
     * @return byte[] an image representing the contact.
     */
    public byte[] getImage();

    /**
     * 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 <tt>queryContactStatus()</tt> method in
     * <tt>OperationSetPresence</tt>.
     * @return the PresenceStatus that we've received in the last status update
     * pertaining to this contact.
     */
    public PresenceStatus getPresenceStatus();

    /**
     * Returns a reference to the contact group that this contact is currently
     * a child of or null if the underlying protocol does not suppord persistent
     * presence.
     * @return a reference to the contact group that this contact is currently
     * a child of or null if the underlying protocol does not suppord persistent
     * presence.
     */
    public ContactGroup getParentContactGroup();

    /**
     * Returns a reference to the protocol provider that created the contact.
     * @return a refererence to an instance of the ProtocolProviderService
     */
    public ProtocolProviderService getProtocolProvider();

    /**
     * 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.
     * @return true if the contact is persistent and false otherwise.
     */
    public boolean isPersistent();

    /**
     * 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.
     * @return true if the contact has been resolved (mapped against a buddy)
     * and false otherwise.
     */
    public boolean isResolved();

    /**
     * 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.
     * <p>
     * @return A <tt>String</tt> 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.
     */
    public String getPersistentData();
    
    /**
     * Return the current status message of this contact.
     * 
     * @return the current status message
     */
    public String getStatusMessage();
}