jain.protocol.ip.sip
Class SipURL

java.lang.Object
  |
  +--jain.protocol.ip.sip.URI
        |
        +--jain.protocol.ip.sip.SipURL

public final class SipURL

extends URI

implements java.lang.Cloneable

This class represents a SIP URL. SipURLs are used within SIP Messages to indicate the originator (FromHeader), current destination (RequestURI) and final recipient (ToHeader) of a SIP RequestMessage, and to specify redirection addresses (ContactHeader). A SipURL can also be embedded in web pages or other hyperlinks to indicate that a particular user or service can be called via SIP. When used as a hyperlink, the SipURL indicates the use of the INVITE method.

The SipURL scheme is defined to allow setting RequestHeaders and the message-body. This corresponds to the use of mailto: URLs. It makes it possible, for example, to specify the subject, urgency or media types of calls initiated through a web page or as part of an email message.

The components of the SipURL have the following meanings:

UserName: If the host is an Internet telephony gateway, the UserName may also encode a telephone number. Thus, a URL parameter, UserType, is added to distinguish telephone numbers from user names. The phone identifier is to be used when connecting to a telephony gateway. Even without this parameter, recipients of SipURLs may interpret the UserName part as a phone number if local restrictions on the name space for user name allow it.

UserPassword: The use of passwords in the userinfo 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.

Host: The mailto: URL and RFC 822 email addresses require that numeric host addresses ("host numbers") are enclosed in square brackets (presumably, since host names might be numeric), while host numbers without brackets are used for all other URLs. The SipURL requires the latter form, without brackets.

Port: The port number to send a RequestMessage to.

URL parameters: SipURLs can define specific parameters of the RequestMessage. The Transport parameter determines the transport mechanism (UDP or TCP). UDP is to be assumed when no explicit transport parameter is included. The MAddr parameter provides the server address to be contacted for this user, overriding the address supplied in the host field. This address is typically a multicast address, but could also be the address of a backup server. The TTL parameter determines the time-to-live value of the UDP multicast packet and must only be used if maddr is a multicast address and the transport protocol is UDP. The UserType parameter was described above. The Transport, MAddr, and TTL parameters must not be used in the FromHeader, ToHeader and the RequestURI; they are ignored if present.

Headers: Headers of the SIP RequestMessage can be defined within a SIP URL. The special header name "body" indicates that the associated header value is the message-body of the SIP InviteMessage. Headers must not be used in the FromHeader, ToHeader and the RequestURI; they are ignored if present.

Method: The method of the SIP RequestMessage can be specified with the Method parameter. This parameter must not be used in the FromHeader, ToHeader and the RequestURI; they are ignored if present.

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

SipURLs are case-insensitive. All SipURL parameters are included when comparing for equality.

Version:

0.6

See Also:

InviteMessage, RequestMessage, FromHeader, ToHeader

Field Summary

static int	TTL_MAX Maximum value of TTL
static int	TTL_MIN Minimum value of TTL
static int	USER_TYPE_IP IP User Type
static int	USER_TYPE_PHONE Phone User Type

Constructor Summary

SipURL(java.net.InetAddress host)
Creates a SipURL based on given host

SipURL(java.lang.String user, java.net.InetAddress host)
Creates a SipURL based on given user and host

Method Summary

java.lang.Object	clone() Creates and returns a copy of SipURL
boolean	equals(SipURL sipURL) Indicates whether some other SipURL is "equal to" this one
java.lang.String	getExtension(java.lang.String extension) Gets the value of specified extension parameter in SipURL
java.lang.String[]	getExtensions() Gets an array of SipURL's extension parameter names
java.lang.String	getHeader(java.lang.String headerName) Gets the value of specified header in SipURL
java.lang.String[]	getHeaders() Gets an array of SipURL's header names
java.net.InetAddress	getHost() Gets host of SipURL
java.lang.String	getIsdnSubAddress() Gets ISDN subaddress of SipURL
java.net.InetAddress	getMAddr() Gets MAddr of SipURL
java.lang.String	getMethod() Gets method of SipURL
int	getPort() Gets port of SipURL
java.lang.String	getPostDial() Gets post dial of SipURL
java.lang.String	getSchemeData() Gets scheme data of SipURL
int	getTransport() Gets transport of SipURL
int	getTTL() Gets TTL of SipURL
java.lang.String	getUserName() Gets user name of SipURL
java.lang.String	getUserPassword() Gets user password of SipURL
int	getUserType() Gets user type of SipURL
boolean	hasExtension(java.lang.String extension) Returns boolean value indicating if SipURL has extension
boolean	hasExtensions() Returns boolean value indicating if SipURL has extensions
boolean	hasHeader(java.lang.String headerName) Returns boolean value indicating if SipURL has given header
boolean	hasHeaders() Returns boolean value indicating if SipURL has headers
boolean	hasIsdnSubAddress() Returns boolean value indicating if SipURL has ISDN subaddress
boolean	hasMAddr() Returns boolean value indicating if SipURL has MAddr
boolean	hasMethod() Returns boolean value indicating if SipURL has method
boolean	hasPort() Returns boolean value indicating if SipURL has port
boolean	hasPostDial() Returns boolean value indicating if SipURL has post dial
boolean	hasTransport() Returns boolean value indicating if SipURL has transport
boolean	hasTTL() Returns boolean value indicating if SipURL has TTL
boolean	hasUserName() Returns boolean value indicating if SipURL has user name
boolean	hasUserPassword() Returns boolean value indicating if SipURL has user password
boolean	hasUserType() Returns boolean value indicating if SipURL has user type
boolean	isGlobal() Returns boolean value to indicate if the SipURL has a global phone user
void	removeExtension(java.lang.String extension) Removes extension from SipURL
void	removeExtensions() Removes all extensions from SipURL
void	removeHeader(java.lang.String headerName) Removes header from SipURL
void	removeHeaders() Removes all headers from SipURL
void	removeIsdnSubAddress() Removes ISDN subaddress from SipURL
void	removeMAddr() Removes MAddr from SipURL
void	removeMethod() Removes method from SipURL
void	removePort() Removes port from SipURL
void	removePostDial() Removes post dial from SipURL
void	removeTransport() Removes transport from SipURL
void	removeTTL() Removes TTL from SipURL
void	removeUserPassword() Removes user password from SipURL
void	removeUserType() Removes user type from SipURL
void	setExtension(java.lang.String extension, java.lang.String value) Sets value of extension parameterin SipURL
void	setGlobal(boolean global) Sets phone user of SipURL to be global or local
void	setHeader(java.lang.String headerName, java.lang.String headerValue) Sets header of SipURL
void	setHost(java.net.InetAddress host) Sets host of SipURL
void	setIsdnSubAddress(java.lang.String isdnSubAddress) Sets ISDN subaddress of SipURL
void	setMAddr(java.net.InetAddress mAddr) Sets MAddr of SipURL
void	setMethod(java.lang.String method) Sets method of SipURL
void	setPort(int port) Sets port of SipURL
void	setPostDial(java.lang.String postDial) Sets post dial of SipURL
void	setTransport(int transport) Sets transport of SipURL
void	setTTL(int ttl) Sets TTL of SipURL
void	setUserName(java.lang.String userName) Sets user name of SipURL
void	setUserPassword(java.lang.String userPassword) Sets user password of SipURL
void	setUserType(int userType) Sets user type of SipURL
java.lang.String	toString() Gets string representation of SipURL

Methods inherited from class jain.protocol.ip.sip.URI

equals, getScheme, setScheme, setSchemeData

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

USER_TYPE_IP

public static final int USER_TYPE_IP

IP User Type

USER_TYPE_PHONE

public static final int USER_TYPE_PHONE

Phone User Type

TTL_MIN

public static final int TTL_MIN

Minimum value of TTL

TTL_MAX

public static final int TTL_MAX

Maximum value of TTL

Constructor Detail

SipURL

public SipURL(java.net.InetAddress host)
       throws java.lang.IllegalArgumentException

Creates a SipURL based on given host

Parameters:

host - host

Throws:

java.lang.IllegalArgumentException - if host is null

SipURL

public SipURL(java.lang.String user,
              java.net.InetAddress host)
       throws java.lang.IllegalArgumentException

Creates a SipURL based on given user and host

Parameters:

user - user

host - host

Throws:

java.lang.IllegalArgumentException - if user is null or zero-length, or if host is null

Method Detail

removePort

public void removePort()

Removes port from SipURL

hasTransport

public boolean hasTransport()

Returns boolean value indicating if SipURL has transport

Returns:

boolean value indicating if SipURL has transport

hasMethod

public boolean hasMethod()

Returns boolean value indicating if SipURL has method

Returns:

boolean value indicating if SipURL has method

hasPort

public boolean hasPort()

Returns boolean value indicating if SipURL has port

Returns:

boolean value indicating if SipURL has port

hasIsdnSubAddress

public boolean hasIsdnSubAddress()

Returns boolean value indicating if SipURL has ISDN subaddress

Returns:

boolean value indicating if SipURL has ISDN subaddress

getIsdnSubAddress

public java.lang.String getIsdnSubAddress()
                                   throws ParameterNotSetException

Gets ISDN subaddress of SipURL

Returns:

ISDN subaddress of SipURL

Throws:

ParameterNotSetException - if ISDN subaddress does not exist

hasPostDial

public boolean hasPostDial()

Returns boolean value indicating if SipURL has post dial

Returns:

boolean value indicating if SipURL has post dial

getPostDial

