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.