javax.sip.address

Interface SipURI

All Superinterfaces:

Cloneable, Parameters, Serializable, URI

All Known Subinterfaces:

SipURIExt

All Known Implementing Classes:

SipUri

public interface SipURI
extends URI, Parameters

This class represents SIP URIs, that may have either a sip: or sips: scheme. All SIP implementations MUST support the sip: URI scheme.

SIP and SIPS URIs are used for addressing. They are similar to email addresses in that they are of the form user@host where user is either a user name or telephone number, and host is a host or domain name, or a numeric IP address. Additionally, SIP and SIPS URIs may contain parameters and headers (although headers are not legal in all contexts). A SipURI can be embedded in web pages, business cards or other hyperlinks to indicate that a particular user or service can be called via SIP.

Within a SIP Message, SipURIs are used to indicate the source and intended destination of a Request, redirection addresses and the current destination of a Request. Normally all these Headers will contain SipURIs.

Syntactically, SIP and SIPS URIs are identical except for the name of the URI scheme. The semantics differs in that the SIPS scheme implies that the identified resource is to be contacted using TLS. Because SIP and SIPS URIs are syntactically identical and because they're used the same way, they're both represented by the SipURI interface.

The SipURI interface extends the generic URI interface and provides additional convenience methods for the following components of a SipURI address, above the generic URI interface:

• User - The set of valid telephone-subscriber strings is a subset of valid user strings. The user URI parameter exists to distinguish telephone numbers from user names that happen to look like telephone numbers. If the user string contains a telephone number formatted as a telephone-subscriber, the user parameter value "phone" SHOULD be present. Even without this parameter, recipients of SIP and SIPS URIs MAY interpret the pre-@ part as a telephone number if local restrictions on the name space for user name allow it.
• UserPassword - A password associated with the user. While the SIP and SIPS URI syntax allows this field to be present, its use is NOT RECOMMENDED, because the passing of authentication information in clear text (such as URIs) has proven to be a security risk in almost every case where it has been used. For instance, transporting a PIN number in this field exposes the PIN.
• URI parameters - Parameters affecting a request constructed from this URI. URI parameters are added after the hostport component and are separated by semi-colons. URI parameters take the form:
  parameter-name "=" parameter-value
  Even though an arbitrary number of URI parameters may be included in a URI, any given parameter-name MUST NOT appear more than once. The SipURI interface also provides convenience methods for the manipulation of popular parameters in a SipURI address, namely:
  • Lr Parameter - the element responsible for this resource implements the routing mechanisms specified in RFC 3261.
  • Method - The method of the SIP request constructed from the URI.
  • MAddr Parameter - the server address to be contacted for this user.
  • TTL Parameter - the time-to-live value when packets are sent using UDP multicast.
  • User Parameter - the set of valid telephone-subscriber strings.
  • Transport Parameter - specifies which transport protocol to use for sending requests and responses to this entity
• URI Headers - Header fields to be included in a request constructed from the URI. Headers fields in the SIP request can be specified with the "?" mechanism within a URI. The header names and values are encoded in ampersand separated 'hname = hvalue' pairs. The special hname "body" indicates that the associated hvalue is the message-body of the SIP request.
• Secure - This determines if the scheme of this URI is either sip: or sips:, where sips: is secure.

See section 19.1.2 of RFC3261 for the use of SIP and SIPS URI components based on the context in which the URI appears.

Version:

1.2

Author:

BEA Systems, NIST

See Also:

FromHeader, ToHeader, ContactHeader, URI

Method Summary

Methods

