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: /** Property is a simple data object that contains one typed value. This
041: * interface contains methods to inspect and modify the stored value and its
042: * type, and the object's read-only state.
043: *
044: * Property also defines the events ReadOnlyStatusChangeEvent and
045: * ValueChangeEvent, and the associated listener and notifier interfaces.
046: *
047: * The Property.Viewer interface should be used to attach the Property to
048: * an external data source. This way the value in the data source can be
049: * inspected using the Property interface.
050: *
051: * The Property.editor interface should be implemented if the value needs to
052: * be changed through the implementing class.
053: *
054: * @author IT Mill Ltd
055: * @version 3.1.1
056: * @since 3.0
057: */
058: public interface Property {
059:
060: /** Gets the value stored in the Property.
061: *
062: * @return the value stored in the Property
063: */
064: public Object getValue();
065:
066: /** Sets the value of the Property.
067: *
068: * Implementing this functionality is optional. If the functionality
069: * is missing, one should declare the Property to be in read-only mode
070: * and throw Property.ReadOnlyException in this function.
071: *
072: * It is not required, but highly recommended to support setting
073: * the value also as a <code>String</code> in addition to the native
074: * type of the Property (as given by the <code>getType</code> method).
075: * If the <code>String</code> conversion fails or is unsupported, the
076: * method should throw </code>Property.ConversionException</code>. The
077: * string conversion should at least understand the format returned by
078: * the <code>toString()</code> method of the Property.
079: *
080: * @param newValue New value of the Property. This should be assignable
081: * to the type returned by <code>getType</code>, but also String type
082: * should be supported
083: *
084: * @throws Property.ReadOnlyException if the object is in read-only
085: * mode
086: * @throws Property.ConversionException if <code>newValue</code> can't
087: * be converted into the Property's native type directly or through
088: * String
089: */
090: public void setValue(Object newValue)
091: throws Property.ReadOnlyException,
092: Property.ConversionException;
093:
094: /** Returns the value of the Property in human readable textual format.
095: * The return value should be assignable to the <code>setValue</code>
096: * method if the Property is not in read-only mode.
097: *
098: * @return <code>String</code> representation of the value stored in the
099: * Property
100: */
101: public String toString();
102:
103: /** Returns the type of the Property. The methods <code>getValue</code>
104: * and <code>setValue</code> must be compatible with this type: one
105: * must be able to safely cast the value returned from
106: * <code>getValue</code> to the given type and pass any variable
107: * assignable to this type as an argument to <code>setValue</code>.
108: *
109: * @return type of the Property
110: */
111: public Class getType();
112:
113: /** Tests if the Property is in read-only mode. In read-only mode calls
114: * to the method <code>setValue</code> will throw
115: * <code>ReadOnlyException</code>s and will not modify the value of the
116: * Property.
117: *
118: * @return <code>true</code> if the Property is in read-only mode,
119: * <code>false</code> if it's not
120: */
121: public boolean isReadOnly();
122:
123: /** Sets the Property's read-only mode to the specified status.
124: *
125: * This functionality is optional, but all properties must implement
126: * the <code>isReadOnly()</code> mode query correctly.
127: *
128: * @param newStatus new read-only status of the Property
129: */
130: public void setReadOnly(boolean newStatus);
131:
132: /** <code>Exception</code> object that signals that a requested
133: * Property modification failed because it's in read-only mode.
134: * @author IT Mill Ltd.
135: * @version 3.1.1
136: * @since 3.0
137: */
138: public class ReadOnlyException extends RuntimeException {
139:
140: /**
141: * Serial generated by eclipse.
142: */
143: private static final long serialVersionUID = 3257571702287119410L;
144:
145: /** Constructs a new <code>ReadOnlyException</code> without a detail
146: * message.
147: */
148: public ReadOnlyException() {
149: }
150:
151: /** Constructs a new <code>ReadOnlyException</code> with the
152: * specified detail message.
153: *
154: * @param msg the detail message
155: */
156: public ReadOnlyException(String msg) {
157: super (msg);
158: }
159: }
160:
161: /** An exception that signals that the value passed to the
162: * <code>setValue()</code> method couldn't be converted to the native
163: * type of the Property.
164: * @author IT Mill Ltd
165: * @version 3.1.1
166: * @since 3.0
167: */
168: public class ConversionException extends RuntimeException {
169:
170: /**
171: * Serial generated by eclipse.
172: */
173: private static final long serialVersionUID = 3257571706666366008L;
174:
175: /** Constructs a new <code>ConversionException</code> without a
176: * detail message.
177: */
178: public ConversionException() {
179: }
180:
181: /** Constructs a new <code>ConversionException</code> with the
182: * specified detail message.
183: *
184: * @param msg the detail message
185: */
186: public ConversionException(String msg) {
187: super (msg);
188: }
189:
190: /** Constructs a new <code>ConversionException</code> from another
191: * exception.
192: *
193: * @param cause The cause of the the conversion failure
194: */
195: public ConversionException(Throwable cause) {
196: super (cause.toString());
197: }
198: }
199:
200: /** Interface implemented by the viewer classes capable of using a
201: * Property as a data source.
202: * @author IT Mill Ltd.
203: * @version 3.1.1
204: * @since 3.0
205: */
206: public interface Viewer {
207:
208: /** Set the Property that serves as the data source of the viewer.
209: *
210: * @param newDataSource the new data source Property
211: */
212: public void setPropertyDataSource(Property newDataSource);
213:
214: /** Get the Property serving as the data source of the viewer.
215: *
216: * @return the Property serving as the viewers data source
217: */
218: public Property getPropertyDataSource();
219: }
220:
221: /** Interface implemented by the editor classes capable of editing the
222: * Property. Implementing this interface means that the Property serving
223: * as the data source of the editor can be modified through the editor.
224: * It does not restrict the editor from editing the Property internally,
225: * though if the Property is in a read-only mode, attempts to modify it
226: * will result in the <code>ReadOnlyException</code> being thrown.
227: * @author IT Mill Ltd.
228: * @version 3.1.1
229: * @since 3.0
230: */
231: public interface Editor extends Property.Viewer {
232:
233: }
234:
235: /* Value change event ******************************************* */
236:
237: /** An <code>Event</code> object specifying the Property whose value
238: * has been changed.
239: * @author IT Mill Ltd.
240: * @version 3.1.1
241: * @since 3.0
242: */
243: public interface ValueChangeEvent {
244:
245: /** Retrieves the Property that has been modified.
246: *
247: * @return source Property of the event
248: */
249: public Property getProperty();
250: }
251:
252: /** The listener interface for receiving ValueChangeEvent objects.
253: * @author IT Mill Ltd.
254: * @version 3.1.1
255: * @since 3.0
256: **/
257: public interface ValueChangeListener {
258:
259: /** Notifies this listener that the Property's value has changed.
260: *
261: * @param event value change event object
262: */
263: public void valueChange(Property.ValueChangeEvent event);
264: }
265:
266: /** The interface for adding and removing <code>ValueChangeEvent</code>
267: * listeners. If a Property wishes to allow other objects to receive
268: * <code>ValueChangeEvent</code>s generated by it, it must implement
269: * this interface.
270: *
271: * Note that the general Java convention is not to explicitly declare
272: * that a class generates events, but to directly define the
273: * <code>addListener</code> and <code>removeListener</code> methods.
274: * That way the caller of these methods has no real way of finding out
275: * if the class really will send the events, or if it just defines the
276: * methods to be able to implement an interface.
277: * @author IT Mill Ltd.
278: * @version 3.1.1
279: * @since 3.0
280: */
281: public interface ValueChangeNotifier {
282:
283: /** Registers a new value change listener for this Property.
284: *
285: * @param listener the new Listener to be registered
286: */
287: public void addListener(Property.ValueChangeListener listener);
288:
289: /** Removes a previously registered value change listener.
290: *
291: * @param listener listener to be removed
292: */
293: public void removeListener(Property.ValueChangeListener listener);
294: }
295:
296: /* ReadOnly Status change event ***************************************** */
297:
298: /** An <code>Event</code> object specifying the Property whose read-only
299: * status has been changed.
300: * @author IT Mill Ltd.
301: * @version 3.1.1
302: * @since 3.0
303: */
304: public interface ReadOnlyStatusChangeEvent {
305:
306: /** Property whose read-only state has changed.
307: *
308: * @return source Property of the event.
309: */
310: public Property getProperty();
311: }
312:
313: /** The listener interface for receiving ReadOnlyStatusChangeEvent
314: * objects.
315: * @author IT Mill Ltd.
316: * @version 3.1.1
317: * @since 3.0
318: * */
319: public interface ReadOnlyStatusChangeListener {
320:
321: /** Notifies this listener that a Property's read-only status has
322: * changed.
323: *
324: * @param event Read-only status change event object
325: */
326: public void readOnlyStatusChange(
327: Property.ReadOnlyStatusChangeEvent event);
328: }
329:
330: /** The interface for adding and removing
331: * <code>ReadOnlyStatusChangeEvent</code> listeners. If a Property
332: * wishes to allow other objects to receive
333: * <code>ReadOnlyStatusChangeEvent</code>s generated by it, it must
334: * implement this interface.
335: *
336: * Note that the general Java convention is not to explicitly declare
337: * that a class generates events, but to directly define the
338: * <code>addListener</code> and <code>removeListener</code> methods.
339: * That way the caller of these methods has no real way of finding out
340: * if the class really will send the events, or if it just defines the
341: * methods to be able to implement an interface.
342: * @author IT Mill Ltd.
343: * @version 3.1.1
344: * @since 3.0
345: */
346: public interface ReadOnlyStatusChangeNotifier {
347:
348: /** Registers a new read-only status change listener for this
349: * Property.
350: *
351: * @param listener the new Listener to be registered
352: */
353: public void addListener(
354: Property.ReadOnlyStatusChangeListener listener);
355:
356: /** Remove a previously registered read-only status change listener.
357: *
358: * @param listener listener to be removed
359: */
360: public void removeListener(
361: Property.ReadOnlyStatusChangeListener listener);
362: }
363: }
|