org.eclipse.wst.common.frameworks.datamodel
Interface IDataModel


public interface IDataModel

IDataModels are the core piece of a framework used to simplify data collection, operation execution, and Wizard generation.

IDataModels are primarily an intelligent mechanism for managing data. Each IDataModel tracks specific Objects known as "properties". Each property may be set or get using its property name. A Collection of property names for an IDataModel instance may be retreived using getAllProperties(). In addition to getting/setting properties, IDataModels may also provide default values for unset properties, human readable descriptors for properties, enumerations of valid property values, validation for properties, and enablement for properties.

IDataModels may also be nested (and unnested) recursively within another. When one IDataModel is nested within another, then client code may access all properties on the former through the latter. This is especially useful when the same IDataModel (tracking the same properties) may be used within the context of several different broader scenarios. Nesting may apply to any IDataModel, and may be abitraryly deep (even cylical if you dare). Nesting offers flexibility, especially for extension by 3rd party clients.

Each IDataModel may also supply an IDataModelOperation (a subclass of org.eclipse.core.commands.operations.IUndoableOperation) for execution. When executed within the IDataModel framework all these operations are inherently and abitrarily extendable.

Each IDataModel may also indirectly supply a DataModelWizard. This indirection is necessary to spilt UI dependencies from the core IDataModel framework. DataModelWizards are also inherently extendable.

IDataModels are not meant to be instantiated directly, rather they are built from an IDataModelProvider. Clients wishing to define their own IDataModel must do so by implementing an IDataModelProvider. Clients wishing to utilize an IDataModel must create it using the DataModelFactory with the associated IDataModelProvider.

This interface is not intended to be implemented by clients.

Since:
1.0
See Also:
IDataModelProvider, DataModelFactory

Field Summary
static int DEFAULT_CHG
           A constant used for notification.
static int ENABLE_CHG
           A constant used for notification.
static int VALID_VALUES_CHG
           A constant used for notification.
static int VALUE_CHG
           A constant used for notification.
 
