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    }