FriendList.java

/**
 * Interface definition for a Tox Friendlist implementation
 * 
 * @author sonOfRa
 * 
 */
public interface FriendList extends Iterable<ToxFriend> {

	/**
	 * Retrieve a friend from the list by its number
	 * 
	 * @param friendnumber
	 *            the number to look for
	 * @return the first friend in the list with the specified friendnumber.
	 *         Null if no such friend exists.
	 */
	public ToxFriend getByFriendNumber(int friendnumber);

	/**
	 * Retrieve a friend by its client id.
	 * 
	 * @param id
	 *            the id to search for
	 * @return the first friend in the list with the specified client id. Null
	 *         if no such friend exists.
	 */
	public ToxFriend getById(String id);

	/**
	 * Retrieve all friends with the specified name
	 * 
	 * @param name
	 *            the name to look for
	 * @param ignorecase
	 *            when <code>true</code>, this call must ignore the case of
	 *            results
	 * @return a list containing all friends with the specified name. If no
	 *         results are found, an empty List is returned.
	 */
	public List<ToxFriend> getByName(String name, boolean ignorecase);

	/**
	 * Retrieve all friends with the specified nickname
	 * 
	 * @param nickname
	 * @param ignorecase
	 *            when <code>true</code>, this call must ignore the case of
	 *            results
	 * @return a List containing all friends with the specified nickname. If no
	 *         results are found, an empty List is returned.
	 */
	public List<ToxFriend> getByNickname(String nickname, boolean ignorecase);

	/**
	 * Retrieve all Friends that have the content of partial inside of their
	 * names or nicknames. This method should ignore the case when comparing.
	 * 
	 * @param partial
	 *            the partial String to look for
	 * @return a List containing all friends that match the partial String. If
	 *         no results are found, an empty List is returned.
	 */
	public List<ToxFriend> searchFriend(String partial);

	/**
	 * Get all friends that are currently online and have the specified status.
	 * 
	 * @param status
	 *            the status to search for
	 * @return a List containing all friends with the specified status. If no
	 *         friends have that status, an empty List is returned.
	 */
	public List<ToxFriend> getByStatus(ToxUserStatus status);

	/**
	 * Get all currently online friends
	 * 
	 * @return a List containing all online friends. If no friends are online,
	 *         an empty List is returned
	 */
	public List<ToxFriend> getOnlineFriends();

	/**
	 * Get all currently offline friends
	 * 
	 * @return a List containing all offline friends. If no friends are offline,
	 *         an empty List is returned.
	 */
	public List<ToxFriend> getOfflineFriends();
}