001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : TelURL.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 08/10/2002 Phelim O'Doherty Initial version
020: * 1.2 19/05/2005 Phelim O'Doherty Added phone context methods
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip.address;
023:
024: import java.text.ParseException;
025: import javax.sip.header.Parameters;
026:
027: /**
028: * This class represents Tel URLs, which are used for addressing. The Tel URL
029: * starts with the scheme <code>tel:</code>. This tells the
030: * local entity that what follows is a URL that should be parsed as described
031: * in <a href = "http://www.ietf.org/rfc/rfc2806.txt">RFC2806</a>. After that,
032: * the URL contains the phone number of the remote entity.
033: * <p>
034: * Within a SIP Message, TelURLs can be used to indicate the source and intended
035: * destination of a Request, redirection addresses and the current destination
036: * of a Request. All these Headers may contain TelURLs.
037: * <p>
038: * The TelURL interface extends the generic URI interface and provides
039: * additional convenience methods for the following components of a TelURL
040: * address, above the generic URI class:
041: * <ul>
042: * <li>ISDN Subaddress - Phone numbers can also contain subaddresses, which
043: * are used to identify different remote entities under the same phone number.
044: * <li>Post Dial - Phone numbers can also contain a post-dial sequence.
045: * This is what is often used with voice mailboxes and other services that
046: * are controlled by dialing numbers from your phone keypad while the call is
047: * in progress.
048: * <li>Global - Phone numbers can be either "global" or "local". Global numbers
049: * are unambiguous everywhere. Local numbers are usable only within a certain
050: * area.
051: * <li>URL parameters - Parameters affecting a request constructed from this
052: * URL. URL parameters are added to the end of the URL component and are
053: * separated by semi-colons. URL parameters take the form:<br>
054: * parameter-name "=" parameter-value
055: * </ul>
056: * See <a href = "http://www.ietf.org/rfc/rfc2806.txt">RFC2806</a> for more
057: * information on the use of TelURL's.
058: *
059: * @author BEA Systems, NIST
060: * @version 1.2
061: */
062:
063: public interface TelURL extends URI, Parameters {
064:
065: /**
066: * Returns <code>true</code> if this TelURL is global i.e. if the TelURI
067: * has a global phone user.
068: *
069: * @return <code>true</code> if this TelURL represents a global phone user,
070: * and <code>false</code> otherwise.
071: */
072: public boolean isGlobal();
073:
074: /**
075: * Sets phone user of this TelURL to be either global or local. The default
076: * value is false, hence the TelURL is defaulted to local.
077: *
078: * @param global - the boolean value indicating if the TelURL has a global
079: * phone user.
080: */
081: public void setGlobal(boolean global);
082:
083: /**
084: * Sets post dial of this TelURL. The post-dial sequence describes what and
085: * when the local entity should send to the phone line.
086: *
087: * @param postDial - new value of the <code>postDial</code> parameter
088: * @throws ParseException which signals that an error has been reached
089: * unexpectedly while parsing the postDial value.
090: */
091: public void setPostDial(String postDial) throws ParseException;
092:
093: /**
094: * Returns the value of the <code>postDial</code> parameter, or null if it
095: * is not set.
096: *
097: * @return the value of the <code>postDial</code> parameter
098: */
099: public String getPostDial();
100:
101: /**
102: * Sets phone number of this TelURL. The phone number may either be local or
103: * global determined by the isGlobal method in this interface. The phoneNumber
104: * argument should not contain the "+" associated with telephone numbers.
105: *
106: * @param phoneNumber - new value of the <code>phoneNumber</code> parameter
107: * @throws ParseException which signals that an error has been reached
108: * unexpectedly while parsing the phoneNumber value.
109: */
110: public void setPhoneNumber(String phoneNumber)
111: throws ParseException;
112:
113: /**
114: * Returns the value of the <code>phoneNumber</code> parameter. This method
115: * will not return the "+" associated with telephone numbers.
116: *
117: * @return the value of the <code>phoneNumber</code> parameter
118: */
119: public String getPhoneNumber();
120:
121: /**
122: * Sets ISDN subaddress of this TelURL. If a subaddress is present, it is
123: * appended to the phone number after ";isub=".
124: *
125: * @param isdnSubAddress - new value of the <code>isdnSubAddress</code>
126: * parameter
127: * @throws ParseException which signals that an error has been reached
128: * unexpectedly while parsing the isdnSubAddress value.
129: */
130: public void setIsdnSubAddress(String isdnSubAddress)
131: throws ParseException;
132:
133: /**
134: * Returns the value of the <code>isdnSubAddress</code> parameter, or null
135: * if it is not set.
136: *
137: * @return the value of the <code>isdnSubAddress</code> parameter
138: */
139: public String getIsdnSubAddress();
140:
141: /**
142: * Sets the phone context of this TelURL.
143: *
144: * @param phoneContext - new value of the <code>phoneContext</code>
145: * parameter
146: * @throws ParseException which signals that an error has been reached
147: * unexpectedly while parsing the phoneContext value.
148: * @since v1.2
149: */
150: public void setPhoneContext(String phoneContext)
151: throws ParseException;
152:
153: /**
154: * Returns the value of the <code>phoneContext</code> parameter, or null
155: * if it is not set.
156: *
157: * @return the value of the <code>phoneContext</code> parameter
158: * @since v1.2
159: */
160: public String getPhoneContext();
161:
162: /**
163: * This method returns the URI as a string.
164: *
165: * @return String The stringified version of the URI
166: */
167: public String toString();
168: }
|