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 : Address.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 18/05/2005 Phelim O'Doherty Added hashcode method
021: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
022: */package javax.sip.address;
023:
024: import java.io.*;
025: import java.text.ParseException;
026:
027: /**
028: * This interface represents a user's display name and URI address. The display
029: * name of an address is optional but if included can be displayed to an end-user.
030: * The address URI (most likely a SipURI) is the user's address. For example a
031: * 'To' address of <code>To: Bob sip:duke@jcp.org</code> would have a display
032: * name attribute of <code>Bob</code> and an address of
033: * <code>sip:duke@jcp.org</code>.
034: *
035: * @see SipURI
036: * @see TelURL
037: *
038: * @author BEA Systems, NIST
039: * @version 1.2
040: *
041: */
042:
043: public interface Address extends Cloneable, Serializable {
044:
045: /**
046: * Sets the display name of the Address. The display name is an
047: * additional user friendly personalized text that accompanies the address.
048: *
049: * @param displayName - the new string value of the display name.
050: * @throws ParseException which signals that an error has been reached
051: * unexpectedly while parsing the displayName value.
052: */
053: public void setDisplayName(String displayName)
054: throws ParseException;
055:
056: /**
057: * Gets the display name of this Address, or null if the attribute is
058: * not set.
059: *
060: * @return the display name of this Address
061: */
062: public String getDisplayName();
063:
064: /**
065: * Sets the URI of this Address. The URI can be either a TelURL or a SipURI.
066: *
067: * @param uri - the new URI value of this Address.
068: */
069: public void setURI(URI uri);
070:
071: /**
072: * Returns the URI of this Address. The type of URI can be
073: * determined by the scheme.
074: *
075: * @return URI parmater of the Address object
076: */
077: public URI getURI();
078:
079: /**
080: * Returns a string representation of this Address.
081: *
082: * @return the stringified representation of the Address
083: */
084: public String toString();
085:
086: /**
087: * Indicates whether some other Object is "equal to" this Address.
088: * The actual implementation class of a Address object must override
089: * the Object.equals method. The new equals method must ensure that the
090: * implementation of the method is reflexive, symmetric, transitive and
091: * for any non null value X, X.equals(null) returns false.
092: *
093: * @param obj - the Object with which to compare this Address
094: * @return true if this Address is "equal to" the object argument and
095: * false otherwise.
096: * @see Object
097: */
098: public boolean equals(Object obj);
099:
100: /**
101: * Gets a hash code value for this address. Implementations MUST
102: * implement a hashCode method that overrides the default hash code
103: * method for Objects comparision.
104: *
105: * @return a hash code value.
106: * @since v1.2
107: */
108: public int hashCode();
109:
110: /**
111: * This determines if this address is a wildcard address. That is
112: * <code>((SipURI)Address.getURI()).getUser() == *;</code>. This method
113: * is specific to SIP and SIPS schemes.
114: *
115: * @return true if this address is a wildcard, false otherwise.
116: */
117: public boolean isWildcard();
118:
119: /**
120: * Clone method. An implementation is expected to override the default
121: * Object.clone method and return a "deep clone".
122: *
123: * @since v1.2
124: */
125: public Object clone();
126:
127: }
|