Method Summary
 void addListener(IDataModelListener dataModelListener)
           Adds the specified IDataModelListener to listen for DataModelEvents.
 boolean addNestedModel(java.lang.String nestedModelName, IDataModel dataModel)
           This method is used to nest the specified IDataModel within this IDataModel.
 void dispose()
           A typical dispose method used to clean up any resources not handled by general garbage collection.
 java.util.Collection getAllProperties()
           Returns a Collection of all properties (the union of getBaseProperties() and getNestedProperties()), or an empty Collection if none exist.
 java.util.Collection getBaseProperties()
           Returns a Collection of all base properties (not including nested properties), or an empty Collection if none exist.
 boolean getBooleanProperty(java.lang.String propertyName)
           A convenience method for getting booleans.
 IDataModelOperation getDefaultOperation()
           Returns the default operation to execute against this IDataModel.
 java.lang.Object getDefaultProperty(java.lang.String propertyName)
           Returns the default property value for the specified propertyName.
 java.util.List getExtendedContext()
           This method only pertains to IDataModels for extedended operations.
 java.lang.String getID()
           Returns the unique ID which identifies this IDataModel instance.
 int getIntProperty(java.lang.String propertyName)
           A convenience method for getting ints.
 IDataModel getNestedModel(java.lang.String nestedModelName)
           Returns the nested IDataModel identified the by the specified name.
 java.util.Collection getNestedModelNames()
           Returns a Collection of all nested IDataModels names, or an empty Collection if none exist.
 java.util.Collection getNestedModels()
           Returns a Collection of all nested IDataModels, or an empty Collection if none exist.
 java.util.Collection getNestedProperties()
           Returns a Collection of all properties of recursively nested IDataModels, or an empty Collection if none exist.
 java.util.Collection getNestingModels()
           Returns a Collection of all nesting (the inverse of nested) IDataModels, or an empty Collection if none exist.
 java.lang.Object getProperty(java.lang.String propertyName)
           Returns the property value for the specified propertyName.
 DataModelPropertyDescriptor getPropertyDescriptor(java.lang.String propertyName)
           Returns a DataModelPropertyDescriptor for the specified property.
 java.lang.String getStringProperty(java.lang.String propertyName)
           A convenience method for getting Strings.
 DataModelPropertyDescriptor[] getValidPropertyDescriptors(java.lang.String propertyName)
           Returns a DataModelPropertyDescriptor array consisting of all valid DataModelPropertyDescriptors for the specified property.
 boolean isBaseProperty(java.lang.String propertyName)
           Returns true if the specified propertyName is a valid propertyName for this root IDataModel only.
 boolean isNestedModel(java.lang.String nestedModelName)
           Returns true if a nested model exists (at the top level only) with the specified name and false otherwise.
 boolean isNestedProperty(java.lang.String propertyName)
           Returns true if the specified propertyName is a valid propertyName for any of its (recursively) nested IDataModels.
 boolean isProperty(java.lang.String propertyName)
           Returns true if the specified propertyName is a valid propertyName for this DataModel or any of its (recursively) nested IDataModels.
 boolean isPropertyEnabled(java.lang.String propertyName)
           Returns true if the specified property is enabled and false otherwise.
 boolean isPropertySet(java.lang.String propertyName)
           Returns true if the specified property has been set on the IDataModel.
 boolean isPropertyValid(java.lang.String propertyName)
           Returns false if the the IStatus returned by validateProperty(String) is ERROR and true otherwise.
 boolean isValid()
           Returns false if the IStatus returned by validate(true) is ERROR and true otherwise.
 void notifyPropertyChange(java.lang.String propertyName, int eventType)
           Notify all listeners of a property change.
 void removeListener(IDataModelListener dataModelListener)
           Remove the specified IDataModelListener.
 IDataModel removeNestedModel(java.lang.String nestedModelName)
           Remove the specified nestedModel.
 void setBooleanProperty(java.lang.String propertyName, boolean propertyValue)
           A convenience method for setting booleans.
 void setIntProperty(java.lang.String propertyName, int propertyValue)
           A convenience method for setting ints.
 void setProperty(java.lang.String propertyName, java.lang.Object propertyValue)
           Sets the specified propertyName to the specified propertyValue.
 void setStringProperty(java.lang.String propertyName, java.lang.String propertyValue)
           A convenience method for setting Strings.
 org.eclipse.core.runtime.IStatus validate()
           Equavalent to calling validate(true).
 org.eclipse.core.runtime.IStatus validate(boolean stopAtFirstFailure)
           Iterates over all base properties and nested models IDs and calls validate(String).
 org.eclipse.core.runtime.IStatus validateProperty(java.lang.String propertyName)
           Returns an IStatus for the specified property.
 

Field Detail

VALUE_CHG

static final int VALUE_CHG

A constant used for notification.

See Also:
DataModelEvent.VALUE_CHG, notifyPropertyChange(String, int), Constant Field Values

DEFAULT_CHG

static final int DEFAULT_CHG

A constant used for notification. This contant is different from the others because it does not map to an event type on DataModelEvent. When notifying with this type, a check is first done to see whether the property is set. If the property is NOT set, then a VALUE_CHG is fired, otherwise nothing happens.

See Also:
notifyPropertyChange(String, int), Constant Field Values

ENABLE_CHG

static final int ENABLE_CHG

A constant used for notification.

See Also:
DataModelEvent.ENABLE_CHG, notifyPropertyChange(String, int), Constant Field Values

VALID_VALUES_CHG

static final int VALID_VALUES_CHG

A constant used for notification.

See Also:
DataModelEvent.VALID_VALUES_CHG, notifyPropertyChange(String, int), Constant Field Values
Method Detail

getID

java.lang.String getID()

