javax.servlet.sip
Interface Address

All Superinterfaces:

java.lang.Cloneable

public interface Address

extends java.lang.Cloneable

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-params)
 

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.
java.lang.String	getDisplayName() Returns the display name of this Address.
int	getExpires() Returns the value of the "expires" parameter as delta-seconds.
java.lang.String	getParameter(java.lang.String name) Returns the value of the specified parameter.
java.util.Iterator	getParameterNames() Returns an Iterator over the set of all parameters of this address.
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	removeParameter(java.lang.String name) Removes the parameter with the specified name.
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	setParameter(java.lang.String name, java.lang.String value) Sets the value of the specified 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.

Method Detail

getDisplayName

public 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

public 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

public 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

public 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

getParameter

public java.lang.String getParameter(java.lang.String name)

Returns the value of the specified parameter. A zero-length String indicates flag parameter.

Parameters:

name - the name of the parameter

Returns:

the value of the specified parameter

setParameter

public void setParameter(java.lang.String name,
                         java.lang.String value)

Sets the value of the specified parameter. A zero-length String indicates flag parameter.

Parameters:

name - parameter name

value - parameter value

Throws:

java.lang.IllegalStateException - if this Address is used in a context where it cannot be modified

removeParameter

public void removeParameter(java.lang.String name)

Removes the parameter with the specified name.

Parameters:

name - parameter name

Throws:

java.lang.IllegalStateException - if this Address is used in a context where it cannot be modified

getParameterNames

public java.util.Iterator getParameterNames()

Returns an Iterator over the set of all parameters of this address.

Returns:

an Iterator over the set of String objects that are the names of parameters of this Address

isWildcard

public 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

public 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

public 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

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. A negative value causes the "expires" parameter to be removed.

toString

public 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

public 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.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this Address