001 package data;
002
003 import java.beans.PropertyChangeListener;
004 import java.io.Serializable;
005
006 /**
007 * An object that has a name that complies with a NameContext's rules.
008 *
009 * <p>When implementing nameable objects you migth want to subclass {@link AbstractNameable}, which already
010 * implements all the methods required by Nameable.</p>
011 *
012 * @see Catalog
013 * @see Stock
014 * @see CatalogItem
015 * @see NameContext
016 *
017 * @author Steffen Zschaler
018 * @version 2.0 25/05/1999
019 * @since v2.0
020 */
021 public interface Nameable extends Serializable {
022
023 /**
024 * Attach a NameContext to this Nameable.
025 *
026 * <p>No naming conventions are checked neither in the old nor in the new NameContext.</p>
027 *
028 * @param nc the new NameContext of this Nameable object.
029 *
030 * @return the previous NameContext, if any.
031 *
032 * @override Always
033 */
034 public NameContext attach(NameContext nc);
035
036 /**
037 * Detach the current NameContext from this Nameable.
038 *
039 * @return the previously attached NameContext, if any.
040 *
041 * @override Always
042 */
043 public NameContext detachNC();
044
045 /**
046 * Set the Nameable's name.
047 *
048 * <p><code>setName()</code> must implement the following protocol (Let <code>nc</code> be the Nameable's
049 * current NameContext):</p>
050 *
051 * <pre>
052 * if (nc != null) {
053 * synchronized (nc.getNCMonitor()) {
054 * nc.checkNameChange (db, getName(), sName);
055 *
056 * // set the internal name attribute(s), leaving old name in sOldName
057 *
058 * nc.nameHasChanged (db, sOldName, getName());
059 * }
060 * }
061 * else {
062 * // set the internal name attribute(s)
063 * }
064 * </pre>
065 *
066 * @param sName the new name of the object
067 * @param db the DataBasket relative to which the operation is to be performed.
068 *
069 * @exception NameContextException if the name change was not approved of by the NameContext.
070 *
071 * @see NameContext
072 *
073 * @override Always
074 */
075 public void setName(String sName, DataBasket db) throws NameContextException;
076
077 /**
078 * Get the name of this Nameable object.
079 *
080 * @override Always
081 */
082 public String getName();
083
084 /**
085 * Register a listener to receive events whenever propertiy changes.
086 *
087 * @override Always
088 */
089 public void addPropertyChangeListener(PropertyChangeListener pcl);
090
091 /**
092 * Stop a listener from receiving events whenever a property changes.
093 *
094 * @override Always
095 */
096 public void removePropertyChangeListener(PropertyChangeListener pcl);
097
098 /**
099 * Add a PropertyChangeListener that will receive events whenever the "name" property changes.
100 *
101 * @override Always
102 */
103 public void addNameListener(PropertyChangeListener pcl);
104
105 /**
106 * Remove a PropertyChangeListener for the "name" property.
107 *
108 * @override Always
109 */
110 public void removeNameListener(PropertyChangeListener pcl);
111
112 /**
113 * The programmatical name of the "name" property. This is "name".
114 */
115 public final static String NAME_PROPERTY = "name";
116 }