Returns the unique ID which identifies this IDataModel instance. The same ID should be used by the default operation (if any) for clients to extend or instantiate directly, the DataModelWizard (if any) for clients to extend or instantiate directly.

Note, this is not the same as a hashcode. Multiple IDataModel instances created with the same IDataModelProvider type will all have the same ID.

An IDataModel implementor defines this in IDataModelProvider.

Returns:
the unique ID for this IDataModel
See Also:
IDataModelProvider.getID()

getDefaultOperation

IDataModelOperation getDefaultOperation()

Returns the default operation to execute against this IDataModel. The returned operation is derived from the operation supplied by the backing IDataModelProvider. The returned type is IDataModelManagerOperation which adds additional functionality to the returned IDataModelOperation.

An IDataModel implementor defines this in IDataModelProvider.

Returns:
the default operation
See Also:
IDataModelProvider.getDefaultOperation()

getExtendedContext

java.util.List getExtendedContext()

This method only pertains to IDataModels for extedended operations. The returned extended context is used by the IDataModelOperation framework to determine whether a particular extended operation should execute. The returned list is should contain Objects adaptable to IProject. This IDataModel's function groups are looked up through the extension mechanism. If a function group is defined, it is first checked for enablement. Then each adapted IProject is inspected to verify it handles the function group. If all these conditions are met, then the extended operation associated with this IDataModel is executed; otherwise it is skipped. If no function group is defined, or no extended context is defined (i.e. this method returns an empty list, or the objects in the returned list are not adaptable to IProject) then the extended operation will execute (it will never be skipped).

An IDataModel implementor defines this in IDataModelProvider.

This method should not be called by clients.

Returns:
a List of Objects adaptable to IProject
See Also:
IDataModelProvider.getExtendedContext()

getProperty

java.lang.Object getProperty(java.lang.String propertyName)

Returns the property value for the specified propertyName.

If the specified propertyName is not a property then a RuntimeException will be thrown.

Before the property is returned, first the owning IDataModel must be located. If the specified propertyName is a base property isBaseProperty(String), then this IDataModel is the owner. Otherwise, a recursive search through the nested IDataModels is conducted to locate the owning IDataModel. If more than one nested IDataModel defines the property, then the first one located is considered the owning IDataModel.

Once the owning IDataModel is found the property is checked to see if it is set isPropertySet(String). If the property is set, the set value is returned. If the property is not set, its default is returned getDefaultProperty(String).

There are convenience methods for getting primitive int and boolean types as well as Strings.

Parameters:
propertyName - the property name
Returns:
the property
See Also:
setProperty(String, Object), getBooleanProperty(String), getIntProperty(String), getStringProperty(String)

getDefaultProperty

java.lang.Object getDefaultProperty(java.lang.String propertyName)

Returns the default property value for the specified propertyName.

An IDataModel implementor defines this in IDataModelProvider.

See Also:
IDataModelProvider.getDefaultProperty(String)

getIntProperty

int getIntProperty(java.lang.String propertyName)

A convenience method for getting ints. If the property is set then this method is equavalent to:

((Integer)getProperty(propertyName)).intValue();

-1 is returned if a call to getProperty(propertyName) returns null.

Parameters:
propertyName - the property name
Returns:
the int value of the property
See Also:
setProperty(String, Object), setIntProperty(String, int)

getBooleanProperty

boolean getBooleanProperty(java.lang.String propertyName)

A convenience method for getting booleans. If the property is set then this method is equavalent to:

((Boolean)getProperty(propertyName)).booleanValue();

false is returned if a call to getProperty(propertyName) returns null.

Parameters:
propertyName - the property name
Returns:
the boolean value of the property
See Also:
setProperty(String, Object), setBooleanProperty(String, boolean)

getStringProperty

java.lang.String getStringProperty(java.lang.String propertyName)

A convenience method for getting Strings. If the property is set then this method is equavalent to:

(String)getProperty(propertyName)

