javax.servlet.sip
Interface Contact

All Superinterfaces:
java.lang.Cloneable, java.lang.Comparable, SipAddress

public interface Contact
extends SipAddress, java.lang.Comparable

Represents SIP contact addresses. The value of the SIP Contact header is represented as a List of Contact objects. The SIP Contact header specifies one or more locations (URIs) where a user is reachable. and consists of an optional display name along with a URI and a set of parameters.

Contacts in SIP serve two purposes:

  1. As a mechanism for a UA to specify, in INVITE and 2xx responses to INVITE, to its peer UA the exact address to which the peer should address subsequent message within that session. In this case there is always a single URL. Servlets should not set the Contact header in these cases.
  2. The other use of Contact is in REGISTER requests and responses, as well as 3xx and 485 responses. Contacts in these messages are Alternate addresses for a user, and there may be more than one. Servlets may set the value of the Contact header in these messages using either setContacts or the generic setHeader and addHeader on SipServletMessage.

The SIP specification specifies the meaning of two Contact parameters:

The Contact interface extends Comparable so that a list of Contacts can easily be sorted using the sorting algorithms of java.util.Collections. Implementations of Comparable.compareTo(java.lang.Object) are required to return values consistent with getQ(), that is

   x.getQ()  < y.getQ() <=> x.compareTo(y)  < 0,  and
   x.getQ() == y.getQ() <=> x.compareTo(y) == 0
 

See Also:
SipServletMessage.getContacts()

Method Summary
 int getExpires()
          Returns the value of the "expires" parameter as delta-seconds.
 float getQ()
          Returns the value of the "q" parameter of this Contact.
 boolean isWildcard()
          Checks whether this Contact represents the "wildcard" contact address.
 void setExpires(int seconds)
          Sets the value of the "expires" parameter.
 void setQ(float q)
          Sets this Contacts qvalue.
 java.lang.String toString()
          Returns the value of this Contact as a String.
 
Methods inherited from interface javax.servlet.sip.SipAddress
clone, getDisplayName, getParameter, getParameterNames, getURI, removeParameter, setDisplayName, setParameter, setURI
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Method Detail

isWildcard

public boolean isWildcard()
Checks whether this Contact represents the "wildcard" contact address. This is the case if it represents a Contact header whose value was "*". Likewise, SipFactory.createContact("*") always returns a wildcard Contact instance.
Returns:
true if this Contact represents the "wildcard" contact address, and false otherwise

getQ

public float getQ()
Returns the value of the "q" parameter of this Contact. The "qvalue" indicates the relative preference amongst a set of locations. "qvalue" values are decimal numbers from 0 to 1, with higher values indicating higher preference.
Returns:
this Contacts qvalue or -1.0 if this is not set

setQ

public void setQ(float q)
Sets this Contacts qvalue.
Parameters:
q - new qvalue for this Contact or -1 to remove the qvalue
Throws:
java.lang.IllegalArgumentException - if the new qvalue isn't between 0.0 and 1.0 (inclusive) and isn't -1.0.

getExpires

public int getExpires()
Returns the value of the "expires" parameter as delta-seconds.
Returns:
value of "expires" parameter measured in delta-seconds, or -1 if the parameter does not exist

setExpires

public void setExpires(int seconds)
Sets the value of the "expires" parameter.
Parameters:
seconds - new relative value of the "expires" parameter

toString

public java.lang.String toString()
Returns the value of this Contact as a String. This must be a valid value of a SIP Contact header.
Specified by:
toString in interface SipAddress
Overrides:
toString in class java.lang.Object
Returns:
String representation of this Contact header