javax.servlet.sip
Interface Address

All Superinterfaces:
java.lang.Cloneable, Parameterable

public interface Address
extends Parameterable

Represents SIP addresses as found, for example, in From, To, and Contact headers. Applications use addresses when sending requests as a user agent client (UAC) and when redirecting an incoming request.

Addresses appear in a number of SIP headers and generally adhere to the grammar (constituent non-terminals are defined in the SIP specification, RFC 3261):

 (name-addr / addr-spec) *(SEMI generic-param)
 
that is to say, Addresses consist of a URI, an optional display name, and a set of name-value parameters.

The Address interface is used to represent the value of all headers defined to contain one or more addresses as defined above. Apart from From, To, and Contact, this includes Route, Record-Route, Reply-To, Alert-Info, Call-Info, Error-Info, as well as extension headers like P-Asserted-Identity, P-Preferred-Identity, and Path.

Address objects can be constructed using one of the SipFactory.createAddress methods and can be obtained from messages using SipServletMessage.getAddressHeader(java.lang.String) and SipServletMessage.getAddressHeaders(java.lang.String).


Method Summary
 java.lang.Object clone()
          Returns a clone of this Address.
 boolean equals(java.lang.Object o)
          Compares the given Address with this one.
 java.lang.String getDisplayName()
          Returns the display name of this Address.
 int getExpires()
          Returns the value of the "expires" parameter as delta-seconds.
 float getQ()
          Returns the value of the "q" parameter of this Address.
 URI getURI()
          Returns the URI component of this Address.
 boolean isWildcard()
          Returns true if this Address represents the "wildcard" contact address.
 void setDisplayName(java.lang.String name)
          Sets the display name of this Address.
 void setExpires(int seconds)
          Sets the value of the "expires" parameter.
 void setQ(float q)
          Sets this Addresss qvalue.
 void setURI(URI uri)
          Sets the URI of this Address.
 java.lang.String toString()
          Returns the value of this address as a String.
 
Methods inherited from interface javax.servlet.sip.Parameterable
getParameter, getParameterNames, getParameters, getValue, removeParameter, setParameter, setValue
 

Method Detail

getDisplayName

java.lang.String getDisplayName()
Returns the display name of this Address. This is typically a caller or callees real name and may be rendered by a user agent, for example when alerting.

Returns:
display name of this Address, or null if one doesn't exist

setDisplayName

void setDisplayName(java.lang.String name)
Sets the display name of this Address.

Parameters:
name - display name
Throws:
java.lang.IllegalStateException - if this Address is used in a context where it cannot be modified

getURI

URI getURI()
Returns the URI component of this Address. This method will return null for wildcard addresses (see isWildcard(). For non-wildcard addresses the result will always be non-null.

Returns:
the URI of this Address

setURI

void setURI(URI uri)
Sets the URI of this Address.

Parameters:
uri - new URI of this Address
Throws:
java.lang.IllegalStateException - if this Address is used in a context where it cannot be modified
java.lang.NullPointerException - on null uri.

isWildcard

boolean isWildcard()
Returns true if this Address represents the "wildcard" contact address. This is the case if it represents a Contact header whose string value is "*". Likewise, SipFactory.createAddress("*") always returns a wildcard Address instance.

Returns:
true if this Address represents the "wildcard" contact address, and false otherwise

getQ

float getQ()
Returns the value of the "q" parameter of this Address. 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 Address' qvalue or -1.0 if this is not set

setQ

void setQ(float q)
Sets this Addresss qvalue.

Parameters:
q - new qvalue for this Address 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

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

void setExpires(int seconds)
Sets the value of the "expires" parameter.

Parameters:
seconds - new relative value of the "expires" parameter. A negative value causes the "expires" parameter to be removed.

toString

java.lang.String toString()
Returns the value of this address as a String. The resulting string must be a valid value of a SIP From or To header.

Overrides:
toString in class java.lang.Object
Returns:
value of this Address as a String

clone

java.lang.Object clone()
Returns a clone of this Address. The cloned Address has identical display name, URI, and parameters, except that it has no tag parameter. This means the cloned address can be used as an argument to SipFactory.createRequest.

Specified by:
clone in interface Parameterable
Returns:
a clone of this Address

equals

boolean equals(java.lang.Object o)
Compares the given Address with this one.

As Addresses consist of a URI, an optional display name, and an optional set of name-value parameters, the following rules should be used for comparing them:

  1. URI (SipURI, TelURL, etc.) within the Address should be compared based on their respective equals() methods.
  2. Address parameters should be compared in the same way as URI parameters (as specified in RFC 3261 Section 19.1.4) with no restrictions for well-known URI params.
  3. display-names should be ignored in the comparison.

Specified by:
equals in interface Parameterable
Overrides:
equals in class java.lang.Object
Parameters:
o - given Parameterable to be compared with this.
Returns:
true if the two Addresses are equal.