"" is returned if a call to getProperty(propertyName) returns null.

Parameters:
propertyName -
See Also:
setProperty(String, Object)

setProperty

void setProperty(java.lang.String propertyName,
                 java.lang.Object propertyValue)

Sets the specified propertyName to the specified propertyValue. Subsequent calls to getProperty(String) will return the same propertyValue.

When a propertyValue other than null is set, then the property is considered "set" (see isPropertySet(String)), conversly, a propertyValue of null is considered "unset".

If the specified propertyName is not a property (see isProperty(String)) then a RuntimeException will be thrown.

There are convenience methods for setting primitive int and boolean types as well as Strings.

An IDataModel implementor may define additional post set logic in IDataModelProvider.propertySet(String, Object).

Parameters:
propertyName - the name of the property to set
propertyValue - the value to set the property
See Also:
getProperty(String), isPropertySet(String), isProperty(String), IDataModelProvider.propertySet(String, Object)

setIntProperty

void setIntProperty(java.lang.String propertyName,
                    int propertyValue)

A convenience method for setting ints. This method is equavalent to:

setProperty(propertyName, new Integer(propertyValue));

Parameters:
propertyName - the name of the property
propertyValue - the int value of the property
See Also:
setProperty(String, Object), getIntProperty(String)

setBooleanProperty

void setBooleanProperty(java.lang.String propertyName,
                        boolean propertyValue)

A convenience method for setting booleans. This method is equavalent to:

setProperty(propertyName, (value) ? Boolean.TRUE : Boolean.FALSE);

Parameters:
propertyName - the name of the property
propertyValue - the boolean value of the property
See Also:
setProperty(String, Object), getBooleanProperty(String)

setStringProperty

void setStringProperty(java.lang.String propertyName,
                       java.lang.String propertyValue)

A convenience method for setting Strings. This method is equavalent to:

setProperty(propertyName, propertyValue);

Parameters:
propertyName - the name of the property
propertyValue - the value of the property
See Also:
setProperty(String, Object), getStringProperty(String)

addNestedModel

boolean addNestedModel(java.lang.String nestedModelName,
                       IDataModel dataModel)

This method is used to nest the specified IDataModel within this IDataModel. The nestedModelName argument should be a unique String to identify this particular nested IDataModel. The same String is required when accessing the nested IDataModel using either getNestedModel(String) or removeNestedModel(String). If the specified nested IDataModel has already been nested under this IDataModel or it is the same instance as this IDataModel, then calling this method will have no effect.

Parameters:
nestedModelName - the name of the IDataModel to be nested
dataModel - the IDataModel to be nested
Returns:
true if the nesting was successful, false otherwise.
See Also:
getNestedModel(String), removeNestedModel(String)

removeNestedModel

IDataModel removeNestedModel(java.lang.String nestedModelName)

Remove the specified nestedModel.

Parameters:
nestedModelName - the name of the nested IDataModel to remove.
Returns:
the IDataModel removed, or null if the nested model does not exist or if the specified name is null.

isNestedModel

boolean isNestedModel(java.lang.String nestedModelName)

Returns true if a nested model exists (at the top level only) with the specified name and false otherwise.

Parameters:
nestedModelName - the name of the nested IDataModel to check.
Returns:
Returns true if a nested model exists (at the top level only) with the specified name and false otherwise.

getNestedModel

IDataModel getNestedModel(java.lang.String nestedModelName)

Returns the nested IDataModel identified the by the specified name. A RuntimeException is thrown if there is no such nested IDataModel (i.e. isNestedModel() would return false).

Parameters:
nestedModelName - the name of the nested IDataModel to get.
Returns:
the nested IDataModel

getNestedModels

java.util.Collection getNestedModels()

Returns a Collection of all nested IDataModels, or an empty Collection if none exist.

Returns:
a Collection of all nested IDataModels, or an empty Collection if none exist.

getNestedModelNames

java.util.Collection getNestedModelNames()

Returns a Collection of all nested IDataModels names, or an empty Collection if none exist.

Returns:
a Collection of all nested IDataModels names, or an empty Collection if none exist.

getNestingModels

java.util.Collection getNestingModels()

Returns a Collection of all nesting (the inverse of nested) IDataModels, or an empty Collection if none exist.

Returns:
a Collection of all nesting (the inverse of nested) IDataModels, or an empty Collection if none exist.

getBaseProperties

java.util.Collection getBaseProperties()

Returns a Collection of all base properties (not including nested properties), or an empty Collection if none exist.

Returns:
a Collection of all base properties (not including nested properties), or an empty Collection if none exist.

getNestedProperties

java.util.Collection getNestedProperties()

Returns a Collection of all properties of recursively nested IDataModels, or an empty Collection if none exist.

Returns:
a Collection of all properties of recursively nested IDataModels, or an empty Collection if none exist.

getAllProperties

java.util.Collection getAllProperties()

Returns a Collection of all properties (the union of getBaseProperties() and getNestedProperties()), or an empty Collection if none exist.

Returns:
a Collection of all properties (the union of getBaseProperties() and getNestedProperties()), or an empty Collection if none exist.

isBaseProperty

boolean isBaseProperty(java.lang.String propertyName)

Returns true if the specified propertyName is a valid propertyName for this root IDataModel only. Nested IDataModels are not checked, though it is possible for a nested IDataModel to contain the same property.

Parameters:
propertyName - the property name to check
Returns:
true if this property is a base property, false otherwise.
See Also:
isProperty(String), isNestedProperty(String)

isProperty

boolean isProperty(java.lang.String propertyName)

Returns true if the specified propertyName is a valid propertyName for this DataModel or any of its (recursively) nested IDataModels.

Parameters:
propertyName - the property name to check
Returns:
true if this is a property, false otherwise.
See Also:
isBaseProperty(String)

isNestedProperty

boolean isNestedProperty(java.lang.String propertyName)

Returns true if the specified propertyName is a valid propertyName for any of its (recursively) nested IDataModels. The root IDataModel is not checked, though it is possible for the root IDataModel to contain the same property.

Parameters:
propertyName - the property name to check
Returns:
true if the property is nested, false otherwise.
See Also:
isBaseProperty(String)

isPropertySet

boolean isPropertySet(java.lang.String propertyName)

Returns true if the specified property has been set on the IDataModel. If it has not been set, then a call to get the same property will return the default value.

Parameters:
propertyName - the property name to check
Returns:
true if the property is set, false otherwise.

isPropertyEnabled

boolean isPropertyEnabled(java.lang.String propertyName)

Returns true if the specified property is enabled and false otherwise.

An IDataModel implementor defines this in IDataModelProvider.

Parameters:
propertyName - the property name to check
Returns:
true if the specified property is enabled and false otherwise.
See Also:
IDataModelProvider.isPropertyEnabled(String)

isPropertyValid

boolean isPropertyValid(java.lang.String propertyName)

Returns false if the the IStatus returned by validateProperty(String) is ERROR and true otherwise.

Parameters:
propertyName - the property name to check
Returns:
false if the the IStatus returned by validateProperty(String) is ERROR and true otherwise.

validateProperty

org.eclipse.core.runtime.IStatus validateProperty(java.lang.String propertyName)

Returns an IStatus for the specified property. Retuns an IStatus.OK if the returned value is valid with respect itself, other properites, and broader context of the IDataModel. IStatus.ERROR is returned if the returned value is invalid. IStatus.WARNING may also be returned if the value is not optimal.

An IDataModel implementor defines this in IDataModelProvider.

See Also:
IDataModelProvider.validate(String)

isValid

boolean isValid()

Returns false if the IStatus returned by validate(true) is ERROR and true otherwise.

Returns:
false if the IStatus returned by validate(true) is ERROR and true otherwise.

