Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Unpublished - rights reserved under the Copyright Laws of the United States. Copyright � 2003 Sun Microsystems, Inc. All rights reserved. Copyright � 2005 BEA Systems, Inc. All rights reserved. Use is subject to license terms. This distribution may include materials developed by third parties. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Module Name : JSIP Specification File Name : SipURI.java Author : Phelim O'Doherty HISTORY Version Date Author Comments 1.1 08/10/2002 Phelim O'Doherty Initial version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 package javax.sip.address;
 
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.

public interface SipURI extends URIParameters {

    
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:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the user value.
    public void setUser(String userthrows ParseException;

    
Returns the user part of this SipURI.

Returns:
the user part of this SipURI, this value may be null.
    public String getUser();

    
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

Parameters:
userPassword - the new String value of the user password
Throws:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the userPassword value.
:
sign make up the user-info.
    public void setUserPassword(String userPasswordthrows ParseException;

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

Returns:
the user password of this SipURI
    public String getUserPassword();

    
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.
    public boolean isSecure();

    
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.
    public void setSecure(boolean secure);

    
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:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the host value.
  
    public void setHost(String hostthrows ParseException;

     
Returns the host part of this SipURI.

Returns:
the host part of this SipURI
     
    public String getHost();
    
    
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
    public void setPort(int port);     

    
Returns the port part of this SipURI.

Returns:
the port part of this SipURI
    
    public int getPort();    

    
Removes the port part of this SipURI. If no port is specified the stack will assume the default port.
    
    public void removePort();     
// header manipulation methods

    
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
    public String getHeader(String name);

    
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:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the name or value parameters.
    public void setHeader(String nameString valuethrows ParseException;


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

Returns:
an Iterator over all the header names
    public Iterator getHeaderNames();
//Param Covenience methods


    
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
    public String getTransportParam();

    
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 javax.sip.ListeningPoint.

Parameters:
transport - new value for the "transport" parameter
Throws:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the transport value.
    public void setTransportParam(String transportthrows ParseException;

    
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
    public int getTTLParam();

    
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:
javax.sip.InvalidArgumentException if supplied value is less than zero, excluding -1 the default not set value.
    public void setTTLParam(int ttlthrows InvalidArgumentException;

    
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
    public String getMethodParam();

    
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:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the method value.
    public void setMethodParam(String methodthrows 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:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the userParam value.
    public void setUserParam(String userParamthrows ParseException;

    
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
    public String getUserParam();


    
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
    public String getMAddrParam();

    
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:
java.text.ParseException which signals that an error has been reached unexpectedly while parsing the mAddr value.
    public void setMAddrParam(String mAddrthrows ParseException;

    
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.
    public boolean hasLrParam();

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

    
    
    
This method returns the URI as a string.

Returns:
the stringified version of the URI
    
    public String toString();
    
New to GrepCode? Check out our FAQ X