net.java.sip.communicator.service.protocol
Class PresenceStatus

java.lang.Object
  net.java.sip.communicator.service.protocol.PresenceStatus

All Implemented Interfaces:

Comparable<PresenceStatus>

Direct Known Subclasses:

AimStatusEnum, DictStatusEnum, GibberishStatusEnum, IcqStatusEnum, IrcStatusEnum, MockStatusEnum, MsnStatusEnum, RssStatusEnum, SSHStatusEnum, YahooStatusEnum, ZeroconfStatusEnum

public class PresenceStatus
extends Object
implements Comparable<PresenceStatus>

The class is used to represent the state of the connection of a given ProtocolProvider or Contact. It is up to the implementation to determine the exact states that an object might go through. An IM provider for example might go through states like, CONNECTING, ON-LINE, AWAY, etc, A status instance is represented by an integer varying from 0 to 100, a Status Name and a Status Description. The integer status variable is used so that the users of the service get the notion of whether or not a given Status instance represents a state that allows communication (above 20) and so that it could compare instances between themselves (e.g. for sorting a ContactList for example). A state may not be created by the user. User may request a status change giving parameters requested by the ProtocolProvider. Once a statue is successfully entered by the provider, a ConnectivityStatus instance is conveyed to the user through a notification event.

Author:

Emil Ivov

Field Summary