Modifier and Type	Method and Description
String	getHeader(String name) Returns the value of the named header, or null if it is not set.
Iterator	getHeaderNames() Returns an Iterator over the String names of all headers present in this SipURI.
String	getHost() Returns the host part of this SipURI.
String	getMAddrParam() Returns the value of the maddr parameter, or null if this is not set.
String	getMethodParam() Returns the value of the method parameter, or null if this is not set.
int	getPort() Returns the port part of this SipURI.
String	getTransportParam() Returns the value of the "transport" parameter, or null if this is not set.
int	getTTLParam() Returns the value of the "ttl" parameter, or -1 if this is not set.
String	getUser() Returns the user part of this SipURI.
String	getUserParam() Returns the value of the userParam, or null if this is not set.
String	getUserPassword() Gets user password of SipURI, or null if it is not set.
boolean	hasLrParam() Returns whether the the lr parameter is set.
boolean	isSecure() Returns true if this SipURI is secure i.e.
void	removePort() Removes the port part of this SipURI.
void	setHeader(String name, String value) Sets the value of the specified header fields to be included in a request constructed from the URI.
void	setHost(String host) Set the host part of this SipURI to the newly supplied host parameter.
void	setLrParam() Sets the value of the lr parameter of this SipURI.
void	setMAddrParam(String mAddr) Sets the value of the maddr parameter of this SipURI.
void	setMethodParam(String method) Sets the value of the method parameter.
void	setPort(int port) Set the port part of this SipURI to the newly supplied port parameter.
void	setSecure(boolean secure) Sets the scheme of this URI to sip or sips depending on whether the argument is true or false.
void	setTransportParam(String transport) Sets the value of the "transport" parameter.
void	setTTLParam(int ttl) Sets the value of the ttl parameter.
void	setUser(String user) Sets the user of SipURI.
void	setUserParam(String userParam) Sets the value of the user parameter.
void	setUserPassword(String userPassword) Sets the user password associated with the user of SipURI.
String	toString() This method returns the URI as a string.

Methods inherited from interface javax.sip.address.URI

clone, getScheme, isSipURI

Methods inherited from interface javax.sip.header.Parameters

getParameter, getParameterNames, removeParameter, setParameter

Method Detail

setUser

void setUser(String user)
             throws ParseException

Sets the user of SipURI. The identifier of a particular resource at the host being addressed. The user and the user password including the '@' sign make up the user-info.

Parameters:

user - - the new String value of the user.

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the user value.

getUser

String getUser()

Returns the user part of this SipURI.

Returns:

the user part of this SipURI, this value may be null.

setUserPassword

void setUserPassword(String userPassword)
                     throws ParseException

Sets the user password associated with the user of SipURI. While the SIP and SIPS URI syntax allows this field to be present, its use is NOT RECOMMENDED, because the passing of authentication information in clear text (such as URIs) has proven to be a security risk in almost every case where it has been used. The user password and the user including the @ sign make up the user-info.

Parameters:

userPassword - - the new String value of the user password

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the userPassword value.

getUserPassword

String getUserPassword()

Gets user password of SipURI, or null if it is not set.

Returns:

the user password of this SipURI

isSecure

boolean isSecure()

Returns true if this SipURI is secure i.e. if this SipURI represents a sips URI. A sip URI returns false.

Returns:

true if this SipURI represents a sips URI, and false if it represents a sip URI.

setSecure

void setSecure(boolean secure)

Sets the scheme of this URI to sip or sips depending on whether the argument is true or false. The default value is false.

Parameters:

secure - - the boolean value indicating if the SipURI is secure.

setHost

void setHost(String host)
             throws ParseException

Set the host part of this SipURI to the newly supplied host parameter.

Parameters:

host - - the new interger value of the host of this SipURI

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the host value.

getHost

String getHost()

Returns the host part of this SipURI.

Returns:

the host part of this SipURI

setPort

void setPort(int port)

Set the port part of this SipURI to the newly supplied port parameter.

Parameters:

port - - the new interger value of the port of this SipURI

getPort

int getPort()

Returns the port part of this SipURI.

Returns:

the port part of this SipURI

removePort

void removePort()

Removes the port part of this SipURI. If no port is specified the stack will assume the default port.

getHeader

String getHeader(String name)

Returns the value of the named header, or null if it is not set. SIP/SIPS URIs may specify headers. As an example, the URI sip:jimmy@jcp.org?priority=urgent has a header "priority" whose value is "urgent".

