sip.address.AddressFactory 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 : AddressFactory.java
* Author : Phelim O'Doherty
*
* HISTORY
* Version Date Author Comments
* 1.1 08/10/2002 Phelim O'Doherty Initial version
*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
package javax.sip.address;
import java.text.ParseException;
/**
* This interface provides factory methods that allow an application to create
* Address objects, URI's, SipURI's and TelURL's from a particular
* implementation of this specification. This class is a singleton and can be
* retrieved from the {@link javax.sip.SipFactory#createAddressFactory()}.
*
* @author BEA Systems, NIST
* @version 1.2
*/
public interface AddressFactory {
/**
* Creates a URI based on given URI string. The URI string is parsed in
* order to create the new URI instance. Depending on the scheme the
* returned may or may not be a SipURI or TelURL cast as a URI.
*
* @param uri - the new string value of the URI.
* @throws ParseException if the URI string is malformed.
*/
public URI createURI(String uri) throws ParseException;
/**
* Creates a SipURI based on the given user and host components. The user
* component may be null.
*
* This create method first builds a URI in string form using the given
* components as follows:
*
* - Initially, the result string is empty.
*
- The scheme followed by a colon character ('sip:') is appended to
* the result.
*
- The user and host are then appended. Any character that is not a
* legal URI character is quoted.
*
*
* The resulting URI string is then parsed in order to create the new
* SipURI instance as if by invoking the createURI(String) constructor;
* this may cause a URISyntaxException to be thrown.
*
* An application that wishes to create a 'sips' URI should call the
* {@link SipURI#setSecure(boolean)} with an argument of 'true' on the
* returned SipURI.
*
* @param user - the new string value of the user, this value may be null.
* @param host - the new string value of the host.
* @throws ParseException if the URI string is malformed.
*/
public SipURI createSipURI(String user, String host)
throws ParseException;
/**
* Creates a TelURL based on given URI string. The scheme should
* not be included in the phoneNumber string argument.
*
* @param phoneNumber the new string value of the phoneNumber.
* @throws ParseException if the URI string is malformed.
*/
public TelURL createTelURL(String phoneNumber) throws ParseException;
/**
* Creates an Address with the new address string value. The address
* string is parsed in order to create the new Address instance.
* Valid arguments obey the syntax for name-addr tokens in
* RFC3261, for example "Bob ". It is recommended to
* use the to use the name-addr form containing '<' '>' to avoid confusion
* of URI parameters. As a special case, the
* string argument "*" creates a wildcard Address object with the property
* that ((SipURI)Address.getURI()).getUser() returns a
* String contain one character "*".
*
* @param address - the new string value of the address.
* @throws ParseException which signals that an error has been reached
* unexpectedly while parsing the address value.
*/
public Address createAddress(String address) throws ParseException;
/**
* Creates an Address with the new URI attribute value.
*
* @param uri - the URI value of the address.
*/
public Address createAddress(URI uri);
/**
* Creates an Address with the new display name and URI attribute
* values.
*
* @param displayName - the new string value of the display name of the
* address. A null value does not set the display name.
* @param uri - the new URI value of the address.
* @throws ParseException which signals that an error has been reached
* unexpectedly while parsing the displayName value.
*/
public Address createAddress(String displayName, URI uri) throws ParseException;
}