gov.nist.javax.sip.address
Class SipUri

java.lang.Object
  gov.nist.core.GenericObject
      gov.nist.javax.sip.address.NetObject
          gov.nist.javax.sip.address.GenericURI
              gov.nist.javax.sip.address.SipUri

All Implemented Interfaces:

Cloneable, Parameters, Serializable, SipURI, URI

public class SipUri

extends GenericURI

implements SipURI

Implementation of the SipURI interface.

Version:

1.2 $Revision: 1.10 $ $Date: 2006/11/01 02:23:09 $

Author:

M. Ranganathan

See Also:

Serialized Form

Field Summary

Fields inherited from class gov.nist.javax.sip.address.GenericURI

ISUB, PHONE_CONTEXT_TAG, POSTDIAL, PROVIDER_TAG, SIP, SIPS, TEL

Constructor Summary

SipUri()

Method Summary

void	clearPassword() Clear the password from the user part if it exists.
void	clearQheaders() Clear all Qheaders.
void	clearUriParms() clear all URI Parameters.
Object	clone() clone this.
String	encode() Construct a URL from the parsed structure.
boolean	equals(Object that) Compare two URIs and return true if they are equal.
Authority	getAuthority() Get the authority.
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 names (Strings) of all headers present in this SipURI.
String	getHost() Get the host protion of the URI.
gov.nist.core.HostPort	getHostPort() Get the host and port of the server.
String	getLrParam() Returns the value of the lr parameter, or null if this is not set.
String	getMAddrParam() Returns the value of the maddr parameter, or null if this is not set.
String	getMethod() Get the method parameter.
String	getMethodParam() Returns the value of the method parameter, or null if this is not set.
String	getParameter(String name) Returns the value of the named parameter, or null if it is not set.
Iterator	getParameterNames() Returns an Iterator over the names (Strings) of all parameters present in this ParametersHeader.
Object	getParm(String parmname) get the parameter (do a name lookup) and return null if none exists.
int	getPort() Get the port from the authority field.
gov.nist.core.NameValueList	getQheaders() Accessor forSIPObjects
String	getScheme() Get the scheme.
TelephoneNumber	getTelephoneSubscriber() Returns the stucture corresponding to the telephone number provided that the user is a telephone subscriber.
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.
gov.nist.core.NameValueList	getUriParms() Accessor for URI parameters
String	getUser() Returns the value of the userParam, or null if this is not set.
String	getUserAtHost() getUser@host
String	getUserAtHostPort() getUser@host
String	getUserParam() Returns the user part of this SipURI, or null if it is not set.
String	getUserPassword() Get the password of the user.
String	getUserType() Get the urse parameter.
boolean	hasLrParam() Returns whether the the lr parameter is set.
boolean	hasParameter(String name) Boolean to check if a parameter of a given name exists.
boolean	hasTransport() Return true if the transport parameter is defined.
boolean	isSecure() Returns true if this SipURI is secure i.e. if this SipURI represents a sips URI.
boolean	isSipURI() This method determines if this is a URI with a scheme of "sip" or "sips".
boolean	isUserTelephoneSubscriber() returns true if the user is a telephone subscriber.
void	removeHeader(String name) Remove a header given its name (provided it exists).
void	removeHeaders() Remove all headers.
void	removeMAddr() Remove the maddr param if it exists.
void	removeMethod() remove the Method.
void	removeParameter(String name) Remove a parameter given its name
void	removePort() remove the port setting.
void	removeTransport() Delete the transport string.
void	removeTTL() remove the ttl value from the parameter list if it exists.
void	removeUriParms() Remove the URI parameters.
void	removeUser() Remove the user.
void	removeUserType() Set the user type.
void	setAuthority(Authority authority) Set the authority member
void	setDefaultParm(String name, Object value) Set the default parameters for this URI.
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(gov.nist.core.Host h) Set the host for this URI.
void	setHost(String host) Set the host portion of the SipURI
void	setHostPort(gov.nist.core.HostPort hostPort) Set the hostPort field of the imbedded authority field.
void	setIsdnSubAddress(String isdnSubAddress) Sets ISDN subaddress of SipURL
void	setLrParam() Sets the value of the lr parameter of this SipURI.
void	setMAddr(String mAddr) Set the MADDR parameter .
void	setMAddrParam(String maddr) Sets the value of the maddr parameter of this SipURI.
void	setMethod(String method) Set the Method
void	setMethodParam(String method) Sets the value of the method parameter.
void	setParameter(String name, String value) Sets the value of the specified parameter.
void	setPort(int p) set the port to a given value.
void	setQHeader(gov.nist.core.NameValue nameValue) Set the query header when provided as a name-value pair.
void	setQheaders(gov.nist.core.NameValueList parms) Set the qheaders member
void	setScheme(String scheme) Constructor given the scheme.
void	setSecure(boolean secure) Sets the scheme of this URI to sip or sips depending on whether the argument is true or false.
void	setTelephoneSubscriber(TelephoneNumber tel) Set the telephone subscriber field.
void	setTransportParam(String transport) Sets the value of the "transport" parameter.
void	setTTLParam(int ttl) Sets the value of the ttl parameter.
void	setUriParameter(gov.nist.core.NameValue nameValue) Set the parameter as given.
void	setUriParm(String name, Object value) Set a given URI parameter.
void	setUriParms(gov.nist.core.NameValueList parms) Set the uriParms member
void	setUser(String uname) Sets the user of SipURI.
void	setUserParam(String usertype) Sets the value of the user parameter.
void	setUserPassword(String password) Set the user password.
String	toString() Return a string representation.

Methods inherited from class gov.nist.javax.sip.address.GenericURI

hashCode

Methods inherited from class gov.nist.javax.sip.address.NetObject

debugDump, debugDump, match

Methods inherited from class gov.nist.core.GenericObject

getClassFromName, getMatcher, isMySubclass, makeClone, merge, setMatcher

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SipUri

public SipUri()

Method Detail

setScheme

public void setScheme(String scheme)

Constructor given the scheme. The scheme must be either Sip or Sips

getScheme

public String getScheme()

Get the scheme.

Specified by:

getScheme in interface URI

Overrides:

getScheme in class GenericURI

Returns:

the scheme paramter of the URI

clearUriParms

public void clearUriParms()

clear all URI Parameters.

Since:

v1.0

clearPassword

public void clearPassword()

Clear the password from the user part if it exists.

getAuthority

public Authority getAuthority()

Get the authority.

clearQheaders

public void clearQheaders()

Clear all Qheaders.

equals

public boolean equals(Object that)

Compare two URIs and return true if they are equal.

Overrides:

equals in class GenericURI

Parameters:

that - the object to compare to.

Returns:

true if the object is equal to this object. JvB: Updated to define equality in terms of API methods, according to the rules in RFC3261 section 19.1.4 TODO: Need to convert %HEX HEX encoding before comparing

encode

public String encode()

Construct a URL from the parsed structure.

Overrides:

encode in class GenericURI

Returns:

String

toString

public String toString()

Return a string representation.

Specified by:

toString in interface SipURI

Overrides:

toString in class GenericURI

Returns:

the String representation of this URI.

getUserAtHost

public String getUserAtHost()

getUser@host

Returns:

user@host portion of the uri (null if none exists). Peter Musgrave - handle null user

getUserAtHostPort

public String getUserAtHostPort()

getUser@host

Returns:

user@host portion of the uri (null if none exists).

getParm

public Object getParm(String parmname)

get the parameter (do a name lookup) and return null if none exists.

Parameters:

parmname - Name of the parameter to get.

Returns:

Parameter of the given name (null if none exists).

getMethod

public String getMethod()

Get the method parameter.

Returns:

Method parameter.

getUriParms

public gov.nist.core.NameValueList getUriParms()

Accessor for URI parameters

Returns:

A name-value list containing the parameters.

removeUriParms

public void removeUriParms()

Remove the URI parameters.

getQheaders

public gov.nist.core.NameValueList getQheaders()

Accessor forSIPObjects

Returns:

Get the query headers (that appear after the ? in the URL)

getUserType

public String getUserType()

Get the urse parameter.

Returns:

User parameter (user= phone or user=ip).

getUserPassword

public String getUserPassword()

Get the password of the user.

Specified by:

getUserPassword in interface SipURI

Returns:

User password when it embedded as part of the uri ( a very bad idea).

setUserPassword

public void setUserPassword(String password)

Set the user password.

Specified by:

setUserPassword in interface SipURI

Parameters:

password - - password to set.

getTelephoneSubscriber

public TelephoneNumber getTelephoneSubscriber()

Returns the stucture corresponding to the telephone number provided that the user is a telephone subscriber.

Returns:

TelephoneNumber part of the url (only makes sense when user = phone is specified)

getHostPort

public gov.nist.core.HostPort getHostPort()

Get the host and port of the server.

Returns:

get the host:port part of the url parsed into a structure.

getPort

public int getPort()

Get the port from the authority field.

Specified by:

getPort in interface SipURI

Returns:

the port from the authority field.

getHost

public String getHost()

Get the host protion of the URI.

Specified by:

getHost in interface SipURI

Returns:

the host portion of the url.

isUserTelephoneSubscriber

public boolean isUserTelephoneSubscriber()

returns true if the user is a telephone subscriber. If the host is an Internet telephony gateway, a telephone-subscriber field MAY be used instead of a user field. The telephone-subscriber field uses the notation of RFC 2806 [19]. Any characters of the un-escaped "telephone-subscriber" that are not either in the set "unreserved" or "user-unreserved" MUST be escaped. The set of characters not reserved in the RFC 2806 description of telephone-subscriber contains a number of characters in various syntax elements that need to be escaped when used in SIP URLs, for example quotation marks (%22), hash (%23), colon (%3a), at-sign (%40) and the "unwise" characters, i.e., punctuation of %5b and above. The telephone number is a special case of a user name and cannot be distinguished by a BNF. Thus, a URL parameter, user, is added to distinguish telephone numbers from user names. The user parameter value "phone" indicates that the user part contains a telephone number. Even without this parameter, recipients of SIP URLs MAY interpret the pre-@ part as a telephone number if local restrictions on the

Returns:

true if the user is a telephone subscriber.

removeTTL

public void removeTTL()

remove the ttl value from the parameter list if it exists.

removeMAddr

public void removeMAddr()

Remove the maddr param if it exists.

removeTransport

public void removeTransport()

Delete the transport string.

removeHeader

public void removeHeader(String name)

Remove a header given its name (provided it exists).

Parameters:

name - name of the header to remove.

removeHeaders

public void removeHeaders()

Remove all headers.

removeUserType

public void removeUserType()

Set the user type.

removePort

public void removePort()

remove the port setting.

Specified by:

removePort in interface SipURI

removeMethod

public void removeMethod()

remove the Method.

setUser

public void setUser(String uname)

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

Specified by:

setUser in interface SipURI

Parameters:

uname - The new String value of the user.

Throws:

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

removeUser

public void removeUser()

Remove the user.

setDefaultParm

public void setDefaultParm(String name,
                           Object value)

Set the default parameters for this URI. Do nothing if the parameter is already set to some value. Otherwise set it to the given value.

Parameters:

name - Name of the parameter to set.

value - value of the parameter to set.

setAuthority

public void setAuthority(Authority authority)

Set the authority member

Parameters:

authority - Authority to set.

setHost

public void setHost(gov.nist.core.Host h)

Set the host for this URI.

Parameters:

h - host to set.

setUriParms

public void setUriParms(gov.nist.core.NameValueList parms)

Set the uriParms member

Parameters:

parms - URI parameters to set.

setUriParm

public void setUriParm(String name,
                       Object value)

Set a given URI parameter. Note - parameter must be properly encoded before the function is called.

Parameters:

name - Name of the parameter to set.

value - value of the parameter to set.

setQheaders

public void setQheaders(gov.nist.core.NameValueList parms)

Set the qheaders member

Parameters:

parms - query headers to set.

setMAddr

public void setMAddr(String mAddr)

Set the MADDR parameter .

Parameters:

mAddr - Host Name to set

setUserParam

public void setUserParam(String usertype)

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

Specified by:

setUserParam in interface SipURI

Parameters:

usertype - New value String value of the method parameter

setMethod

public void setMethod(String method)

Set the Method

Parameters:

method - method parameter

setIsdnSubAddress

public void setIsdnSubAddress(String isdnSubAddress)

Sets ISDN subaddress of SipURL

Parameters:

isdnSubAddress - ISDN subaddress

setTelephoneSubscriber

public void setTelephoneSubscriber(TelephoneNumber tel)

Set the telephone subscriber field.

Parameters:

tel - Telephone subscriber field to set.

setPort

public void setPort(int p)

set the port to a given value.

Specified by:

setPort in interface SipURI

Parameters:

p - Port to set.

hasParameter

public boolean hasParameter(String name)

Boolean to check if a parameter of a given name exists.

Parameters:

name - Name of the parameter to check on.

Returns:

a boolean indicating whether the parameter exists.

setQHeader

public void setQHeader(gov.nist.core.NameValue nameValue)

Set the query header when provided as a name-value pair.

Parameters:

nameValue - qeuery header provided as a name,value pair.

setUriParameter

