*** empty log message ***
diff --git a/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPDataModelSynchHelper.java b/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPDataModelSynchHelper.java
index a9a29d5..5f7aa37 100644
--- a/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPDataModelSynchHelper.java
+++ b/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPDataModelSynchHelper.java
@@ -168,7 +168,7 @@
public void propertyChanged(WTPOperationDataModelEvent event) {
String propertyName = event.getPropertyName();
int flag = event.getFlag();
- if (flag == WTPOperationDataModelListener.ENABLE_CHG)
+ if (flag == WTPOperationDataModelEvent.ENABLE_CHG)
setEnablement(propertyName, ((Boolean) event.getNewValue()).booleanValue());
else
synchUIWithModel(propertyName, flag);
@@ -290,7 +290,7 @@
}
protected void setWidgetValue(String propertyName, int flag, Combo combo) {
- if (flag == WTPOperationDataModelListener.VALID_VALUES_CHG || combo.getItemCount() == 0) {
+ if (flag == WTPOperationDataModelEvent.VALID_VALUES_CHG || combo.getItemCount() == 0) {
// Display properties should only fire if the contents change.
WTPPropertyDescriptor[] descriptors = dataModel.getValidPropertyDescriptors(propertyName);
String[] items = new String[descriptors.length];
@@ -411,7 +411,7 @@
String propertyName = null;
while (propertyNames.hasNext()) {
propertyName = (String) propertyNames.next();
- synchUIWithModel(propertyName, WTPOperationDataModelListener.PROPERTY_CHG);
+ synchUIWithModel(propertyName, WTPOperationDataModelEvent.PROPERTY_CHG);
}
}
}
@@ -429,7 +429,7 @@
widgetToDepControls = new HashMap();
widgetToDepControls.put(widget, depControls);
}
- synchUIWithModel(propertyName, WTPOperationDataModelListener.PROPERTY_CHG);
+ synchUIWithModel(propertyName, WTPOperationDataModelEvent.PROPERTY_CHG);
}
public void synchText(Text text, String propertyName, Control[] dependentControls) {
diff --git a/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPWizardPage.java b/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPWizardPage.java
index 2b2bb95..35549de 100644
--- a/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPWizardPage.java
+++ b/plugins/org.eclipse.wst.common.frameworks.ui/wtp_ui/org/eclipse/wst/common/frameworks/ui/WTPWizardPage.java
@@ -384,7 +384,7 @@
*/
public void propertyChanged(WTPOperationDataModelEvent event) {
String propertyName = event.getPropertyName();
- if (validationPropertyNames != null && (event.getFlag() == PROPERTY_CHG || (!isPageComplete() && event.getFlag() == VALID_VALUES_CHG))) {
+ if (validationPropertyNames != null && (event.getFlag() == WTPOperationDataModelEvent.PROPERTY_CHG || (!isPageComplete() && event.getFlag() == WTPOperationDataModelEvent.VALID_VALUES_CHG))) {
for (int i = 0; i < validationPropertyNames.length; i++) {
if (validationPropertyNames[i].equals(propertyName)) {
validatePage();
diff --git a/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModel.java b/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModel.java
index 82f0de5..0a719eb 100644
--- a/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModel.java
+++ b/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModel.java
@@ -47,8 +47,8 @@
* <LI>Compose and decompose entire DataModels through nesting.</LI>
* </UL>
*
- * <B>PropertyNames</B> Clients interact with DataModels by getting and setting properties (Objects)
- * with PropertyNames. A PropertyName is a String Object uniquely identifing a particular
+ * <B>PropertyNames </B> Clients interact with DataModels by getting and setting properties
+ * (Objects) with PropertyNames. A PropertyName is a String Object uniquely identifing a particular
* property. The recommended practice for defining PropertyNames is to define them as static final
* Class level Strings and to use the DataModel instance class name appended with the property name
* as the value (this should ensure uniqueness and gives a readible value when debugging).
@@ -270,6 +270,33 @@
throw new RuntimeException(PROPERTY_NOT_LOCATED_ + propertyName);
}
+ /**
+ * <p>
+ * Returns a WTPPropertyDescriptor array consisting of all valid WTPPropertyDescriptors for the
+ * specified property. Each WTPPropertyDescriptor {@see WTPPropertyDescriptor for details}
+ * 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 DataModel. 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, the a 0 length array is returned. <code>null</code> is never
+ * returned.
+ * </p>
+ * <p>
+ * As an example, suppose there is a property called <code>SHIRT_SIZE</code> which is an
+ * <code>Integer</code> 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 <code>getValidPropertyDescriptors(SHIRT_SIZE)</code> would return a
+ * WTPPropertyDescriptor array where the value, description pairs would be {(1, small), (2,
+ * medium), (3, large)}.
+ * </p>
+ * <p>
+ * Subclasses should override {@see #doGetValidPropertyDescriptors(String)}as necessary.
+ * </p>
+ *
+ * @param propertyName
+ * @return
+ * @see #getPropertyDescriptor(String)
+ * @see #doGetPropertyDescriptor(String)
+ */
public final WTPPropertyDescriptor[] getValidPropertyDescriptors(String propertyName) {
checkValidPropertyName(propertyName);
if (isBaseProperty(propertyName)) {
@@ -288,15 +315,45 @@
}
/**
- * Subclasses may override to provide specific valid property values for the given propertyName.
+ * Subclasses should override this method to return their set of valid WTPPropertyDescriptors.
+ * This default implementation returns: <code>new WTPPropertyDescriptor[0];</code>
*
* @param propertyName
* @return
+ *
+ * @see #getValidPropertyDescriptors(String)
*/
protected WTPPropertyDescriptor[] doGetValidPropertyDescriptors(String propertyName) {
return new WTPPropertyDescriptor[0];
}
+ /**
+ * <p>
+ * Returns a WTPPropertyDescriptor for the specified property. The
+ * <code>getPropertyValue()</code> method on the returned WTPPropertyDescriptor will be the
+ * same value as returned by <code>getPropertyValue(propertyName)</code>.
+ * </p>
+ * <p>
+ * Following the example introduced in {@see #getValidPropertyDescriptors(String)}, suppose the
+ * <code>SHIRT_SIZE</code> property is currently set to 1. A call to this method would return
+ * a WTPPropertyDescriptor whose <code>getPropertyValue()</code> returns <code>1</code> and
+ * whose <code>getPropertyDescription()</code> returns <code>small</code>.
+ * </p>
+ * <p>
+ * Also, note that even if a particular property is not confined to a finite set of values as
+ * defined by {@see #getValidPropertyDescriptors(String)}this method will always return a valid
+ * WTPPropertyDescriptor.
+ * </p>
+ * <p>
+ * Subclasses should should override {@see #doGetPropertyDescriptor(String)}as necessary.
+ * </p>
+ *
+ * @param propertyName
+ * @return
+ *
+ * @see #getValidPropertyDescriptors(String)
+ * @see #doGetPropertyDescriptor(String)
+ */
public final WTPPropertyDescriptor getPropertyDescriptor(String propertyName) {
checkValidPropertyName(propertyName);
if (isBaseProperty(propertyName)) {
@@ -314,6 +371,13 @@
throw new RuntimeException(PROPERTY_NOT_LOCATED_ + propertyName);
}
+ /**
+ * Subclasses should override this method as necessary. This default implementation returns
+ * <code>new WTPPropertyDescriptor(getProperty(propertyName));</code>.
+ *
+ * @param propertyName
+ * @return
+ */
protected WTPPropertyDescriptor doGetPropertyDescriptor(String propertyName) {
return new WTPPropertyDescriptor(getProperty(propertyName));
}
@@ -463,14 +527,17 @@
/**
* <p>
* Returns the property value for the specified propertyName.
+ * </p>
* <p>
- * If the specified propertyName is not a property (see#isProperty(String)) then a
+ * If the specified propertyName is not a property {@see #isProperty(String)}then a
* RuntimeException will be thrown.
+ * </p>
* <p>
- * If the specified propertyName is a base property (see#isBaseProperty(String)) then it will
+ * If the specified propertyName is a base property {@see #isBaseProperty(String)}then it will
* immediatly be set and nested models will not be affected. If it is not a base property (i.e.
* it is a property for a nested DataModel) then a recursive search through nested DataModels
* will be conducted. The first nested DataModel having the property will return its value.
+ * </p>
*
* @param propertyName
* @return
@@ -478,10 +545,12 @@
* <p>
* There are also convenience methods for getting properties representing property types of
* boolean, int, and String
- * <p>
- * @see #getBooleanProperty(String)
- * @see #getIntProperty(String)
- * @see #getStringProperty(String)
+ * </p>
+ * <ul>
+ * <li>{@see #getBooleanProperty(String)}</li>
+ * <li>{@see #getIntProperty(String)}</li>
+ * <li>{@see #getStringProperty(String)}</li>
+ * </ul>
*/
public final Object getProperty(String propertyName) {
checkValidPropertyName(propertyName);
@@ -612,7 +681,7 @@
* @param propertyValue
*/
public void notifyListeners(String propertyName, Object oldValue, Object propertyValue) {
- notifyListeners(propertyName, PROPERTY_CHG, oldValue, propertyValue);
+ notifyListeners(propertyName, WTPOperationDataModelEvent.PROPERTY_CHG, oldValue, propertyValue);
}
/**
@@ -828,13 +897,13 @@
* @param propertyName
*/
public void notifyValidValuesChange(String propertyName) {
- notifyListeners(propertyName, WTPOperationDataModelListener.VALID_VALUES_CHG, null, null);
+ notifyListeners(propertyName, WTPOperationDataModelEvent.VALID_VALUES_CHG, null, null);
}
protected void notifyEnablementChange(String propertyName) {
Boolean enable = isEnabled(propertyName);
if (enable != null)
- notifyListeners(propertyName, ENABLE_CHG, null, enable);
+ notifyListeners(propertyName, WTPOperationDataModelEvent.ENABLE_CHG, null, enable);
}
public void dispose() {
@@ -851,7 +920,7 @@
/**
* @return Returns the locked.
*/
- protected boolean isLocked() {
+ protected final boolean isLocked() {
return locked;
}
@@ -859,7 +928,7 @@
* @param locked
* The locked to set.
*/
- protected void setLocked(boolean locked) {
+ protected final void setLocked(boolean locked) {
this.locked = locked;
if (locked)
hasBeenExecutedAgainst = true;
@@ -923,7 +992,7 @@
public boolean hasBeenExecutedAgainst() {
return hasBeenExecutedAgainst;
}
-
+
///////////////////////////////////////////////////////////////////////////////////////////////
//TODO figure out the best way support ExtendedOperations
///////////////////////////////////////////////////////////////////////////////////////////////
diff --git a/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModelListener.java b/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModelListener.java
index 1d3698b..8dbf0be 100644
--- a/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModelListener.java
+++ b/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPOperationDataModelListener.java
@@ -8,27 +8,34 @@
**************************************************************************************************/
package org.eclipse.wst.common.frameworks.operations;
+/**
+ * Clients wishing to register with a WTPOperationData to receive WTPOperationDataModelEvents need
+ * to implement this interface.
+ *
+ * @see org.eclipse.wst.common.frameworks.operations.WTPOperationDataModel#addListener(WTPOperationDataModelListener)
+ */
public interface WTPOperationDataModelListener {
/**
- * Flags associated with the propertyChanged event. <code>PROPERTY_CHG</code>= A simple
- * property change. <code>VALID_VALUES_CHG</code>= The valid values for the given property
- * have changed. <code>ENABLE_CHG</code>= The enablement for the given property has changed.
+ * Use WTPOperationDataModelEvent.PROPERTY_CHG instead.
+ * @deprecated
*/
final int PROPERTY_CHG = WTPOperationDataModelEvent.PROPERTY_CHG;
- final int VALID_VALUES_CHG = WTPOperationDataModelEvent.VALID_VALUES_CHG;
- final int ENABLE_CHG = WTPOperationDataModelEvent.ENABLE_CHG;
-
+
/**
- * A property has changed on the model with the given propertyName. Use the flag to detect the
- * type of change.
+ * Use WTPOperationDataModelEvent.VALID_VALUES_CHG instead.
+ * @deprecated
+ */
+ final int VALID_VALUES_CHG = WTPOperationDataModelEvent.VALID_VALUES_CHG;
+
+ /**
+ * Use WTPOperationDataModelEvent.ENABLE_CHG instead.
+ * @deprecated
+ */
+ final int ENABLE_CHG = WTPOperationDataModelEvent.ENABLE_CHG;
+ /**
+ * This method is invoked on listening clients when a property changes.
*
- * @param propertyName
- * @param flag
- * @param oldValue
- * @param newValue
- *
- * @see WTPOperationDataModelListener#PROPERTY_CHG
- * @see WTPOperationDataModelListener#VALID_VALUES_CHG
+ * @param event
*/
void propertyChanged(WTPOperationDataModelEvent event);
diff --git a/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPPropertyDescriptor.java b/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPPropertyDescriptor.java
index 22a779d..9114863 100644
--- a/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPPropertyDescriptor.java
+++ b/plugins/org.eclipse.wst.common.frameworks/src/org/eclipse/wst/common/frameworks/operations/WTPPropertyDescriptor.java
@@ -1,14 +1,24 @@
-/*
- * Created on Nov 18, 2004
- * @author jsholl
- */
package org.eclipse.wst.common.frameworks.operations;
+//TODO link to an example in the tutorial
/**
- * @author jsholl
+ * A WTPPropertyDescriptor provides a human readible description for a WTPDataModel propertyValue.
+ *
+ * @see org.eclipse.wst.common.frameworks.operations.WTPOperationDataModel#getPropertyDescriptor(String)
+ * @see org.eclipse.wst.common.frameworks.operations.WTPOperationDataModel#getValidPropertyDescriptors(String)
*/
public class WTPPropertyDescriptor {
+ /**
+ * A convenience method which returns an array of WTPPropertyDescriptors. If <code>values</code>
+ * is <code>null</code> then a 0 length array is returned. Otherwise for each
+ * <code>values[i]</code> in the array, a new WTPPropertyDescriptor is created using
+ * <code>new WTPPropertyDescriptor(values[i]);</code>.
+ *
+ * @param values
+ * the array of property values
+ * @return the constructed WTPPropertyDescriptor array
+ */
public static WTPPropertyDescriptor[] createDescriptors(Object[] values) {
if (null == values) {
return new WTPPropertyDescriptor[0];
@@ -20,6 +30,20 @@
return descriptors;
}
+ /**
+ * A convenience method which returns an array of WTPPropertyDescriptors. If <code>values</code>
+ * is <code>null</code> then a 0 length array is returned. Otherwise for each
+ * <code>values[i]</code> and <code>descriptions[i]</code> in the arrays, a new
+ * WTPPropertyDescriptor is created using
+ * <code>new WTPPropertyDescriptor(values[i], descriptions[i]);</code>. Both arrays must be
+ * the same length.
+ *
+ * @param values
+ * the array of property values
+ * @param descriptions
+ * the array of property descriptions cooresponding the values array
+ * @return the constructed WTPPropertyDescriptor array
+ */
public static WTPPropertyDescriptor[] createDescriptors(Object[] values, String[] descriptions) {
if (null == values) {
return new WTPPropertyDescriptor[0];
@@ -35,19 +59,43 @@
private Object propertyValue;
private String propertyDescription;
+ /**
+ * This is equavalent to calling <code>WTPPropertyDescriptor(propertyValue, null);</code>
+ *
+ * @param propertyValue
+ */
public WTPPropertyDescriptor(Object propertyValue) {
this.propertyValue = propertyValue;
}
+ /**
+ * Creates a new WTPPropertyDescriptor with the specified propertyValue and propertyDescription.
+ *
+ * @param propertyValue
+ * @param propertyDescription
+ */
public WTPPropertyDescriptor(Object propertyValue, String propertyDescription) {
this.propertyValue = propertyValue;
this.propertyDescription = propertyDescription;
}
+ /**
+ * Returns the property value.
+ *
+ * @return the property value
+ */
public Object getPropertyValue() {
return propertyValue;
}
+ /**
+ * Returns a human readible property description. If a non null description has been specified,
+ * then it will be returned. Otherwise, the property value's <code>toString()</code> will be
+ * returned if it is not null. Otherwise the empty String (<code>""</code>) will be
+ * returned. Null will never be returned.
+ *
+ * @return the human readible property description, never <code>null</code>
+ */
public String getPropertyDescription() {
if (null != propertyDescription) {
return propertyDescription;
