001: /* *************************************************************************
002:
003: Millstone(TM)
004: Open Sourced User Interface Library for
005: Internet Development with Java
006:
007: Millstone is a registered trademark of IT Mill Ltd
008: Copyright (C) 2000-2005 IT Mill Ltd
009:
010: *************************************************************************
011:
012: This library is free software; you can redistribute it and/or
013: modify it under the terms of the GNU Lesser General Public
014: license version 2.1 as published by the Free Software Foundation.
015:
016: This library is distributed in the hope that it will be useful,
017: but WITHOUT ANY WARRANTY; without even the implied warranty of
018: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019: Lesser General Public License for more details.
020:
021: You should have received a copy of the GNU Lesser General Public
022: License along with this library; if not, write to the Free Software
023: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024:
025: *************************************************************************
026:
027: For more information, contact:
028:
029: IT Mill Ltd phone: +358 2 4802 7180
030: Ruukinkatu 2-4 fax: +358 2 4802 7181
031: 20540, Turku email: info@itmill.com
032: Finland company www: www.itmill.com
033:
034: Primary source for MillStone information and releases: www.millstone.org
035:
036: ********************************************************************** */
037:
038: package org.millstone.base.data;
039:
040: import java.util.Collection;
041:
042: /** <p>Provides a mechanism for handling a set of Properties, each associated
043: * to a locally unique identifier. The interface is split into subinterfaces
044: * to enable a class to implement only the functionalities it needs.</p>
045: *
046: * @author IT Mill Ltd
047: * @version 3.1.1
048: * @since 3.0
049: */
050: public interface Item {
051:
052: /** Gets the Property corresponding to the given Property ID stored in
053: * the Item. If the Item does not contain the Property,
054: * <code>null</code> is returned.
055: *
056: * @param id identifier of the Property to get
057: * @return the Property with the given ID or <code>null</code>
058: */
059: public Property getItemProperty(Object id);
060:
061: /** Gets the collection of IDs of all Properties stored in the Item.
062: *
063: * @return unmodifiable collection containing IDs of the Properties
064: * stored the Item
065: */
066: public Collection getItemPropertyIds();
067:
068: /** Tries to add a new Property into the Item.
069: *
070: * <p>This functionality is optional.</p>
071: *
072: * @param id ID of the new Property
073: * @param property the Property to be added and associated with
074: * <code>id</code>
075: * @throws UnsupportedOperationException if the operation is not supported.
076: * @return <code>true</code> if the operation succeeded,
077: * <code>false</code> if not
078: */
079: public boolean addItemProperty(Object id, Property property)
080: throws UnsupportedOperationException;
081:
082: /** Removes the Property identified by ID from the Item.
083:
084: * <p>This functionality is optional.</p>
085: *
086: * @param id ID of the Property to be removed
087: * @throws UnsupportedOperationException if the operation is not supported.
088: * @return <code>true</code> if the operation succeeded
089: * <code>false</code> if not
090: */
091: public boolean removeItemProperty(Object id)
092: throws UnsupportedOperationException;
093:
094: /** Interface implemented by viewer classes capable of using an Item as
095: * a data source.
096: */
097: public interface Viewer {
098:
099: /** Sets the Item that serves as the data source of the viewer.
100: *
101: * @param newDataSource The new data source Item
102: */
103: public void setItemDataSource(Item newDataSource);
104:
105: /** Gets the Item serving as the data source of the viewer.
106: *
107: * @return data source Item
108: */
109: public Item getItemDataSource();
110: }
111:
112: /** Interface implemented by the editor classes capable of editing the
113: * Item. Implementing this interface means that the Item serving as the
114: * data source of the editor can be modified through it. Note that
115: * not implementing the <code>Item.Editor</code> interface does not
116: * restrict the class from editing the contents of an internally.
117: */
118: public interface Editor extends Item.Viewer {
119:
120: }
121:
122: /* Property set change event ******************************************** */
123:
124: /** An <code>Event</code> object specifying the Item whose contents
125: * has been changed through the Property.Managed interface. Note that
126: * the values stored in the Properties may change without triggering
127: * this event.
128: */
129: public interface PropertySetChangeEvent {
130:
131: /** Retrieves the Item whose contents has been modified.
132: *
133: * @return source Item of the event
134: */
135: public Item getItem();
136: }
137:
138: /** The listener interface for receiving
139: * <code>PropertySetChangeEvent</code> objects.
140: */
141: public interface PropertySetChangeListener {
142:
143: /** Notifies this listener that the Item's property set has changed.
144: *
145: * @param event Property set change event object
146: */
147: public void itemPropertySetChange(
148: Item.PropertySetChangeEvent event);
149: }
150:
151: /** The interface for adding and removing
152: * <code>PropertySetChangeEvent</code> listeners. By implementing this
153: * interface a class explicitly announces that it will generate a
154: * <code>PropertySetChangeEvent</code> when its Property set is
155: * modified.
156: *
157: * Note that the general Java convention is not to explicitly declare
158: * that a class generates events, but to directly define the
159: * <code>addListener</code> and <code>removeListener</code> methods.
160: * That way the caller of these methods has no real way of finding out
161: * if the class really will send the events, or if it just defines the
162: * methods to be able to implement an interface.
163: */
164: public interface PropertySetChangeNotifier {
165:
166: /** Registers a new property set change listener for this Item.
167: *
168: * @param listener The new Listener to be registered.
169: */
170: public void addListener(Item.PropertySetChangeListener listener);
171:
172: /** Removes a previously registered property set change listener.
173: *
174: * @param listener Listener to be removed.
175: */
176: public void removeListener(
177: Item.PropertySetChangeListener listener);
178: }
179: }
|