validate

org.eclipse.core.runtime.IStatus validate()

Equavalent to calling validate(true).

Returns:
an IStatus

validate

org.eclipse.core.runtime.IStatus validate(boolean stopAtFirstFailure)

Iterates over all base properties and nested models IDs and calls validate(String). This method returns when any call to validate(String) returns an IStatus error and stopAtFirstFailure is set to true.

Parameters:
stopAtFirstFailure - whether validation should stop at the first failure
Returns:
an IStatus

getPropertyDescriptor

DataModelPropertyDescriptor getPropertyDescriptor(java.lang.String propertyName)

Returns a DataModelPropertyDescriptor for the specified property. The getPropertyValue() method on the returned DataModelPropertyDescriptor will be the same value as returned by getPropertyValue(propertyName).

Following the example introduced in getValidPropertyDescriptors(String), suppose the SHIRT_SIZE property is currently set to 1. A call to this method would return a DataModelPropertyDescriptor whose getPropertyValue() returns 1 and whose getPropertyDescription() returns small.

Also, note that even if a particular property is not confined to a finite set of values as defined by getValidPropertyDescriptors(String)this method will always return a valid DataModelPropertyDescriptor.

An IDataModel implementor defines this in IDataModelProvider.

Parameters:
propertyName -
Returns:
the DataModelPropertyDescriptor for the specified property
See Also:
getValidPropertyDescriptors(String)

getValidPropertyDescriptors

DataModelPropertyDescriptor[] getValidPropertyDescriptors(java.lang.String propertyName)

Returns a DataModelPropertyDescriptor array consisting of all valid DataModelPropertyDescriptors for the specified property. Each DataModelPropertyDescriptor contains a value and a human readible description for the value. The set of all values in the returned array are those values which are valid for the IDataModel. This value set only makes sense when valid property values conform to a well defined finite set. If no such value set exists for the property, then a 0 length array is returned. null is never returned.

As an example, suppose there is a property called SHIRT_SIZE which is an Integer type. Also suppse that valid shirt sizes are only small, medium, or large. However, the actual values representing small, medium, and large are 1, 2, and 3 respectively. A call to getValidPropertyDescriptors(SHIRT_SIZE) would return a DataModelPropertyDescriptor array where the value, description pairs would be {(1, small), (2, medium), (3, large)}.

An IDataModel implementor defines this in IDataModelProvider.

Parameters:
propertyName - then name of the property to check
Returns:
the array of valid DataModelPropertyDescriptors
See Also:
getPropertyDescriptor(String)

addListener

void addListener(IDataModelListener dataModelListener)

Adds the specified IDataModelListener to listen for DataModelEvents. If the specified listener has already been added, calling this method will have no effect.

Parameters:
dataModelListener - the new listener to add.
See Also:
removeListener(IDataModelListener)

removeListener

void removeListener(IDataModelListener dataModelListener)

Remove the specified IDataModelListener. If the specified listener is not a registered listenr on this IDataModel, then calling this method will have no effect.

Parameters:
dataModelListener - the listener to remove.
See Also:
addListener(IDataModelListener)

notifyPropertyChange

void notifyPropertyChange(java.lang.String propertyName,
                          int eventType)

Notify all listeners of a property change. eventType specifies the type of change. Acceptible values for eventType are VALUE_CHG, DEFAULT_CHG, ENABLE_CHG, VALID_VALUES_CHG. If the eventType is DEFAULT_CHG and the specified property is set, then this method will do nothing.

Typically this method should only be invoked by an IDataModelProvider from its propertySet implementation.

Parameters:
propertyName - the name of the property changing
eventType - the type of event to fire
See Also:
VALUE_CHG, DEFAULT_CHG, ENABLE_CHG, VALID_VALUES_CHG, DataModelEvent

dispose

void dispose()

A typical dispose method used to clean up any resources not handled by general garbage collection.