sip.address.TelURL Maven / Gradle / Ivy

/**
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * 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     : TelURL.java
 * Author        : Phelim O'Doherty
 *
 *  HISTORY
 *  Version   Date      Author              Comments
 *  1.1     08/10/2002  Phelim O'Doherty    Initial version
 *  1.2     19/05/2005  Phelim O'Doherty    Added phone context methods
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */
package javax.sip.address;

import java.text.ParseException;
import javax.sip.header.Parameters;

 /**
 * This class represents Tel URLs, which are used for addressing. The Tel URL
 * starts with the scheme tel:. This tells the
 * local entity that what follows is a URL that should be parsed as described
 * in RFC2806. After that,
 * the URL contains the phone number of the remote entity.
 * 
 * Within a SIP Message, TelURLs can be used to indicate the source and intended
 * destination of a Request, redirection addresses and the current destination
 * of a Request. All these Headers may contain TelURLs.
 * 

 * The TelURL interface extends the generic URI interface and provides
 * additional convenience methods for the following components of a TelURL
 * address, above the generic URI class:
 * 

 * ISDN Subaddress - Phone numbers can also contain subaddresses, which
 * are used to identify different remote entities under the same phone number.
 * 
Post Dial - Phone numbers can also contain a post-dial sequence.
 * This is what is often used with voice mailboxes and other services that
 * are controlled by dialing numbers from your phone keypad while the call is
 * in progress.
 * 
Global - Phone numbers can be either "global" or "local". Global numbers
 * are unambiguous everywhere. Local numbers are usable only within a certain
 * area.
 * 
URL parameters - Parameters affecting a request constructed from this
 * URL. URL parameters are added to the end of the URL component and are 
 * separated by semi-colons. URL parameters take the form:

 * parameter-name "=" parameter-value
 * 
 * See RFC2806 for more 
 * information on the use of TelURL's.
 *
 * @author BEA Systems, NIST
 * @version 1.2
 */

public interface TelURL extends URI, Parameters {


    /**
     * Returns true if this TelURL is global i.e. if the TelURI
     * has a global phone user.
     *
     * @return true if this TelURL represents a global phone user,
     * and false otherwise.
     */
    public boolean isGlobal();

    /**
     * Sets phone user of this TelURL to be either global or local. The default
     * value is false, hence the TelURL is defaulted to local.
     *
     * @param global - the boolean value indicating if the TelURL has a global
     * phone user.
     */
    public void setGlobal(boolean global);

    /**
     * Sets post dial of this TelURL. The post-dial sequence describes what and
     * when the local entity should send to the phone line.
     *
     * @param postDial - new value of the postDial parameter
     * @throws ParseException  which signals that an error has been reached
     * unexpectedly while parsing the postDial value.
     */
    public void setPostDial(String postDial) throws ParseException;

    /**
     * Returns the value of the postDial parameter, or null if it
     * is not set.
     *
     * @return  the value of the postDial parameter
     */
    public String getPostDial();

    /**
     * Sets phone number of this TelURL. The phone number may either be local or
     * global determined by the isGlobal method in this interface. The phoneNumber
     * argument should not contain the "+" associated with telephone numbers.
     *
     * @param phoneNumber - new value of the phoneNumber parameter
     * @throws ParseException  which signals that an error has been reached
     * unexpectedly while parsing the phoneNumber value.
     */
    public void setPhoneNumber(String phoneNumber) throws ParseException;

    /**
     * Returns the value of the phoneNumber parameter. This method
     * will not return the "+" associated with telephone numbers.
     *
     * @return  the value of the phoneNumber parameter
     */
    public String getPhoneNumber();    
    
    /**
     * Sets ISDN subaddress of this TelURL. If a subaddress is present, it is
     * appended to the phone number after ";isub=".
     *
     * @param isdnSubAddress - new value of the isdnSubAddress
     * parameter
     * @throws ParseException which signals that an error has been reached
     * unexpectedly while parsing the isdnSubAddress value.
     */
    public void setIsdnSubAddress(String isdnSubAddress) throws ParseException;

    /**
     * Returns the value of the isdnSubAddress parameter, or null
     * if it is not set.
     *
     * @return  the value of the isdnSubAddress parameter
     */
    public String getIsdnSubAddress();
    
    /**
     * Sets the phone context of this TelURL.
     *
     * @param phoneContext - new value of the phoneContext
     * parameter
     * @throws ParseException which signals that an error has been reached
     * unexpectedly while parsing the phoneContext value.
     * @since v1.2
     */
    public void setPhoneContext(String phoneContext) throws ParseException;

    /**
     * Returns the value of the phoneContext parameter, or null
     * if it is not set.
     *
     * @return  the value of the phoneContext parameter
     * @since v1.2
     */
    public String getPhoneContext();
        
    
    /**
     * This method returns the URI as a string. 
     *
     * @return String The stringified version of the URI
     */    
    public String toString();
}