* The Property is a simple data object that contains one typed
* value. This interface contains methods to inspect and modify the stored value
* and its type, and the object's read-only state.
*
* The Property also defines the events
* ReadOnlyStatusChangeEvent and ValueChangeEvent,
* and the associated listener and notifier
* interfaces.
*
* The Property.Viewer interface should be used to attach the
* Property to an external data source. This way the value in the data source
* can be inspected using the Property interface.
*
* The Property.editor interface should be implemented if the
* value needs to be changed through the implementing class.
*
* Implementing this functionality is optional. If the functionality is
* missing, one should declare the Property to be in read-only mode and
* throw Property.ReadOnlyException in this function.
*
String in addition to the native type of
* the Property (as given by the getType method). If the
* String conversion fails or is unsupported, the method
* should throw Property.ConversionException. The string
* conversion should at least understand the format returned by the
* toString method of the Property.
*
* @param newValue
* New value of the Property. This should be assignable to
* the type returned by getType, but also String type should
* be supported
*
* @throws Property.ReadOnlyException
* if the object is in read-only mode
* @throws Property.ConversionException
* if newValue can't be converted into the Property's native
* type directly or through String
*/
public void setValue(Object newValue) throws Property.ReadOnlyException,
Property.ConversionException;
/**
* Returns the value of the Property in human readable textual format. The
* return value should be assignable to the setValue method
* if the Property is not in read-only mode.
*
* @return String representation of the value stored in the
* Property
*/
public String toString();
/**
* Returns the type of the Property. The methods getValue and
* setValue must be compatible with this type: one must be
* able to safely cast the value returned from getValue to
* the given type and pass any variable assignable to this type as an
* argument to setValue.
*
* @return type of the Property
*/
public Class getType();
/**
* Tests if the Property is in read-only mode. In read-only mode calls to
* the method setValue will throw
* ReadOnlyException and will not modify the value of the
* Property.
*
* @return true if the Property is in read-only mode,
* false if it's not
*/
public boolean isReadOnly();
/**
* Sets the Property's read-only mode to the specified status.
*
* This functionality is optional, but all properties must implement the
* isReadOnly mode query correctly.
*
* @param newStatus
* new read-only status of the Property
*/
public void setReadOnly(boolean newStatus);
/**
* Exception object that signals that a requested Property
* modification failed because it's in read-only mode.
*
* @author IT Mill Ltd.
* @version
* @VERSION@
* @since 3.0
*/
public class ReadOnlyException extends RuntimeException {
/**
* Serial generated by eclipse.
*/
private static final long serialVersionUID = 3257571702287119410L;
/**
* Constructs a new ReadOnlyException without a detail
* message.
*/
public ReadOnlyException() {
}
/**
* Constructs a new ReadOnlyException with the specified
* detail message.
*
* @param msg
* the detail message
*/
public ReadOnlyException(String msg) {
super(msg);
}
}
/**
* An exception that signals that the value passed to the
* setValue method couldn't be converted to the native type
* of the Property.
*
* @author IT Mill Ltd
* @version
* @VERSION@
* @since 3.0
*/
public class ConversionException extends RuntimeException {
/**
* Serial generated by eclipse.
*/
private static final long serialVersionUID = 3257571706666366008L;
/**
* Constructs a new ConversionException without a detail
* message.
*/
public ConversionException() {
}
/**
* Constructs a new ConversionException with the
* specified detail message.
*
* @param msg
* the detail message
*/
public ConversionException(String msg) {
super(msg);
}
/**
* Constructs a new ConversionException from another
* exception.
*
* @param cause
* The cause of the the conversion failure
*/
public ConversionException(Throwable cause) {
super(cause.toString());
}
}
/**
* Interface implemented by the viewer classes capable of using a Property
* as a data source.
*
* @author IT Mill Ltd.
* @version
* @VERSION@
* @since 3.0
*/
public interface Viewer {
/**
* Sets the Property that serves as the data source of the viewer.
*
* @param newDataSource
* the new data source Property
*/
public void setPropertyDataSource(Property newDataSource);
/**
* Gets the Property serving as the data source of the viewer.
*
* @return the Property serving as the viewers data source
*/
public Property getPropertyDataSource();
}
/**
* Interface implemented by the editor classes capable of editing the
* Property.
*
* Implementing this interface means that the Property serving as the data
* source of the editor can be modified through the editor. It does not
* restrict the editor from editing the Property internally, though if the
* Property is in a read-only mode, attempts to modify it will result in the
* ReadOnlyException being thrown.
*
Event object specifying the Property whose value has
* been changed.
*
* @author IT Mill Ltd.
* @version
* @VERSION@
* @since 3.0
*/
public interface ValueChangeEvent {
/**
* Retrieves the Property that has been modified.
*
* @return source Property of the event
*/
public Property getProperty();
}
/**
* The listener interface for receiving
* ValueChangeEvent objects.
*
* @author IT Mill Ltd.
* @version
* @VERSION@
* @since 3.0
*/
public interface ValueChangeListener {
/**
* Notifies this listener that the Property's value has changed.
*
* @param event
* value change event object
*/
public void valueChange(Property.ValueChangeEvent event);
}
/**
* The interface for adding and removing ValueChangeEvent
* listeners. If a Property wishes to allow other objects to receive
* ValueChangeEvent generated by it, it must implement this
* interface.
*
* Note : The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* addListener and removeListener methods.
* That way the caller of these methods has no real way of finding out if
* the class really will send the events, or if it just defines the methods
* to be able to implement an interface.
*
Event object specifying the Property whose read-only
* status has been changed.
*
* @author IT Mill Ltd.
* @version
* @VERSION@
* @since 3.0
*/
public interface ReadOnlyStatusChangeEvent {
/**
* Property whose read-only state has changed.
*
* @return source Property of the event.
*/
public Property getProperty();
}
/**
* The listener interface for receiving
* ReadOnlyStatusChangeEvent objects.
*
* @author IT Mill Ltd.
* @version
* @VERSION@
* @since 3.0
*/
public interface ReadOnlyStatusChangeListener {
/**
* Notifies this listener that a Property's read-only status has
* changed.
*
* @param event
* Read-only status change event object
*/
public void readOnlyStatusChange(
Property.ReadOnlyStatusChangeEvent event);
}
/**
* The interface for adding and removing
* ReadOnlyStatusChangeEvent listeners. If a Property wishes
* to allow other objects to receive ReadOnlyStatusChangeEvent
* generated by it, it must implement this interface.
*
* Note : The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* addListener and removeListener methods.
* That way the caller of these methods has no real way of finding out if
* the class really will send the events, or if it just defines the methods
* to be able to implement an interface.
*