|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 |
---|
static final int VALUE_CHG
A constant used for notification.
DataModelEvent.VALUE_CHG
,
notifyPropertyChange(String, int)
,
Constant Field Valuesstatic 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 VALUE_CHG
is fired, otherwise nothing happens.
notifyPropertyChange(String, int)
,
Constant Field Valuesstatic final int ENABLE_CHG
A constant used for notification.
DataModelEvent.ENABLE_CHG
,
notifyPropertyChange(String, int)
,
Constant Field Valuesstatic final int VALID_VALUES_CHG
A constant used for notification.
DataModelEvent.VALID_VALUES_CHG
,
notifyPropertyChange(String, int)
,
Constant Field ValuesMethod Detail |
---|
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.
IDataModelProvider.getID()
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.
IDataModelProvider.getDefaultOperation()
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.
IDataModelProvider.getExtendedContext()
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.
propertyName
- the property name
setProperty(String, Object)
,
getBooleanProperty(String)
,
getIntProperty(String)
,
getStringProperty(String)
java.lang.Object getDefaultProperty(java.lang.String propertyName)
Returns the default property value for the specified propertyName.
An IDataModel implementor defines this in IDataModelProvider.
IDataModelProvider.getDefaultProperty(String)
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
.
propertyName
- the property name
setProperty(String, Object)
,
setIntProperty(String, int)
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
.
propertyName
- the property name
setProperty(String, Object)
,
setBooleanProperty(String, boolean)
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
.
propertyName
- setProperty(String, Object)
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)
.
propertyName
- the name of the property to setpropertyValue
- the value to set the propertygetProperty(String)
,
isPropertySet(String)
,
isProperty(String)
,
IDataModelProvider.propertySet(String, Object)
void setIntProperty(java.lang.String propertyName, int propertyValue)
A convenience method for setting ints. This method is equavalent to:
setProperty(propertyName, new Integer(propertyValue));
propertyName
- the name of the propertypropertyValue
- the int
value of the propertysetProperty(String, Object)
,
getIntProperty(String)
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);
propertyName
- the name of the propertypropertyValue
- the boolean
value of the propertysetProperty(String, Object)
,
getBooleanProperty(String)
void setStringProperty(java.lang.String propertyName, java.lang.String propertyValue)
A convenience method for setting Strings. This method is equavalent to:
setProperty(propertyName, propertyValue);
propertyName
- the name of the propertypropertyValue
- the value of the propertysetProperty(String, Object)
,
getStringProperty(String)
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.
nestedModelName
- the name of the IDataModel to be nesteddataModel
- the IDataModel to be nested
true
if the nesting was successful, false
otherwise.getNestedModel(String)
,
removeNestedModel(String)
IDataModel removeNestedModel(java.lang.String nestedModelName)
Remove the specified nestedModel.
nestedModelName
- the name of the nested IDataModel to remove.
null
if the nested model does not exist or
if the specified name is null.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.
nestedModelName
- the name of the nested IDataModel to check.
true
if a nested model exists (at the top level only) with the
specified name and false
otherwise.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
).
nestedModelName
- the name of the nested IDataModel to get.
java.util.Collection getNestedModels()
Returns a Collection of all nested IDataModels, or an empty Collection if none exist.
java.util.Collection getNestedModelNames()
Returns a Collection of all nested IDataModels names, 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.util.Collection getBaseProperties()
Returns a Collection of all base properties (not including nested properties), 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 getAllProperties()
Returns a Collection of all properties (the union of getBaseProperties() and getNestedProperties()), or an empty Collection if none exist.
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.
propertyName
- the property name to check
true
if this property is a base property, false
otherwise.isProperty(String)
,
isNestedProperty(String)
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.
propertyName
- the property name to check
true
if this is a property, false
otherwise.isBaseProperty(String)
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.
propertyName
- the property name to check
true
if the property is nested, false
otherwise.isBaseProperty(String)
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.
propertyName
- the property name to check
true
if the property is set, false
otherwise.boolean isPropertyEnabled(java.lang.String propertyName)
Returns true
if the specified property is enabled and false
otherwise.
An IDataModel implementor defines this in IDataModelProvider.
propertyName
- the property name to check
true
if the specified property is enabled and false
otherwise.IDataModelProvider.isPropertyEnabled(String)
boolean isPropertyValid(java.lang.String propertyName)
Returns false
if the the IStatus returned by validateProperty(String) is ERROR
and true
otherwise.
propertyName
- the property name to check
false
if the the IStatus returned by validateProperty(String) is ERROR
and true
otherwise.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.
IDataModelProvider.validate(String)
boolean isValid()
Returns false
if the IStatus returned by validate(true) is ERROR and
true
otherwise.
false
if the IStatus returned by validate(true) is ERROR and
true
otherwise.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). This method returns when any call to validate(String) returns an IStatus error and stopAtFirstFailure is set to true.
stopAtFirstFailure
- whether validation should stop at the first failure
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.
propertyName
-
getValidPropertyDescriptors(String)
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.
propertyName
- then name of the property to check
getPropertyDescriptor(String)
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.
dataModelListener
- the new listener to add.removeListener(IDataModelListener)
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.
dataModelListener
- the listener to remove.addListener(IDataModelListener)
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.
propertyName
- the name of the property changingeventType
- the type of event to fireVALUE_CHG
,
DEFAULT_CHG
,
ENABLE_CHG
,
VALID_VALUES_CHG
,
DataModelEvent
void dispose()
A typical dispose method used to clean up any resources not handled by general garbage collection.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |