javax.microedition.sip
Class SipAddress

java.lang.Object
  extended by javax.microedition.sip.SipAddress

public class SipAddress
extends java.lang.Object

SipAddress provides a generic SIP address parser. This class can be used to parse either full SIP name addresses like: BigGuy <sip:UserA@atlanta.com> or SIP/SIPS URIs like: sip:+13145551111@ss1.atlanta.com;user=phone or sips:alice@atlanta.com;transport=tcp.

Correspondingly, valid SIP addresses can be constructed with this class.

SipAddress has following functional requirements:

It is not mandated that the implementation of SipAddress does any semantic checks in addition to ABNF syntax validation. Refer to RFC 3261 (page 149-151) for a list of possible semantic checks that an implementation MAY provide.

Reference, SIP 3261 [1] p.153 Example SIP and SIPS URIs and p.228 name-addr in SIP BNF specification.


Constructor Summary
SipAddress(java.lang.String address)
          Construct a new SipAddress from string.
SipAddress(java.lang.String displayName, java.lang.String URI)
          Construct a new SipAddress from display name and URI.
 
Method Summary
 java.lang.String getDisplayName()
          Returns the display name of SIP address.
 java.lang.String getHost()
          Returns the host part of the SIP address.
 java.lang.String getParameter(java.lang.String name)
          Returns the value associated with the named URI parameter.
 java.lang.String[] getParameterNames()
          Returns a String array of all parameter names.
 int getPort()
          Returns the port number of the SIP address.
 java.lang.String getScheme()
          Returns the scheme of SIP address.
 java.lang.String getURI()
          Returns the URI part of the address (without parameters).
 java.lang.String getUser()
          Returns the user part of SIP address.
 void removeParameter(java.lang.String name)
          Removes the named URI parameter.
 void setDisplayName(java.lang.String name)
          Sets the display name.
 void setHost(java.lang.String host)
          Sets the host part of the SIP address.
 void setParameter(java.lang.String name, java.lang.String value)
          Sets the named URI parameter to the specified value.
 void setPort(int port)
          Sets the port number of the SIP address.
 void setScheme(java.lang.String scheme)
          Sets the scheme of SIP address.
 void setURI(java.lang.String URI)
          Sets the URI part of the SIP address (without parameters).
 void setUser(java.lang.String user)
          Sets the user part of SIP address.
 java.lang.String toString()
          Returns a fully qualified SIP address, with display name, URI and URI parameters.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SipAddress

public SipAddress(java.lang.String address)

Construct a new SipAddress from string. The string can be either name address:

Display Name <sip:user:password@host:port;uri-parameters>

or plain SIP URI:

sip:user:password@host:port;uri-parameters

or the special address value: "*".

Parameters:
address - SIP address as String
Throws:
java.lang.NullPointerException - if address is null.
java.lang.IllegalArgumentException - if there was an error in parsing the address.

SipAddress

public SipAddress(java.lang.String displayName,
                  java.lang.String URI)

Construct a new SipAddress from display name and URI.

Parameters:
displayName - user display name. If null or empty String then no display name is set.
URI - SIP URI
Throws:
java.lang.NullPointerException - if URI is null.
java.lang.IllegalArgumentException - if there was an error in parsing the arguments.
Method Detail

getDisplayName

public java.lang.String getDisplayName()

Returns the display name of SIP address.

Returns:
display name or null if not available or if the address is the special "*" value.

setDisplayName

public void setDisplayName(java.lang.String name)

Sets the display name. Empty string or null removes the display name.

Throws:
java.lang.IllegalArgumentException - if the display name is invalid or the address represents the immutable "*" value.

getScheme

public java.lang.String getScheme()

Returns the scheme of SIP address.

Returns:
the scheme of this SIP address e.g. sip or sips or null if the address is the special "*" value.

setScheme

public void setScheme(java.lang.String scheme)

Sets the scheme of SIP address. Valid scheme format is defined in RFC 3261 [1] p.224

Throws:
java.lang.NullPointerException - if scheme is null
java.lang.IllegalArgumentException - if the scheme is invalid or the address represents the immutable "*" value.

getUser

public java.lang.String getUser()

Returns the user part of SIP address. There is no separate method for getting the password field so that if the password field is present in the address then getUser returns the value of 'user:password' (instead of only 'user').

Returns:
user part of SIP address. Returns null if the user part is missing or if the address is the special "*" value.

setUser

public void setUser(java.lang.String user)

Sets the user part of SIP address. Empty string or null removes the user part.

Throws:
java.lang.IllegalArgumentException - if the user part is invalid or the address represents the immutable "*" value.

getURI

public java.lang.String getURI()

Returns the URI part of the address (without parameters). The URI part of the address is of the form scheme:user@host:port.

Returns:
the URI part of the address or "*" if the address is the special "*" value.

setURI

public void setURI(java.lang.String URI)

Sets the URI part of the SIP address (without parameters). The URI part of the address is of the form scheme:user@host:port. If the parameter of the method contains URI parameters they don't overwrite existing URI parameters, they are simply ignored if present. Parameters can be manipulated by the get/set/removeParameter() calls.

Parameters:
URI - the URI part of the address to set
Throws:
java.lang.NullPointerException - if URI is null
java.lang.IllegalArgumentException - if the URI is "*" or invalid or the address represents the immutable "*" value.

getHost

public java.lang.String getHost()

Returns the host part of the SIP address.

Returns:
host part of this address or null if the address is the special "*" value.

setHost

public void setHost(java.lang.String host)

Sets the host part of the SIP address.

Throws:
java.lang.NullPointerException - if host is null
java.lang.IllegalArgumentException - if the host is invalid or the address represents the immutable "*" value.

getPort

public int getPort()

Returns the port number of the SIP address. If port number is not set, return 5060 for sip: scheme and 5061 for sips: scheme. If the address is wildcard "*" return 0.

Returns:
the port number or 0 if the address is the special "*" value.

setPort

public void setPort(int port)

Sets the port number of the SIP address. Valid range is 0-65535. After setting the port to 0 the port number is removed from the address URI, getPort returns the default 5060 value for sip: scheme and 5061 for sips: scheme.

Parameters:
port - port number. The valid range 0-65535, 0 means that port number is removed from the address URI
Throws:
java.lang.IllegalArgumentException - if the port number is invalid or the address represents the immutable "*" value.

getParameter

public java.lang.String getParameter(java.lang.String name)

Returns the value associated with the named URI parameter.

Parameters:
name - the name of the parameter
Returns:
the value of the named parameter, or empty string for parameters without value and null if the parameter is not defined or if the address is the special "*" value.
Throws:
java.lang.NullPointerException - if name is null

setParameter

public void setParameter(java.lang.String name,
                         java.lang.String value)

Sets the named URI parameter to the specified value. If the value is null the parameter is interpreted as a parameter without value. Existing parameter will be overwritten, otherwise the parameter is added.

Throws:
java.lang.NullPointerException - if name is null
java.lang.IllegalArgumentException - if the parameter is invalid (RFC 3261, chapter 19.1.1 SIP and SIPS URI Components "URI parameters" p.149) or the address represents the immutable "*" value.

removeParameter

public void removeParameter(java.lang.String name)

Removes the named URI parameter. The method returns without any action if the named parameter is not defined or if the address is the special "*" value.

Parameters:
name - the name of the parameter to remove
Throws:
java.lang.NullPointerException - if name is null

getParameterNames

public java.lang.String[] getParameterNames()

Returns a String array of all parameter names.

Returns:
String array of parameter names. Returns null if the address does not have any parameters or if the address is the special "*" value.

toString

public java.lang.String toString()

Returns a fully qualified SIP address, with display name, URI and URI parameters. If display name is not specified only a SIP URI is returned. If the port is not explicitly set (to 5060 or other value) it will be omitted from the address URI in returned String.

Overrides:
toString in class java.lang.Object
Returns:
a fully qualified SIP name address, SIP or SIPS URI or "*" if the address is the special "*" value.


Copyright © 2007 Nokia Corporation. All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.