public java.lang.String getPostDial()
                             throws ParameterNotSetException

Gets post dial of SipURL

Returns:

post dial of SipURL

Throws:

ParameterNotSetException - if post dial does not exist

hasTTL

public boolean hasTTL()

Returns boolean value indicating if SipURL has TTL

Returns:

boolean value indicating if SipURL has TTL

hasMAddr

public boolean hasMAddr()

Returns boolean value indicating if SipURL has MAddr

Returns:

boolean value indicating if SipURL has MAddr

hasUserType

public boolean hasUserType()

Returns boolean value indicating if SipURL has user type

Returns:

boolean value indicating if SipURL has user type

hasUserName

public boolean hasUserName()

Returns boolean value indicating if SipURL has user name

Returns:

boolean value indicating if SipURL has user name

hasUserPassword

public boolean hasUserPassword()

Returns boolean value indicating if SipURL has user password

Returns:

boolean value indicating if SipURL has user password

hasHeaders

public boolean hasHeaders()

Returns boolean value indicating if SipURL has headers

Returns:

boolean value indicating if SipURL has headers

hasHeader

public boolean hasHeader(java.lang.String headerName)

Returns boolean value indicating if SipURL has given header

Returns:

boolean value indicating if SipURL has given header

getUserName

public java.lang.String getUserName()
                             throws ParameterNotSetException

Gets user name of SipURL

Returns:

user name of SipURL

Throws:

ParameterNotSetException - if user name does not exist

setUserName

public void setUserName(java.lang.String userName)
                 throws java.lang.IllegalArgumentException

Sets user name of SipURL

Parameters:

userName - user name

Throws:

java.lang.IllegalArgumentException - if userName is null or zero-length

getUserPassword

public java.lang.String getUserPassword()
                                 throws ParameterNotSetException

Gets user password of SipURL

Returns:

user password of SipURL

Throws:

ParameterNotSetException - if user password does not exist

setUserPassword

public void setUserPassword(java.lang.String userPassword)
                     throws java.lang.IllegalArgumentException,
                            SipException

Sets user password of SipURL

Parameters:

userPassword - user password

Throws:

SipException - if user name does not exist

java.lang.IllegalArgumentException - if userPassword is null or zero-length

getHost

public java.net.InetAddress getHost()

Gets host of SipURL

Returns:

host of SipURL

setHost

public void setHost(java.net.InetAddress host)
             throws java.lang.IllegalArgumentException

Sets host of SipURL

Parameters:

host - host

Throws:

java.lang.IllegalArgumentException - if host is null

getPort

public int getPort()
            throws ParameterNotSetException

Gets port of SipURL

Returns:

port of SipURL

Throws:

ParameterNotSetException - if port does not exist

setPort

public void setPort(int port)
             throws java.lang.IllegalArgumentException

Sets port of SipURL

Parameters:

port - port

Throws:

java.lang.IllegalArgumentException - if xxx is negative

getTTL

public int getTTL()
           throws ParameterNotSetException

Gets TTL of SipURL

Returns:

TTL of SipURL

Throws:

ParameterNotSetException - if TTL does not exist

setTTL

public void setTTL(int ttl)
            throws java.lang.IllegalArgumentException

Sets TTL of SipURL

Parameters:

ttl - TTL

Throws:

java.lang.IllegalArgumentException - if ttl is negative

removeTTL

public void removeTTL()

Removes TTL from SipURL

getTransport

public int getTransport()
                 throws ParameterNotSetException

Gets transport of SipURL

Returns:

transport of SipURL

Throws:

ParameterNotSetException - if transport does not exist

setTransport

public void setTransport(int transport)
                  throws java.lang.IllegalArgumentException

Sets transport of SipURL

Parameters:

transport - transport

Throws:

java.lang.IllegalArgumentException - if transport is an invalid transport type

removeTransport

public void removeTransport()

Removes transport from SipURL

getUserType

public int getUserType()
                throws ParameterNotSetException

Gets user type of SipURL

Returns:

user type of SipURL

Throws:

ParameterNotSetException - if user type does not exist

setUserType

public void setUserType(int userType)
                 throws java.lang.IllegalArgumentException

Sets user type of SipURL

Parameters:

userType - user type

Throws:

java.lang.IllegalArgumentException - if userType is invalid user type

removeUserType

public void removeUserType()

Removes user type from SipURL

removeUserPassword

public void removeUserPassword()

Removes user password from SipURL

removeExtension

public void removeExtension(java.lang.String extension)

Removes extension from SipURL

removeExtensions

public void removeExtensions()

Removes all extensions from SipURL

removeHeader

public void removeHeader(java.lang.String headerName)

Removes header from SipURL

removeHeaders

public void removeHeaders()

Removes all headers from SipURL

getMethod

public java.lang.String getMethod()
                           throws ParameterNotSetException

Gets method of SipURL