public void setUriParameter(gov.nist.core.NameValue nameValue)

Set the parameter as given.

Parameters:

nameValue - - parameter to set.

hasTransport

public boolean hasTransport()

Return true if the transport parameter is defined.

Returns:

true if transport appears as a parameter and false otherwise.

removeParameter

public void removeParameter(String name)

Remove a parameter given its name

Specified by:

removeParameter in interface Parameters

Parameters:

name - -- name of the parameter to remove.

setHostPort

public void setHostPort(gov.nist.core.HostPort hostPort)

Set the hostPort field of the imbedded authority field.

Parameters:

hostPort - is the hostPort to set.

clone

public Object clone()

clone this.

Specified by:

clone in interface URI

getHeader

public 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:joe@jcp.org?priority=urgent has a header "priority" whose value is "urgent".

Specified by:

getHeader in interface SipURI

Parameters:

name - name of header to retrieve

Returns:

the value of specified header

getHeaderNames

public Iterator getHeaderNames()

Returns an Iterator over the names (Strings) of all headers present in this SipURI.

Specified by:

getHeaderNames in interface SipURI

Returns:

an Iterator over all the header names

getLrParam

public String getLrParam()

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

Returns:

the value of the lr parameter

getMAddrParam

public String getMAddrParam()

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

Specified by:

getMAddrParam in interface SipURI

Returns:

the value of the maddr parameter

getMethodParam

public String getMethodParam()

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

Specified by:

getMethodParam in interface SipURI

Returns:

the value of the method parameter

getParameter

public String getParameter(String name)

Returns the value of the named parameter, or null if it is not set. A zero-length String indicates flag parameter.

Specified by:

getParameter in interface Parameters

Parameters:

name - name of parameter to retrieve

Returns:

the value of specified parameter

getParameterNames

public Iterator getParameterNames()

Returns an Iterator over the names (Strings) of all parameters present in this ParametersHeader.

Specified by:

getParameterNames in interface Parameters

Returns:

an Iterator over all the parameter names

getTTLParam

public int getTTLParam()

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

Specified by:

getTTLParam in interface SipURI

Returns:

the value of the ttl parameter

getTransportParam

public String getTransportParam()

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

Specified by:

getTransportParam in interface SipURI

Returns:

the transport paramter of the SipURI

getUser

public String getUser()

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

This is equivalent to getParameter("user").

Specified by:

getUser in interface SipURI

Returns:

the value of the userParam of the SipURI

isSecure

public boolean isSecure()

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

Specified by:

isSecure in interface SipURI

Returns:

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

isSipURI

public boolean isSipURI()

This method determines if this is a URI with a scheme of "sip" or "sips".

Specified by:

isSipURI in interface URI

Overrides:

isSipURI in class GenericURI

Returns:

true if the scheme is "sip" or "sips", false otherwise.

setHeader

public void setHeader(String name,
                      String value)

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.

Specified by:

setHeader in interface SipURI

Parameters:

name - - a String specifying the header name

value - - a String specifying the header value

setHost

public void setHost(String host)
             throws ParseException

Set the host portion of the SipURI

Specified by:

setHost in interface SipURI

Parameters:

host - host to set.

Throws:

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

setLrParam

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

Specified by:

setLrParam in interface SipURI

setMAddrParam

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

Specified by:

setMAddrParam in interface SipURI

Parameters:

maddr - New value of the maddr parameter

Throws:

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

setMethodParam

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

Specified by:

setMethodParam in interface SipURI

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.

setParameter

public void setParameter(String name,
                         String value)
                  throws ParseException

Sets the value of the specified parameter. If the parameter already had a value it will be overwritten. A zero-length String indicates flag parameter.

Specified by:

setParameter in interface Parameters

Parameters:

name - - a String specifying the parameter name

value - - a String specifying the parameter value

Throws:

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

setSecure

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

Specified by:

setSecure in interface SipURI

Parameters:

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

setTTLParam

public void setTTLParam(int ttl)

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

Specified by:

setTTLParam in interface SipURI

Parameters:

ttl - - new value of the ttl parameter

setTransportParam

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

Specified by:

setTransportParam in interface SipURI

Parameters:

transport - - new value for the "transport" parameter

Throws:

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

See Also:

ListeningPoint

getUserParam

public String getUserParam()

Returns the user part of this SipURI, or null if it is not set.

Specified by:

getUserParam in interface SipURI

Returns:

the user part of this SipURI

hasLrParam

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

Specified by:

hasLrParam in interface SipURI

Returns:

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