reviewed new CachingTransformationPVMs - minor tweaks, comments

4 files changed, 88 insertions, 46 deletions

diff --git a/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationPropertyValueModel.java b/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationPropertyValueModel.java
index 3f584aa496..a2d1e6157d 100644
--- a/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationPropertyValueModel.java
+++ b/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationPropertyValueModel.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2008 Oracle. All rights reserved.
+ * Copyright (c) 2008 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -15,9 +15,12 @@ import org.eclipse.jpt.utility.model.value.PropertyValueModel;
 /**
  * A <code>CachingTransformationPropertyValueModel</code> wraps another
  * <code>PropertyValueModel</code> and uses a <code>Transformer</code>
- * to transform the wrapped value before it is returned by <code>value()</code>.
- * It also caches the value so that a transform is not done on the oldValue when
- * firing a property change event. 
+ * to transform the wrapped value before it is returned by <code>getValue()</code>.
+ * The transformed value is calculated and cached during initialization and every
+ * time the wrapped value changes. This can be useful when the old value
+ * passed in to <code>valueChanged(PropertyChangeEvent)</code> can no longer
+ * be "transformed" because its state is no longer valid.
+ * This caching can also improve time performance in some situations.
  * <p>
  * As an alternative to building a <code>Transformer</code>,
  * a subclass of <code>CachingTransformationPropertyValueModel</code> can
@@ -27,16 +30,16 @@ import org.eclipse.jpt.utility.model.value.PropertyValueModel;
  */
 public class CachingTransformationPropertyValueModel<T1, T2>
 	extends TransformationPropertyValueModel<T1, T2>
-	implements PropertyValueModel<T2>
 {
 
 	/**
 	 * Cache the transformed value so that during property change event notification
-	 * we do not have to transform the value.  The oldValue could no longer be valid in
-	 * the model, thus transforming it would not be valid.
+	 * we do not have to transform the old value. The old value could no longer be valid in
+	 * the model; as a result, transforming it would not be valid.
 	 */
 	protected T2 cachedValue;
-	
+
+
 	// ********** constructors/initialization **********
 
 	/**
@@ -57,40 +60,53 @@ public class CachingTransformationPropertyValueModel<T1, T2>
 	public CachingTransformationPropertyValueModel(PropertyValueModel<? extends T1> valueHolder, Transformer<T1, T2> transformer) {
 		super(valueHolder, transformer);
 	}
-	
+
+
 	// ********** behavior **********
 
+	/**
+	 * We have listeners, transform the nested value and cache the result.
+	 */
 	@Override
 	protected void engageValueHolder() {
 		super.engageValueHolder();
 		this.cachedValue = this.transform(this.valueHolder.getValue());
 	}
-	
+
+	/**
+	 * We have no more listeners, clear the cached value.
+	 */
 	@Override
 	protected void disengageValueHolder() {
-		super.disengageValueHolder();
 		this.cachedValue = null;
+		super.disengageValueHolder();
 	}
 
+	/**
+	 * No need to transform the nested value, simply return the cached value,
+	 * which is already transformed.
+	 */
 	@Override
 	public T2 getValue() {
 		return this.cachedValue;
 	}
-	
+
 	/**
-	 * Transform the new value, caching it before returning it
+	 * Transform the specified new value, caching it before returning it.
 	 */
 	@Override
 	protected T2 transformNew(T1 value) {
 		this.cachedValue = super.transformNew(value);
 		return this.cachedValue;
-	};
-	
+	}
+
 	/**
-	 * no transformation, just return the cachedValue which is already transformed
+	 * No need to transform the old value, simply return the cached value,
+	 * which is already transformed.
 	 */
 	@Override
 	protected T2 transformOld(T1 value) {
 		return this.cachedValue;
 	}
+
 }
diff --git a/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationWritablePropertyValueModel.java b/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationWritablePropertyValueModel.java
index 1d97e46fca..18b6ce0bdc 100644
--- a/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationWritablePropertyValueModel.java
+++ b/jpa/plugins/org.eclipse.jpt.utility/src/org/eclipse/jpt/utility/internal/model/value/CachingTransformationWritablePropertyValueModel.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2008 Oracle. All rights reserved.
+ * Copyright (c) 2008 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -10,75 +10,98 @@
 package org.eclipse.jpt.utility.internal.model.value;
 
 import org.eclipse.jpt.utility.internal.BidiTransformer;
-import org.eclipse.jpt.utility.model.value.PropertyValueModel;
 import org.eclipse.jpt.utility.model.value.WritablePropertyValueModel;
 
 /**
- * A <code>TransformationPropertyValueModel</code> wraps another
- * <code>PropertyValueModel</code> and uses a <code>Transformer</code>
- * to transform the wrapped value before it is returned by <code>value()</code>.
- * <p>
- * As an alternative to building a <code>Transformer</code>,
- * a subclass of <code>TransformationPropertyValueModel</code> can
- * either override the <code>transform_(Object)</code> method or,
- * if something other than null should be returned when the wrapped value
- * is null, override the <code>transform(Object)</code> method.
+ * A <code>CachingTransformationWritablePropertyValueModel<code> augments the
+ * behavior of a <code>TransformationWritablePropertyValueModel<code> by caching
+ * the transformed value.
+ * The transformed value is calculated and cached during initialization and every
+ * time the wrapped value changes. This can be useful when the old value
+ * passed in to <code>valueChanged(PropertyChangeEvent)</code> can no longer
+ * be "transformed" because its state is no longer valid.
+ * This caching can also improve time performance in some situations.
  */
 public class CachingTransformationWritablePropertyValueModel<T1, T2>
 	extends TransformationWritablePropertyValueModel<T1, T2>
