Friend.java

package org.limewire.friend.api;

import java.util.Map;

import org.limewire.listener.EventListener;

/** 
 * A Friend.
 */
public interface Friend {

    public static final String P2P_FRIEND_ID = "_@_GNUTELLA_@_";

    /**
     * Returns the ID of the friend.  This can be any form of unique ID.
     * For example, an friend can be in the form of <code>friend@host.com</code>,
     * whereas a Gnutella Friend can be the clientGUID.
     */
    public String getId();

    /**
     * Return the friendly given name to the friend, can be null.
     * For example, a friend can be the alias of the friend,
     * where a Gnutella friend can be the IP address.
     * */
    public String getName();
    
    /** Returns the best possible name this can be rendered with.
     *  
     *  NOTE: must not return null. 
     */
    public String getRenderName();
    
    /** If getRenderName returns something other than email, will return subString using the first ' ' delimeter*/
    public String getFirstName();

    /** Sets a new name for this Friend. */
    void setName(String name);
    
    /**
     * Returns true if this is an anonymous friend.
     * For example, an XMPP friend is not anonymous -- it is identified
     * by an email address and is permanent.  A Gnutella Friend is anonymous,
     * in that their existence is temporary and no long-lasting relationship
     * exists.
     * 
     * Callers can use this to determine if data based on this friend is
     * permanent or not.
     */
    boolean isAnonymous();
    
    /** Returns the {@link Network} that this is a friend on. */
    Network getNetwork();

    /**
     * Allows to register a listener for presence changes of this friend
     */
    void addPresenceListener(EventListener<PresenceEvent> presenceListener);

    /**
     * Used to initiate a new chat.
     * @param reader the <code>MessageReader</code> used to process incoming messages
     * @return the <code>MessageWriter</code> used to send outgoing messages
     */
    MessageWriter createChat(MessageReader reader);

    /**
     * Used to register a listener for new incoming chats.  If a chat listener is already set,
     * it is necessary to remove it prior to setting a new one. Does nothing if chat
     * listener is already set.
     *
     * @param listener the <code>IncomingChatListener</code> to be used
     */
    void setChatListenerIfNecessary(IncomingChatListener listener);

    /**
     * Used for removing the existing listener set in {@link #setChatListenerIfNecessary}
     * for new incoming chats.  Does nothing if there is no chat listener set.
     */
    void removeChatListener();

    /**
     * The active presence is the presence currently
     * chatting with (sending msgs to) this client's presence.
     *
     * @return presence the active presence.  null if there is no active presence
     */
    FriendPresence getActivePresence();

    /**
     * @return true if this friend has an associated active presence
     * (presence this friend is currently chatting with)
     */
    boolean hasActivePresence();

    /**
     * Returns whether or not this friend is signed in to chat.
     * @return true if this friend is signed in with at least 1 presence
     */
    boolean isSignedIn();

    /**
     * Returns a map of all {@link FriendPresence FriendPresences} for this
     * Friend. Keys are the identifier of the presence, as defined by
     * {@link FriendPresence#getPresenceId()}.
     */
    Map<String, FriendPresence> getPresences();

    /**
     * Returns whether the current login is subscribed to this friend.
     * This information is in the roster packet.
     * <p>
     * For instance, if a friend sends the current login a friend
     * add request, and the current login accepts, this method
     * will return true.
     * <p>
     * In the following roster packet, my-mutually-accepted-friend is subscribed,
     * and friend-i-rejected-previously and friend-i-requested-but-has-not-responded
     * are not subscribed.
     * <xmp>
     * <iq to="limebuddytest@gmail.com/WuXLh6tmNLC3320061" id="0Qj6D-15" type="result">
     *   <query xmlns="jabber:iq:roster">
     *     <item jid="my-mutually-accepted-friend@gmail.com" subscription="both" name="Lime Friend">
     *     <item jid="friend-i-rejected-previously@gmail.com" subscription="none"/>
     *     <item jid="friend-i-requested-but-has-not-responded@gmail.com" subscription="none"/>
     *   </query>
     * </iq>
     * </xmp>
     * @return true if the roster entry for this friend has
     * a subscription attribute equal to "both" or "to"
     * Returns false otherwise ("from" or "none")
     */
    boolean isSubscribed();
}