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 : SipURI.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: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
021: */package javax.sip.address;
022:
023: import java.util.Iterator;
024: import javax.sip.header.Parameters;
025: import java.text.ParseException;
026: import javax.sip.InvalidArgumentException;
027:
028: /**
029: * This class represents SIP URIs, that may have either a <code>sip:</code> or
030: * <code>sips:</code> scheme. All SIP implementations MUST support the sip:
031: * URI scheme.
032: * <p>
033: * SIP and SIPS URIs are used for addressing. They are similar to email
034: * addresses in that they are of the form
035: * <code>user@host</code> where user is either a user name or telephone number,
036: * and host is a host or domain name, or a numeric IP address. Additionally,
037: * SIP and SIPS URIs may contain parameters and headers (although headers are
038: * not legal in all contexts). A SipURI can be embedded in web pages, business
039: * cards or other hyperlinks to indicate that a particular user or service can
040: * be called via SIP.
041: * <p>
042: * Within a SIP Message, SipURIs are used to indicate the source and intended
043: * destination of a Request, redirection addresses and the current destination
044: * of a Request. Normally all these Headers will contain SipURIs.
045: * <p>
046: * Syntactically, SIP and SIPS URIs are identical except for the name of the URI
047: * scheme. The semantics differs in that the SIPS scheme implies that the
048: * identified resource is to be contacted using TLS. Because SIP and SIPS URIs
049: * are syntactically identical and because they're used the same way, they're
050: * both represented by the SipURI interface.
051: * <p>
052: * The SipURI interface extends the generic URI interface and provides
053: * additional convenience methods for the following components of a SipURI
054: * address, above the generic URI interface:
055: * <ul>
056: * <li>User - The set of valid telephone-subscriber strings is a subset of
057: * valid user strings. The user URI parameter exists to distinguish telephone
058: * numbers from user names that happen to look like telephone numbers. If the
059: * user string contains a telephone number formatted as a telephone-subscriber,
060: * the user parameter value "phone" SHOULD be present. Even without this
061: * parameter, recipients of SIP and SIPS URIs MAY interpret the pre-@ part as a
062: * telephone number if local restrictions on the name space for user name allow it.
063: * <li>UserPassword - A password associated with the user. While the SIP and
064: * SIPS URI syntax allows this field to be present, its use is NOT RECOMMENDED,
065: * because the passing of authentication information in clear text (such as
066: * URIs) has proven to be a security risk in almost every case where it has
067: * been used. For instance, transporting a PIN number in this field exposes
068: * the PIN.
069: * <li>URI parameters - Parameters affecting a request constructed from this
070: * URI. URI parameters are added after the hostport component and are separated
071: * by semi-colons. URI parameters take the form:<br>
072: * parameter-name "=" parameter-value<br>
073: * Even though an arbitrary number of URI parameters may be included in a URI,
074: * any given parameter-name MUST NOT appear more than once. The SipURI
075: * interface also provides convenience methods for the manipulation of popular
076: * parameters in a SipURI address, namely:
077: * <ul>
078: * <li>Lr Parameter - the element responsible for this resource implements the
079: * routing mechanisms specified in RFC 3261.
080: * <li>Method - The method of the SIP request constructed from the URI.
081: * <li>MAddr Parameter - the server address to be contacted for this user.
082: * <li>TTL Parameter - the time-to-live value when packets are sent using UDP
083: * multicast.
084: * <li>User Parameter - the set of valid telephone-subscriber strings.
085: * <li>Transport Parameter - specifies which transport protocol to use for
086: * sending requests and responses to this entity
087: * </ul>
088: * <li>URI Headers - Header fields to be included in a request constructed from
089: * the URI. Headers fields in the SIP request can be specified with the "?"
090: * mechanism within a URI. The header names and values are encoded in
091: * ampersand separated 'hname = hvalue' pairs. The special hname "body"
092: * indicates that the associated hvalue is the message-body of the SIP request.
093: * <li>Secure - This determines if the scheme of this URI is either
094: * <code>sip:</code> or <code>sips:</code>, where <code>sips:</code> is secure.
095: * </ul>
096: * See section 19.1.2 of <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>
097: * for the use of SIP and SIPS URI components based on the context in which the
098: * URI appears.
099: *
100: * @see javax.sip.header.FromHeader
101: * @see javax.sip.header.ToHeader
102: * @see javax.sip.header.ContactHeader
103: * @see URI
104: *
105: * @author BEA Systems, NIST
106: * @version 1.2
107: *
108: */
109:
110: public interface SipURI extends URI, Parameters {
111:
112: /**
113: * Sets the user of SipURI. The identifier of a particular resource at
114: * the host being addressed. The user and the user password including the
115: * '@' sign make up the user-info.
116: *
117: * @param user - the new String value of the user.
118: * @throws ParseException which signals that an error has been reached
119: * unexpectedly while parsing the user value.
120: */
121: public void setUser(String user) throws ParseException;
122:
123: /**
124: * Returns the user part of this SipURI.
125: *
126: * @return the user part of this SipURI, this value may be null.
127: */
128: public String getUser();
129:
130: /**
131: * Sets the user password associated with the user of SipURI. While the SIP and
132: * SIPS URI syntax allows this field to be present, its use is NOT
133: * RECOMMENDED, because the passing of authentication information in clear
134: * text (such as URIs) has proven to be a security risk in almost every
135: * case where it has been used. The user password and the user including
136: * the @ sign make up the user-info.
137: *
138: * @param userPassword - the new String value of the user password
139: * @throws ParseException which signals that an error has been reached
140: * unexpectedly while parsing the userPassword value.
141: */
142: public void setUserPassword(String userPassword)
143: throws ParseException;
144:
145: /**
146: * Gets user password of SipURI, or null if it is not set.
147: *
148: * @return the user password of this SipURI
149: */
150: public String getUserPassword();
151:
152: /**
153: * Returns true if this SipURI is secure i.e. if this SipURI represents a
154: * sips URI. A sip URI returns false.
155: *
156: * @return <code>true</code> if this SipURI represents a sips URI, and
157: * <code>false</code> if it represents a sip URI.
158: */
159: public boolean isSecure();
160:
161: /**
162: * Sets the scheme of this URI to sip or sips depending on whether the
163: * argument is true or false. The default value is false.
164: *
165: * @param secure - the boolean value indicating if the SipURI is secure.
166: */
167: public void setSecure(boolean secure);
168:
169: /**
170: * Set the host part of this SipURI to the newly supplied <code>host</code>
171: * parameter.
172: *
173: * @param host - the new interger value of the host of this SipURI
174: * @throws ParseException which signals that an error has been reached
175: * unexpectedly while parsing the host value.
176: */
177: public void setHost(String host) throws ParseException;
178:
179: /**
180: * Returns the host part of this SipURI.
181: *
182: * @return the host part of this SipURI
183: */
184: public String getHost();
185:
186: /**
187: * Set the port part of this SipURI to the newly supplied port
188: * parameter.
189: *
190: * @param port - the new interger value of the port of this SipURI
191: */
192: public void setPort(int port);
193:
194: /**
195: * Returns the port part of this SipURI.
196: *
197: * @return the port part of this SipURI
198: */
199: public int getPort();
200:
201: /**
202: * Removes the port part of this SipURI. If no port is specified the
203: * stack will assume the default port.
204: *
205: */
206: public void removePort();
207:
208: // header manipulation methods
209:
210: /**
211: * Returns the value of the named header, or null if it is not set.
212: * SIP/SIPS URIs may specify headers. As an example, the URI
213: * sip:jimmy@jcp.org?priority=urgent has a header "priority" whose
214: * value is "urgent".
215: *
216: * @param name name of header to retrieve
217: * @return the value of specified header
218: */
219: public String getHeader(String name);
220:
221: /**
222: * Sets the value of the specified header fields to be included in a
223: * request constructed from the URI. If the header already had a value it
224: * will be overwritten.
225: *
226: * @param name - a String specifying the header name
227: * @param value - a String specifying the header value
228: * @throws ParseException which signals that an error has been reached
229: * unexpectedly while parsing the name or value parameters.
230: */
231: public void setHeader(String name, String value)
232: throws ParseException;
233:
234: /**
235: * Returns an Iterator over the String names of all headers present
236: * in this SipURI.
237: *
238: * @return an Iterator over all the header names
239: */
240: public Iterator getHeaderNames();
241:
242: //Param Covenience methods
243:
244: /**
245: * Returns the value of the "transport" parameter, or null if this is not
246: * set. This is equivalent to getParameter("transport").
247: *
248: * @return the transport paramter of the SipURI
249: */
250: public String getTransportParam();
251:
252: /**
253: * Sets the value of the "transport" parameter. This parameter specifies
254: * which transport protocol to use for sending requests and responses to
255: * this entity. The following values are defined: "udp", "tcp", "sctp",
256: * "tls", but other values may be used also. This method is equivalent to
257: * setParameter("transport", transport). Transport parameter constants
258: * are defined in the {@link javax.sip.ListeningPoint}.
259: *
260: * @param transport - new value for the "transport" parameter
261: * @throws ParseException which signals that an error has been reached
262: * unexpectedly while parsing the transport value.
263: */
264: public void setTransportParam(String transport)
265: throws ParseException;
266:
267: /**
268: * Returns the value of the "ttl" parameter, or -1 if this is not set.
269: * This method is equivalent to getParameter("ttl").
270: *
271: * @return the value of the <code>ttl</code> parameter
272: */
273: public int getTTLParam();
274:
275: /**
276: * Sets the value of the <code>ttl</code> parameter. The ttl parameter
277: * specifies the time-to-live value when packets are sent using UDP
278: * multicast. This is equivalent to setParameter("ttl", ttl).
279: *
280: * @param ttl - new value of the <code>ttl</code> parameter
281: * @throws InvalidArgumentException if supplied value is less than zero,
282: * excluding -1 the default not set value.
283: */
284: public void setTTLParam(int ttl) throws InvalidArgumentException;
285:
286: /**
287: * Returns the value of the <code>method</code> parameter, or null if this
288: * is not set. This is equivalent to getParameter("method").
289: *
290: * @return the value of the <code>method</code> parameter
291: */
292: public String getMethodParam();
293:
294: /**
295: * Sets the value of the <code>method</code> parameter. This specifies
296: * which SIP method to use in requests directed at this URI. This is
297: * equivalent to setParameter("method", method).
298: *
299: * @param method - new value String value of the method parameter
300: * @throws ParseException which signals that an error has been reached
301: * unexpectedly while parsing the method value.
302: */
303: public void setMethodParam(String method) throws ParseException;
304:
305: /**
306: * Sets the value of the user parameter. The user URI parameter exists to
307: * distinguish telephone numbers from user names that happen to look like
308: * telephone numbers. This is equivalent to setParameter("user", user).
309: *
310: * @param userParam - new value String value of the method parameter
311: * @throws ParseException which signals that an error has been reached
312: * unexpectedly while parsing the userParam value.
313: */
314: public void setUserParam(String userParam) throws ParseException;
315:
316: /**
317: * Returns the value of the <code>userParam</code>, or null if this is not
318: * set.
319: * <p>
320: * This is equivalent to getParameter("user").
321: *
322: * @return the value of the <code>userParam</code> of the SipURI
323: */
324: public String getUserParam();
325:
326: /**
327: * Returns the value of the <code>maddr</code> parameter, or null if this
328: * is not set. This is equivalent to getParameter("maddr").
329: *
330: * @return the value of the <code>maddr</code> parameter
331: */
332: public String getMAddrParam();
333:
334: /**
335: * Sets the value of the <code>maddr</code> parameter of this SipURI. The
336: * maddr parameter indicates the server address to be contacted for this
337: * user, overriding any address derived from the host field. This is
338: * equivalent to setParameter("maddr", maddr).
339: *
340: * @param mAddr new value of the <code>maddr</code> parameter
341: * @throws ParseException which signals that an error has been reached
342: * unexpectedly while parsing the mAddr value.
343: */
344: public void setMAddrParam(String mAddr) throws ParseException;
345:
346: /**
347: * Returns whether the the <code>lr</code> parameter is set. This is
348: * equivalent to hasParameter("lr"). This interface has no getLrParam as
349: * RFC3261 does not specify any values for the "lr" paramater.
350: *
351: * @return true if the "lr" parameter is set, false otherwise.
352: */
353: public boolean hasLrParam();
354:
355: /**
356: * Sets the value of the <code>lr</code> parameter of this SipURI. The lr
357: * parameter, when present, indicates that the element responsible for
358: * this resource implements the routing mechanisms specified in RFC 3261.
359: * This parameter will be used in the URIs proxies place in the
360: * Record-Route header field values, and may appear in the URIs in a
361: * pre-existing route set.
362: */
363: public void setLrParam();
364:
365: /**
366: * This method returns the URI as a string.
367: *
368: * @return the stringified version of the URI
369: */
370: public String toString();
371:
372: }
|