NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

gov.nist.javax.sip.address
Class SipUri

java.lang.Object
  extended by gov.nist.core.GenericObject
      extended by gov.nist.javax.sip.address.NetObject
          extended by gov.nist.javax.sip.address.GenericURI
              extended by gov.nist.javax.sip.address.SipUri
All Implemented Interfaces:
SipURIExt, Serializable, Cloneable, SipURI, URI, Parameters

public class SipUri
extends GenericURI
implements SipURI, SipURIExt

Implementation of the SipURI interface.

Version:
1.2 $Revision: 1.18 $ $Date: 2009/07/17 18:57:22 $
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.
 StringBuffer encode(StringBuffer buffer)
          Put the encoded version of this object in the given StringBuffer.
 boolean equals(Object that)
          Compare two URIs and return true if they are equal.
 Authority getAuthority()
          Get the authority.
 String getGrParam()
          Sets the gr parameter.
 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.
 gov.nist.core.NameValueList getParameters()
          Accessor for URI parameters
 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.
 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 hasGrParam()
          Returns whether the gr parameter is set.
 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 removeParameters()
          Remove the URI parameters.
 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 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 setGrParam(String value)
          Sets the gr parameter.
 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 Jean Deruelle: Updated to define equality of API methods, according to the rules in RFC3261 section 19.1.4 convert potential ie : %HEX HEX encoding parts of the URI before comparing them transport param added in comparison header equality enforced in comparison

encode

public String encode()
Construct a URL from the parsed structure.

Overrides:
encode in class GenericURI
Returns:
String

encode

public StringBuffer encode(StringBuffer buffer)
Description copied from class: gov.nist.core.GenericObject
Put the encoded version of this object in the given StringBuffer.

Overrides:
encode in class GenericURI

toString

public String toString()
Return a string representation.

Specified by:
toString in interface SipURI
Specified by:
toString in interface URI
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.

getParameters

public gov.nist.core.NameValueList getParameters()
Accessor for URI parameters

Returns:
A name-value list containing the parameters.

removeParameters

public void removeParameters()
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).

Specified by:
removeHeader in interface SipURIExt
Parameters:
name - name of the header to remove.

removeHeaders

public void removeHeaders()
Remove all headers.

Specified by:
removeHeaders in interface SipURIExt

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
Overrides:
clone in class gov.nist.core.GenericObject
Returns:
a deep copy of 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.

hasGrParam

public boolean hasGrParam()
Returns whether the gr parameter is set. Not part on the interface since gruu is not part of the base RFC3261.

Specified by:
hasGrParam in interface SipURIExt

setGrParam

public void setGrParam(String value)
Sets the gr parameter. Not part on the interface since gruu is not part of the base RFC3261.

Specified by:
setGrParam in interface SipURIExt
Parameters:
value - -- the GRUU param value.

getGrParam

public String getGrParam()
Sets the gr parameter. Not part on the interface since gruu is not part of the base RFC3261.


NIST-SIP: The Reference Implementation for JAIN-SIP 1.2

A product of the NIST/ITL Advanced Networking Technologies Division.
See conditions of use.
Submit a bug report or feature request.