-	implements PropertyValueModel<T2>
 {
 
+	/**
+	 * Cache the transformed value so that during property change event notification
+	 * we do not have to transform the old value. The old value could no longer be valid in
+	 * the model; as a result, transforming it would not be valid.
+	 */
 	protected T2 cachedValue;
-	
+
+
 	// ********** constructors/initialization **********
 
 	/**
-	 * Construct a property value model with the specified nested
-	 * property value model and the default transformer.
+	 * Construct a writable property value model with the specified nested
+	 * writable property value model and the default bidi transformer.
 	 * Use this constructor if you want to override the
-	 * <code>transform_(Object)</code> or <code>transform(Object)</code>
-	 * method instead of building a <code>Transformer</code>.
+	 * <code>transform_(Object)</code> and <code>reverseTransform_(Object)</code>
+	 * (or <code>transform(Object)</code> and <code>reverseTransform(Object)</code>)
+	 * methods instead of building a <code>BidiTransformer</code>.
 	 */
 	public CachingTransformationWritablePropertyValueModel(WritablePropertyValueModel<T1> valueHolder) {
 		super(valueHolder);
 	}
 
 	/**
-	 * Construct an property value model with the specified nested
-	 * property value model and transformer.
+	 * Construct a writable property value model with the specified nested
+	 * writable property value model and bidi transformer.
 	 */
 	public CachingTransformationWritablePropertyValueModel(WritablePropertyValueModel<T1> valueHolder, BidiTransformer<T1, T2> transformer) {
 		super(valueHolder, transformer);
 	}
-	
+
+
 	// ********** behavior **********
 
+	/**
+	 * We have listeners, transform the nested value and cache the result.
+	 */
 	@Override
 	protected void engageValueHolder() {
 		super.engageValueHolder();
 		this.cachedValue = this.transform(this.valueHolder.getValue());
 	}
-	
+
+	/**
+	 * We have no more listeners, clear the cached value.
+	 */
 	@Override
 	protected void disengageValueHolder() {
-		super.disengageValueHolder();
 		this.cachedValue = null;
+		super.disengageValueHolder();
 	}
 
+	/**
+	 * No need to transform the nested value, simply return the cached value,
+	 * which is already transformed.
+	 */
 	@Override
 	public T2 getValue() {
 		return this.cachedValue;
 	}
-	
+
+	/**
+	 * Transform the specified new value, caching it before returning it.
+	 */
 	@Override
 	protected T2 transformNew(T1 value) {
 		this.cachedValue = super.transformNew(value);
 		return this.cachedValue;
-	};
-	
+	}
+
+	/**
+	 * No need to transform the old value, simply return the cached value,
+	 * which is already transformed.
+	 */
 	@Override
 	protected T2 transformOld(T1 value) {
 		return this.cachedValue;
 	}
+
 }
diff --git a/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationPropertyValueModelTests.java b/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationPropertyValueModelTests.java
index fd6ff2ae34..62c56b993f 100644
--- a/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationPropertyValueModelTests.java
+++ b/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationPropertyValueModelTests.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2008 Oracle. All rights reserved.
+ * Copyright (c) 2008 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -20,6 +20,7 @@ import org.eclipse.jpt.utility.model.value.PropertyValueModel;
 import org.eclipse.jpt.utility.model.value.WritablePropertyValueModel;
 import org.eclipse.jpt.utility.tests.internal.TestTools;
 
+@SuppressWarnings("nls")
 public class CachingTransformationPropertyValueModelTests extends TestCase {
 	private WritablePropertyValueModel<Person> objectHolder;
 	PropertyChangeEvent event;
@@ -58,7 +59,6 @@ public class CachingTransformationPropertyValueModelTests extends TestCase {
 	public void testValue() {
 		PropertyChangeListener listener = this.buildTransformationListener();
 		this.transformationObjectHolder.addPropertyChangeListener(listener);
-
 		
 		Person person = this.objectHolder.getValue();
 		assertEquals("Karen", person.getName());
@@ -174,10 +174,10 @@ public class CachingTransformationPropertyValueModelTests extends TestCase {
 	private class Person extends AbstractModel {
 
 		private String name;
-			public static final String NAME_PROPERTY = "nameProperty";
+			public static final String NAME_PROPERTY = "name";
 		
 		private String parentName;
-			public static final String PARENT_NAME_PROPERTY = "parentNameProperty";
+			public static final String PARENT_NAME_PROPERTY = "parentName";
 		
 		private Person child;
 		
@@ -214,5 +214,7 @@ public class CachingTransformationPropertyValueModelTests extends TestCase {
 		public Person getChild() {
 			return this.child;
 		}
+
 	}
+
 }
diff --git a/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationWritablePropertyValueModelTests.java b/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationWritablePropertyValueModelTests.java
index 023c3134dd..72fd1288c3 100644
--- a/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationWritablePropertyValueModelTests.java
+++ b/jpa/tests/org.eclipse.jpt.utility.tests/src/org/eclipse/jpt/utility/tests/internal/model/value/CachingTransformationWritablePropertyValueModelTests.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2008 Oracle. All rights reserved.
+ * Copyright (c) 2008 Oracle. All rights reserved.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v1.0, which accompanies this distribution
  * and is available at http://www.eclipse.org/legal/epl-v10.html.
@@ -21,6 +21,7 @@ import org.eclipse.jpt.utility.tests.internal.TestTools;
 
 import junit.framework.TestCase;
 
+@SuppressWarnings("nls")
 public class CachingTransformationWritablePropertyValueModelTests extends TestCase {
 	private WritablePropertyValueModel<Person> objectHolder;
 	PropertyChangeEvent event;