001: /*
002: * This is free software, licensed under the Gnu Public License (GPL)
003: * get a copy from <http://www.gnu.org/licenses/gpl.html>
004: * $Id: PropertyHolder.java,v 1.4 2004/03/07 14:22:02 hzeller Exp $
005: * author: Henner Zeller <H.Zeller@acm.org>
006: */
007: package henplus.property;
008:
009: import java.util.Iterator;
010:
011: /**
012: * A Property is something that has a value and is bound to
013: * some name. The binding to a name is done elsewhere, the
014: * PropertyHolder holds the value and informs a callback method
015: * on change. It provides a simple way of completing values, if
016: * possible to aid the shell. The PropertyHolder is abstract, since it
017: * needs to be overwritten to get informed on changes of its value. Since
018: * a property is always <em>special</em> in a sense that changing the
019: * property does change some internal state, possibly by calling several
020: * methods, code is always executed on change.
021: */
022: public abstract class PropertyHolder {
023: protected String _propertyValue;
024:
025: /**
026: * construct a PropertyHolder with an empty value.
027: */
028: protected PropertyHolder() {
029: this (null);
030: }
031:
032: protected PropertyHolder(String initialValue) {
033: _propertyValue = initialValue;
034: }
035:
036: /**
037: * set the new value of this property. If changing the property
038: * does not work for e.g. a constraint propblem, then this method will
039: * throw an Exception and the property is <em>not</em> set.
040: * Also, after calling setValue(), the internal value of the property
041: * might not exactly the value given, but some canonicalized form
042: * returned by the {@link #propertyChanged(String)} listener method.
043: *
044: * @param newValue the new value to be set.
045: */
046: public void setValue(String newValue) throws Exception {
047: _propertyValue = propertyChanged(newValue);
048: }
049:
050: /**
051: * The canonicalized value of the value of this Property.
052: */
053: public String getValue() {
054: return _propertyValue;
055: }
056:
057: public abstract String getDefaultValue();
058:
059: /**
060: * is called, when the property changes. This method
061: * is supposed to do whatever is needed on change of the
062: * property.
063: * It returns a canonicalized version of the new value,
064: * or the value itself, if it is cool with it. If the value
065: * is not of the expected range, then this method must
066: * throw an Exception.
067: *
068: * @param newValue a new value of the property. The old value
069: * is still accessible with the {@link #getValue()}
070: * method.
071: * @return the canonicalized value. e.g. for a Property taking
072: * boolean values, it returns all '1', '0', 'on', 'off' as
073: * 'true', 'false'.
074: */
075: protected abstract String propertyChanged(String newValue)
076: throws Exception;
077:
078: /**
079: * given a partial value of a to-be-set value, this will return
080: * an iterator of possible values possible at that point or 'null'
081: * if no such completion can take place.
082: *
083: * @param partialValue a partial given value
084: * @return an Iterator of values that all start with the given String or
085: * <code>null</code> if no such completion exists.
086: */
087: public Iterator completeValue(String partialValue) {
088: return null;
089: }
090:
091: //-- something for the build-in help
092: /**
093: * return a short string describing the purpose of this property
094: * Should contain no newline, no leading spaces and should not be
095: * longer than 40 characters.
096: */
097: public String getShortDescription() {
098: return null;
099: }
100:
101: /**
102: * returns a longer string describing this property. This should return
103: * a String describing details of the given command. This String should
104: * start with a TAB-character in each new line (the first line is a
105: * new line). The last line should not end with newline. Should fit on a
106: * 80 character width terminal.
107: */
108: public String getLongDescription() {
109: return null;
110: }
111: }
112:
113: /*
114: * Local variables:
115: * c-basic-offset: 4
116: * compile-command: "ant -emacs -find build.xml"
117: * End:
118: */
|