1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
/*
* 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;
/**
* 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 instacne is
* conveyed to the user through a notification event.
*
* @author Emil Ivov
*/
public class PresenceStatus
implements Comparable
{
/**
* An integer above which all values of the status coefficient indicate
* that a status with connectivity (communication is possible).
*/
public static final int ONLINE_THRESHOLD = 20;
/**
* An integer above which all values of the status coefficient indicate
* both connectivity and availability.
*/
public static final int AVAILABLE_THRESHOLD = 50;
/**
* An integer above which all values of the status coefficient indicate
* eagerness to communicate
*/
public static final int EAGER_TO_COMMUNICATE_THRESSHOLD = 80;
/**
* Represents the connectivity status on a scale from
* 0 to 100 with 0 indicating complete disabiilty 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.)
*/
protected int status = 0;
/**
* The name of this status instance (e.g. Away, On-line, Invisible, etc.)
*/
protected String statusName = null;
/**
* Creates an instance of this class using the specified parameters.
* @param status the status variable representing the new instance
* @param statusName the name of this PresenceStatus
*/
protected PresenceStatus(int status, String statusName)
{
this.status = status;
this.statusName = statusName;
}
/**
* Returns an integer representing the presence status on a scale from
* 0 to 100.
* @return a short indicating the level of availability corresponding to
* this status object.
*/
public int getStatus()
{
return status;
}
/**
* Returns the name of this status (such as Away, On-line, Invisible, etc).
* @return a String variable containing the name of this status instance.
*/
public String getStatusName()
{
return statusName;
}
/**
* Returns a string represenation of this provider status. Strings returned
* by this method have the following format: PresenceStatus:<STATUS_STRING>:
* <STATUS_MESSAGE> and are meant to be used for loggin/debugging purposes.
* @return a string representation of this object.
*/
public String toString()
{
return "PresenceStatus:" + getStatusName();
}
/**
* Indicates whether the user is Online (can be reached) or not.
* @return true if the the status coefficient is higher than the
* ONLINE_THRESHOLD and false otherwise
*/
public boolean isOnline()
{
return getStatus() >= ONLINE_THRESHOLD;
}
/**
* Indicates whether the user is both Online and avaliable (can be reached
* and is likely to respond) or not.
* @return true if the the status coefficient is higher than the
* AVAILABLE_THRESHOLD and false otherwise
*/
public boolean isAvailable()
{
return getStatus() >= AVAILABLE_THRESHOLD;
}
/**
* Indicates whether the user is Online, available and eager to communicatie
* (can be reached and is likely to become annoyngly talkative if contacted).
*
* @return true if the the status coefficient is higher than the
* EAGER_TO_COMMUNICATE_THRESHOLD and false otherwise
*/
public boolean isEagerToCommunicate()
{
return getStatus() >= EAGER_TO_COMMUNICATE_THRESSHOLD;
}
/**
* Compares this inatance 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 availabilite than the one
* specified by the parameter.<p>
*
* @param o the Object to be compared.
* @return 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.
* @throws NullPointerException if o is null
*/
public int compareTo(Object o)
throws ClassCastException, NullPointerException
{
PresenceStatus target = (PresenceStatus)o;
return (getStatus() - target.getStatus());
}
/**
* Indicates whether some other object is "equal to" this one. To
* PresenceStatus instances are considered equal if and only if both their
* connecfitivity coefficient and their name are equal.
* <p>
* @param obj the reference object with which to compare.
* @return <code>true</code> if this presence status instance is equal to
* the obj argument; <code>false</code> otherwise.
*/
public boolean equals(Object obj)
{
if (obj == null
|| !(obj instanceof PresenceStatus) )
return false;
PresenceStatus status = (PresenceStatus)obj;
if (status.getStatus() != getStatus()
|| status.getStatusName() != statusName)
return false;
return true;
}
/**
* Returns a hash code value for the object. This method is
* supported for the benefit of hashtables such as those provided by
* <code>java.util.Hashtable</code>.
* <p>
*
* @return a hash code value for this object (which is actually the result
* of the getStatusName().hashCode()).
*/
public int hashCode()
{
return getStatusName().hashCode();
}
}
|