Returns:

method of SipURL

Throws:

ParameterNotSetException - if method does not exist

setMethod

public void setMethod(java.lang.String method)
               throws java.lang.IllegalArgumentException

Sets method of SipURL

Parameters:

method - method

Throws:

java.lang.IllegalArgumentException - if method is null or zero-length

setIsdnSubAddress

public void setIsdnSubAddress(java.lang.String isdnSubAddress)
                       throws java.lang.IllegalArgumentException,
                              SipException

Sets ISDN subaddress of SipURL

Parameters:

isdnSubAddress - ISDN subaddress

Throws:

java.lang.IllegalArgumentException - if isdnSubAddress is null or zero-length

setPostDial

public void setPostDial(java.lang.String postDial)
                 throws java.lang.IllegalArgumentException,
                        SipException

Sets post dial of SipURL

Parameters:

postDial - post dial

Throws:

SipException - if user type is not USER_PHONE

java.lang.IllegalArgumentException - if postDial is null or zero-length

removeMethod

public void removeMethod()

Removes method from SipURL

getMAddr

public java.net.InetAddress getMAddr()
                              throws ParameterNotSetException

Gets MAddr of SipURL

Returns:

MAddr of SipURL

Throws:

ParameterNotSetException - if MAddr does not exist

setMAddr

public void setMAddr(java.net.InetAddress mAddr)
              throws java.lang.IllegalArgumentException

Sets MAddr of SipURL

Parameters:

mAddr - MAddr

Throws:

java.lang.IllegalArgumentException - if mAddr is null

removeMAddr

public void removeMAddr()

Removes MAddr from SipURL

removeIsdnSubAddress

public void removeIsdnSubAddress()

Removes ISDN subaddress from SipURL

removePostDial

public void removePostDial()

Removes post dial from SipURL

hasExtensions

public boolean hasExtensions()

Returns boolean value indicating if SipURL has extensions

Returns:

boolean value indicating if SipURL has extensions

hasExtension

public boolean hasExtension(java.lang.String extension)

Returns boolean value indicating if SipURL has extension

Returns:

boolean value indicating if SipURL has extension

setExtension

public void setExtension(java.lang.String extension,
                         java.lang.String value)

Sets value of extension parameterin SipURL

Parameters:

parameter - name of extension parameter

value - value of extension parameter

Throws:

java.lang.IllegalArgumentException - if extension or value are null or zero-length

getExtension

public java.lang.String getExtension(java.lang.String extension)
                              throws ParameterNotSetException

Gets the value of specified extension parameter in SipURL

Parameters:

parameter - extension parameter to retrieve

Returns:

the value of specified extension parameter in SipURL

Throws:

ParameterNotSetException - if the extension parameter does not exist

getExtensions

public java.lang.String[] getExtensions()
                                 throws ParameterNotSetException

Gets an array of SipURL's extension parameter names

Returns:

an array of SipURL's extension parameter names

Throws:

ParameterNotSetException - if no extensions exist

getHeader

public java.lang.String getHeader(java.lang.String headerName)
                           throws ParameterNotSetException

Gets the value of specified header in SipURL

Parameters:

headerName - header to retrieve

Returns:

the value of specified header in SipURL

Throws:

ParameterNotSetException - if the header does not exist

getHeaders

public java.lang.String[] getHeaders()
                              throws ParameterNotSetException

Gets an array of SipURL's header names

Returns:

an array of SipURL's header names

Throws:

ParameterNotSetException - if no headers exist

setHeader

public void setHeader(java.lang.String headerName,
                      java.lang.String headerValue)
               throws java.lang.IllegalArgumentException

Sets header of SipURL

Parameters:

headerName - header name

headerValue - header value

Throws:

java.lang.IllegalArgumentException - if headerName or headerValue are null or zero-length

equals

public boolean equals(SipURL sipURL)

Indicates whether some other SipURL is "equal to" this one

Parameters:

sipURL - the SipURL with which to compare

isGlobal

public boolean isGlobal()
                 throws SipException

Returns boolean value to indicate if the SipURL has a global phone user

Returns:

boolean value to indicate if the SipURL has a global phone user

Throws:

SipException - if user type is not USER_PHONE

setGlobal

public void setGlobal(boolean global)
               throws SipException

Sets phone user of SipURL to be global or local

Parameters:

global - boolean value indicating if phone user should be global

Throws:

SipException - if user type is not USER_PHONE

toString

public java.lang.String toString()

Gets string representation of SipURL

Overrides:

toString in class URI

Returns:

string representation of SipURL

clone

public java.lang.Object clone()

Creates and returns a copy of SipURL

Overrides:

clone in class URI

getSchemeData

public java.lang.String getSchemeData()

Gets scheme data of SipURL

Overrides:

getSchemeData in class URI

Returns:

scheme data of SipURL