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 : AddressFactory.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.text.ParseException;
024:
025: /**
026: * This interface provides factory methods that allow an application to create
027: * Address objects, URI's, SipURI's and TelURL's from a particular
028: * implementation of this specification. This class is a singleton and can be
029: * retrieved from the {@link javax.sip.SipFactory#createAddressFactory()}.
030: *
031: * @author BEA Systems, NIST
032: * @version 1.2
033: */
034: public interface AddressFactory {
035:
036: /**
037: * Creates a URI based on given URI string. The URI string is parsed in
038: * order to create the new URI instance. Depending on the scheme the
039: * returned may or may not be a SipURI or TelURL cast as a URI.
040: *
041: * @param uri - the new string value of the URI.
042: * @throws ParseException if the URI string is malformed.
043: */
044: public URI createURI(String uri) throws ParseException;
045:
046: /**
047: * Creates a SipURI based on the given user and host components. The user
048: * component may be null.
049: * <p>
050: * This create method first builds a URI in string form using the given
051: * components as follows:
052: * <ul>
053: * <li>Initially, the result string is empty.
054: * <li>The scheme followed by a colon character ('sip:') is appended to
055: * the result.
056: * <li>The user and host are then appended. Any character that is not a
057: * legal URI character is quoted.
058: * </ul>
059: * <br>
060: * The resulting URI string is then parsed in order to create the new
061: * SipURI instance as if by invoking the createURI(String) constructor;
062: * this may cause a URISyntaxException to be thrown.
063: * <p>
064: * An application that wishes to create a 'sips' URI should call the
065: * {@link SipURI#setSecure(boolean)} with an argument of 'true' on the
066: * returned SipURI.
067: *
068: * @param user - the new string value of the user, this value may be null.
069: * @param host - the new string value of the host.
070: * @throws ParseException if the URI string is malformed.
071: */
072: public SipURI createSipURI(String user, String host)
073: throws ParseException;
074:
075: /**
076: * Creates a TelURL based on given URI string. The scheme should
077: * not be included in the phoneNumber string argument.
078: *
079: * @param phoneNumber the new string value of the phoneNumber.
080: * @throws ParseException if the URI string is malformed.
081: */
082: public TelURL createTelURL(String phoneNumber)
083: throws ParseException;
084:
085: /**
086: * Creates an Address with the new address string value. The address
087: * string is parsed in order to create the new Address instance.
088: * Valid arguments obey the syntax for <code>name-addr</code> tokens in
089: * RFC3261, for example "Bob <sip:bob@biloxi.com>". It is recommended to
090: * use the to use the name-addr form containing '<' '>' to avoid confusion
091: * of URI parameters. As a special case, the
092: * string argument "*" creates a wildcard Address object with the property
093: * that <code>((SipURI)Address.getURI()).getUser()</code> returns a
094: * String contain one character "*".
095: *
096: * @param address - the new string value of the address.
097: * @throws ParseException which signals that an error has been reached
098: * unexpectedly while parsing the address value.
099: */
100: public Address createAddress(String address) throws ParseException;
101:
102: /**
103: * Creates an Address with the new URI attribute value.
104: *
105: * @param uri - the URI value of the address.
106: */
107: public Address createAddress(URI uri);
108:
109: /**
110: * Creates an Address with the new display name and URI attribute
111: * values.
112: *
113: * @param displayName - the new string value of the display name of the
114: * address. A <code>null</code> value does not set the display name.
115: * @param uri - the new URI value of the address.
116: * @throws ParseException which signals that an error has been reached
117: * unexpectedly while parsing the displayName value.
118: */
119: public Address createAddress(String displayName, URI uri)
120: throws ParseException;
121:
122: }
|