static int	AVAILABLE_THRESHOLD An integer above which all values of the status coefficient indicate both connectivity and availability.
static int	AWAY_THRESHOLD An integer above which all values of the status coefficient indicate both connectivity and availability but the person is away from the computer.
static int	EAGER_TO_COMMUNICATE_THRESHOLD An integer above which all values of the status coefficient indicate eagerness to communicate
static int	MAX_STATUS_VALUE An integer indicating the maximum possible value of the status field.
static int	ONLINE_THRESHOLD An integer above which all values of the status coefficient indicate that a status with connectivity (communication is possible).
protected int	status Represents the connectivity status on a scale from 0 to 100 with 0 indicating complete disability for communication and 100 maximum ability and user willingness.
protected byte[]	statusIcon An image that graphically represents the status.
protected String	statusName The name of this status instance (e.g.

Constructor Summary

protected	PresenceStatus(int status, String statusName) Creates an instance of this class using the specified parameters.
protected	PresenceStatus(int status, String statusName, byte[] statusIcon) Creates an instance of this class using the specified parameters.

Method Summary

int	compareTo(PresenceStatus target) Compares this instance with the specified object for order.
boolean	equals(Object obj) Indicates whether some other object is "equal to" this one.
int	getStatus() Returns an integer representing the presence status on a scale from 0 to 100.
byte[]	getStatusIcon() Returns an image that graphically represents the status.
String	getStatusName() Returns the name of this status (such as Away, On-line, Invisible, etc).
int	hashCode() Returns a hash code value for the object.
boolean	isAvailable() Indicates whether the user is both Online and avaliable (can be reached and is likely to respond) or not.
boolean	isEagerToCommunicate() Indicates whether the user is Online, available and eager to communicate (can be reached and is likely to become annoyingly talkative if contacted).
boolean	isOnline() Indicates whether the user is Online (can be reached) or not.
String	toString() Returns a string representation of this provider status.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ONLINE_THRESHOLD

public static final int ONLINE_THRESHOLD

An integer above which all values of the status coefficient indicate that a status with connectivity (communication is possible).

See Also:

Constant Field Values

AWAY_THRESHOLD

public static final int AWAY_THRESHOLD

An integer above which all values of the status coefficient indicate both connectivity and availability but the person is away from the computer.

See Also:

Constant Field Values

AVAILABLE_THRESHOLD

public static final int AVAILABLE_THRESHOLD

An integer above which all values of the status coefficient indicate both connectivity and availability.

See Also:

Constant Field Values

EAGER_TO_COMMUNICATE_THRESHOLD

public static final int EAGER_TO_COMMUNICATE_THRESHOLD

An integer above which all values of the status coefficient indicate eagerness to communicate

See Also:

Constant Field Values

MAX_STATUS_VALUE

public static final int MAX_STATUS_VALUE

An integer indicating the maximum possible value of the status field.

See Also:

Constant Field Values

statusIcon

protected final byte[] statusIcon

An image that graphically represents the status.

status

protected final int status

Represents the connectivity status on a scale from 0 to 100 with 0 indicating complete disability for communication and 100 maximum ability and user willingness. Implementors of this service should respect the following indications for status values. 0 - complete disability 1:10 - initializing. 1:20 - trying to enter a state where communication is possible (Connecting ..) 20:50 - communication is possible but might be unwanted, inefficient or delayed(e.g. Away state in IM clients) 50:80 - communication is possible (On - line) 80:100 - communication is possible and user is eager to communicate. (Free for chat! Talk to me, etc.)

statusName

protected final String statusName

The name of this status instance (e.g. Away, On-line, Invisible, etc.)

Constructor Detail

PresenceStatus

protected PresenceStatus(int status,
                         String statusName)

Creates an instance of this class using the specified parameters.

Parameters:

status - the status variable representing the new instance

statusName - the name of this PresenceStatus

PresenceStatus

protected PresenceStatus(int status,
                         String statusName,
                         byte[] statusIcon)

Creates an instance of this class using the specified parameters.

Parameters:

status - the status variable representing the new instance

statusName - the name of this PresenceStatus

statusIcon - an image that graphically represents the status or null if no such image is available.

Method Detail

getStatus

public int getStatus()

Returns an integer representing the presence status on a scale from 0 to 100.

Returns:

a short indicating the level of availability corresponding to this status object.

getStatusName

public String getStatusName()

Returns the name of this status (such as Away, On-line, Invisible, etc).

Returns:

a String variable containing the name of this status instance.

toString

public String toString()

Returns a string representation of this provider status. Strings returned by this method have the following format: PresenceStatus:: and are meant to be used for logging/debugging purposes.

Overrides:

toString in class Object

Returns:

a string representation of this object.

isOnline

public boolean isOnline()

Indicates whether the user is Online (can be reached) or not.

Returns:

true if the the status coefficient is higher than the ONLINE_THRESHOLD and false otherwise

isAvailable

public boolean isAvailable()

Indicates whether the user is both Online and avaliable (can be reached and is likely to respond) or not.

Returns:

true if the the status coefficient is higher than the AVAILABLE_THRESHOLD and false otherwise

isEagerToCommunicate

public boolean isEagerToCommunicate()

Indicates whether the user is Online, available and eager to communicate (can be reached and is likely to become annoyingly talkative if contacted).

Returns:

true if the the status coefficient is higher than the EAGER_TO_COMMUNICATE_THRESHOLD and false otherwise

compareTo

public int compareTo(PresenceStatus target)
              throws ClassCastException,
                     NullPointerException

Compares this instance with the specified object for order. Returns a negative integer, zero, or a positive integer as this status instance is considered to represent less, as much, or more availability than the one specified by the parameter.

Specified by:

compareTo in interface Comparable<PresenceStatus>

Parameters:

target - the PresenceStatus to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Throws:

ClassCastException - if the specified object's type prevents it from being compared to this Object.

NullPointerException - if o is null

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one. To PresenceStatus instances are considered equal if and only if both their connectivity coefficient and their name are equal.

Overrides:

equals in class Object

Parameters:

obj - the reference object with which to compare.

Returns:

true if this presence status instance is equal to the obj argument; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object (which is actually the result of the getStatusName().hashCode()).

getStatusIcon

public byte[] getStatusIcon()

Returns an image that graphically represents the status.

Returns:

a byte array containing the image that graphically represents the status or null if no such image is available.