Address

The Address interface represents SIP addresses, which are found in headers like From, To, and Contact. These addresses follow the syntax defined in RFC 3261, comprising a URI, an optional display name, and a set of name-value parameters. The interface is used for headers that contain one or more SIP addresses, including Route, Record-Route, Reply-To, and various informational or extension headers such as P-Asserted-Identity, P-Preferred-Identity, and Path. SIP addresses are important for sending requests as a User Agent Client (UAC) and redirecting incoming requests, such as call forwarding. Applications can construct Address objects using methods from SipFactory or retrieve them from SIP messages through methods like SipServletMessage.getAddressHeader and SipServletMessage.getAddressHeaders. Additionally, as an extension of the Parameterable interface, Address allows manipulation of associated parameters, making it flexible for handling SIP-specific requirements in headers.

Methods:

getDisplayName

java.lang.String getDisplayName()

Retrieves the display name associated with this Address. The display name represents a human-readable identifier, such as the real name of the caller or callee. User agents may render this display name when presenting alerts or call notifications.
Returns: the display name of the Address, or null if no display name is set.

setDisplayName

void setDisplayName(java.lang.String name)

Sets the display name for this Address. The display name is a human-readable name, such as the caller or callee's real name.
Parameters:
name: The display name to set for the Address.
Throws: IllegalStateException if the Address is used in a context where modifications are not allowed.

getURI

URI getURI()

Retrieves the URI component of this Address. For non-wildcard addresses, this method returns the associated URI. If the Address is a wildcard (as determined by isWildcard()), this method returns null.
Returns: the URI of this Address, or null if the Address is a wildcard.

setURI

void setURI(URI uri)

Sets the URI component for this Address. 
Parameters:
uri: The new URI to associate with the Address.
Throws: 
IllegalStateException if the Address is in a context where modifications are not allowed.
NullPointerException: If the provided uri is null.

isWildcard

boolean isWildcard()

Determines if this Address represents a "wildcard" contact address. A wildcard address is used in Contact headers and is represented by the string "*".
Returns:
true if this Address is a wildcard contact address, otherwise false.

getQ

float getQ()

Retrieves the value of the "q" parameter associated with this Address. The "qvalue" represents the relative preference among multiple locations, with values ranging from 0 to 1. Higher values indicate higher preference.
Returns:
The "qvalue" of this Address, or -1.0 if the parameter is not set.

setQ

void setQ(float q)

Sets the "qvalue" for this Address. The "qvalue" indicates the relative preference among a set of locations.
Parameters:
q: The new "qvalue" for this Address. Must be between 0.0 and 1.0 (inclusive) to indicate a preference level, or -1.0 to remove the "qvalue".
Throws:
IllegalArgumentException: If the specified "qvalue" is not between 0.0 and 1.0 (inclusive) and is not -1.0.

getExpires

int getExpires()

Retrieves the value of the "expires" parameter associated with this Address. The "expires" parameter specifies the duration in delta-seconds for which the Address is valid.
Returns: the value of the "expires" parameter in delta-seconds, or -1 if the parameter is not set.

setExpires

void setExpires(int seconds)

Sets the value of the "expires" parameter for this Address. This parameter specifies the relative validity duration of the Address in delta-seconds.
Parameters:
seconds: The new value for the "expires" parameter. A negative value removes the "expires" parameter.

toString

java.lang.String toString()

Returns the string representation of this Address. The resulting string is formatted as a valid value for a SIP From or To header.
Overrides: toString in class java.lang.Object.
Returns: The value of this Address as a String.

clone

java.lang.Object clone()

Creates a clone of this Address object. The cloned Address retains the same display name, URI, and parameters as the original, except for the tag parameter, which is not included. This makes the cloned Address suitable for use as an argument to methods like SipFactory.createRequest.
Specified by:
clone in interface Parameterable.
Returns:
A cloned instance of this Address.

equals

boolean equals(java.lang.Object o)

Compares this Address with the specified object to determine equality. The comparison follows these rules:

• The URI component (e.g., SipURI, TelURL) is compared using the equals() method of the respective URI type.
• Address parameters are compared as specified in RFC 3261, Section 19.1.4, without restrictions for well-known URI parameters.
• Display names are ignored in the comparison.

Specified by:
equals in interface Parameterable.
Overrides:
equals in class java.lang.Object.
Parameters:
o: The object to compare with this Address.
Returns:
true if the two Address objects are considered equal, otherwise false.