Parameters:

name - name of header to retrieve

Returns:

the value of specified header

setHeader

void setHeader(String name,
             String value)
               throws ParseException

Sets the value of the specified header fields to be included in a request constructed from the URI. If the header already had a value it will be overwritten.

Parameters:

name - - a String specifying the header name

value - - a String specifying the header value

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the name or value parameters.

getHeaderNames

Iterator getHeaderNames()

Returns an Iterator over the String names of all headers present in this SipURI.

Returns:

an Iterator over all the header names

getTransportParam

String getTransportParam()

Returns the value of the "transport" parameter, or null if this is not set. This is equivalent to getParameter("transport").

Returns:

the transport paramter of the SipURI

setTransportParam

void setTransportParam(String transport)
                       throws ParseException

Sets the value of the "transport" parameter. This parameter specifies which transport protocol to use for sending requests and responses to this entity. The following values are defined: "udp", "tcp", "sctp", "tls", but other values may be used also. This method is equivalent to setParameter("transport", transport). Transport parameter constants are defined in the ListeningPoint.

Parameters:

transport - - new value for the "transport" parameter

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the transport value.

getTTLParam

int getTTLParam()

Returns the value of the "ttl" parameter, or -1 if this is not set. This method is equivalent to getParameter("ttl").

Returns:

the value of the ttl parameter

setTTLParam

void setTTLParam(int ttl)
                 throws InvalidArgumentException

Sets the value of the ttl parameter. The ttl parameter specifies the time-to-live value when packets are sent using UDP multicast. This is equivalent to setParameter("ttl", ttl).

Parameters:

ttl - - new value of the ttl parameter

Throws:

InvalidArgumentException - if supplied value is less than zero, excluding -1 the default not set value.

getMethodParam

String getMethodParam()

Returns the value of the method parameter, or null if this is not set. This is equivalent to getParameter("method").

Returns:

the value of the method parameter

setMethodParam

void setMethodParam(String method)
                    throws ParseException

Sets the value of the method parameter. This specifies which SIP method to use in requests directed at this URI. This is equivalent to setParameter("method", method).

Parameters:

method - - new value String value of the method parameter

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the method value.

setUserParam

void setUserParam(String userParam)
                  throws ParseException

Sets the value of the user parameter. The user URI parameter exists to distinguish telephone numbers from user names that happen to look like telephone numbers. This is equivalent to setParameter("user", user).

Parameters:

userParam - - new value String value of the method parameter

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the userParam value.

getUserParam

String getUserParam()

Returns the value of the userParam, or null if this is not set.

This is equivalent to getParameter("user").

Returns:

the value of the userParam of the SipURI

getMAddrParam

String getMAddrParam()

Returns the value of the maddr parameter, or null if this is not set. This is equivalent to getParameter("maddr").

Returns:

the value of the maddr parameter

setMAddrParam

void setMAddrParam(String mAddr)
                   throws ParseException

Sets the value of the maddr parameter of this SipURI. The maddr parameter indicates the server address to be contacted for this user, overriding any address derived from the host field. This is equivalent to setParameter("maddr", maddr).

Parameters:

mAddr - new value of the maddr parameter

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the mAddr value.

hasLrParam

boolean hasLrParam()

Returns whether the the lr parameter is set. This is equivalent to hasParameter("lr"). This interface has no getLrParam as RFC3261 does not specify any values for the "lr" paramater.

Returns:

true if the "lr" parameter is set, false otherwise.

setLrParam

void setLrParam()

Sets the value of the lr parameter of this SipURI. The lr parameter, when present, indicates that the element responsible for this resource implements the routing mechanisms specified in RFC 3261. This parameter will be used in the URIs proxies place in the Record-Route header field values, and may appear in the URIs in a pre-existing route set.

toString

String toString()

This method returns the URI as a string.

Specified by:

toString in interface URI

Overrides:

toString in class Object

Returns:

the stringified version of the URI