mapping javadoc

spring-binding/src/main/java/org/springframework/binding/mapping/Mapping.java

@@ -17,10 +17,25 @@ package org.springframework.binding.mapping;
 
 import org.springframework.binding.expression.Expression;
 
+/**
+ * Information about a single mapping.
+ * 
+ * @author Keith Donald
+ */
 public interface Mapping {
+
+	/**
+	 * The source of the mapping.
+	 */
 	public Expression getSourceExpression();
 
+	/**
+	 * The target of the mapping.
+	 */
 	public Expression getTargetExpression();
 
+	/**
+	 * Whether this is a required mapping.
+	 */
 	public boolean isRequired();
 }

spring-binding/src/main/java/org/springframework/binding/mapping/MappingResult.java

@@ -1,20 +1,34 @@
 package org.springframework.binding.mapping;
 
+/**
+ * A single mapping result within a {@link MappingResults} transaction.
+ */
 public class MappingResult {
 
 	private Mapping mapping;
 
 	private Result result;
 
+	/**
+	 * Creates a new mapping result.
+	 * @param mapping the mapping that executed
+	 * @param result the result of executing the mapping
+	 */
 	public MappingResult(Mapping mapping, Result result) {
 		this.mapping = mapping;
 		this.result = result;
 	}
 
+	/**
+	 * Returns the mapping that executed.
+	 */
 	public Mapping getMapping() {
 		return mapping;
 	}
 
+	/**
+	 * Returns the result of executing the mapping.
+	 */
 	public Result getResult() {
 		return result;
 	}

spring-binding/src/main/java/org/springframework/binding/mapping/MappingResults.java

@@ -2,18 +2,42 @@ package org.springframework.binding.mapping;
 
 import java.util.List;
 
+/**
+ * Exposes information about the results of a mapping transaction.
+ * 
+ * @author Keith Donald
+ */
 public interface MappingResults {
 
+	/**
+	 * The source object that was mapped from.
+	 */
 	public Object getSource();
 
+	/**
+	 * The target object that was mapped to.
+	 */
 	public Object getTarget();
 
+	/**
+	 * A list of all the mapping results between the source and target.
+	 */
 	public List getAllResults();
 
+	/**
+	 * Whether some results were errors. Returns true if mapping errors occurred.
+	 */
 	public boolean hasErrorResults();
 
+	/**
+	 * A list of all error results that occurred.
+	 */
 	public List getErrorResults();
 
+	/**
+	 * Get all results that meet the given result criteria.
+	 * @param criteria the mapping result criteria
+	 */
 	public List getResults(MappingResultsCriteria criteria);
 
 }

spring-binding/src/main/java/org/springframework/binding/mapping/MappingResultsCriteria.java

@@ -1,5 +1,16 @@
 package org.springframework.binding.mapping;
 
+/**
+ * A predicate used to select mapping result objects in a call to
+ * {@link MappingResults#getResults(MappingResultsCriteria)}.
+ * @author Keith Donald
+ */
 public interface MappingResultsCriteria {
+
+	/**
+	 * Tests if the mapping result meets this criteria.
+	 * @param result the result
+	 * @return true if so, false if not
+	 */
 	public boolean test(MappingResult result);
 }

spring-binding/src/main/java/org/springframework/binding/mapping/Result.java

@@ -1,11 +1,30 @@
 package org.springframework.binding.mapping;
 
+/**
+ * Exposes information about the result of a single mapping operation.
+ * @author Keith Donald
+ */
 public abstract class Result {
+
+	/**
+	 * The original value of the source object that was to be mapped. Null if this result is an error on the source
+	 * object.
+	 */
 	public abstract Object getOriginalValue();
 
+	/**
+	 * The actual value that was mapped to the target object. Null if this result is an error.
+	 */
 	public abstract Object getMappedValue();
 
+	/**
+	 * Indicates if this result was an error.
+	 */
 	public abstract boolean isError();
 
+	/**
+	 * If this result was an error, the logical mapping error code; for example "propertyNotFound". Null if this result
+	 * is not an error result.
+	 */
 	public abstract String getErrorCode();
 }

spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapper.java

@@ -26,25 +26,26 @@ import org.springframework.binding.mapping.MappingResults;
 import org.springframework.core.style.ToStringCreator;
 
 /**
- * Generic attributes mapper implementation that allows mappings to be configured programatically.
- * 
- * @author Erwin Vervaet
+ * Generic mapper implementation that allows mappings to be configured programatically.
  * @author Keith Donald
- * @author Colin Sampaleanu
  */
 public class DefaultMapper implements Mapper {
 
-	/**
-	 * The ordered list of mappings to apply.
-	 */
 	private List mappings = new LinkedList();
 
 	private ConversionService conversionService;
 
+	/**
+	 * Returns the conversion service to use to perform type conversions as needed by mapping operations. May be null.
+	 */
 	public ConversionService getConversionService() {
 		return conversionService;
 	}
 
+	/**
+	 * Sets the conversion service to use to perform type conversions as needed by mapping operations. Optional.
+	 * @param conversionService the conversion service;
+	 */
 	public void setConversionService(ConversionService conversionService) {
 		this.conversionService = conversionService;
 	}

spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapping.java

@@ -84,14 +84,26 @@ public class DefaultMapping implements Mapping {
 
 	// optional impl getters/setters
 
+	/**
+	 * Returns the type conversion executor to use during mapping execution. May be null.
+	 */
 	public ConversionExecutor getTypeConverter() {
 		return typeConverter;
 	}
 
+	/**
+	 * Sets a specific type conversion executor to use during mapping execution.
+	 * @param typeConverter the type converter
+	 * @see #map(MappingContext)
+	 */
 	public void setTypeConverter(ConversionExecutor typeConverter) {
 		this.typeConverter = typeConverter;
 	}
 
+	/**
+	 * Indicates if this mapping is a required mapping. Default is false.
+	 * @param required required status
+	 */
 	public void setRequired(boolean required) {
 		this.required = required;
 	}

spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingContext.java

@@ -14,6 +14,10 @@ import org.springframework.binding.mapping.results.Success;
 import org.springframework.binding.mapping.results.TargetAccessError;
 import org.springframework.binding.mapping.results.TypeConversionError;
 
+/**
+ * Default mapping context implementation.
+ * @author Keith Donald
+ */
 class DefaultMappingContext implements MappingContext {
 
 	private Object source;
@@ -53,7 +57,7 @@ class DefaultMappingContext implements MappingContext {
 	}
 
 	public void setSuccessResult(Object originalValue, Object mappedValue) {
-		mappingResults.add(new MappingResult(currentMapping, new Success(originalValue, mappedValue)));
+		mappingResults.add(new MappingResult(currentMapping, new Success(mappedValue, originalValue)));
 		currentMapping = null;
 	}
 

spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingResults.java

@@ -9,6 +9,10 @@ import org.springframework.binding.mapping.MappingResult;
 import org.springframework.binding.mapping.MappingResults;
 import org.springframework.binding.mapping.MappingResultsCriteria;
 
+/**
+ * Default mapping results implementation.
+ * @author Keith Donald
+ */
 public class DefaultMappingResults implements MappingResults {
 
 	private Object source;
@@ -17,6 +21,12 @@ public class DefaultMappingResults implements MappingResults {
 
 	private List mappingResults;
 
+	/**
+	 * Creates a new mapping results object.
+	 * @param source the source
+	 * @param target the target
+	 * @param mappingResults the actual results produced by {@link DefaultMapper}
+	 */
 	public DefaultMappingResults(Object source, Object target, List mappingResults) {
 		this.source = source;
 		this.target = target;

spring-binding/src/main/java/org/springframework/binding/mapping/results/RequiredError.java

@@ -2,10 +2,19 @@ package org.springframework.binding.mapping.results;
 
 import org.springframework.binding.mapping.Result;
 
+/**
+ * The "required" error result--indicates a required mapping could not be performed because the source value to map was
+ * empty.
+ * @author Keith Donald
+ */
 public class RequiredError extends Result {
 
 	private Object originalValue;
 
+	/**
+	 * Creates a new required error result
+	 * @param originalValue the original source value (empty)
+	 */
 	public RequiredError(Object originalValue) {
 		this.originalValue = originalValue;
 	}

spring-binding/src/main/java/org/springframework/binding/mapping/results/SourceAccessError.java

@@ -1,16 +1,29 @@
 package org.springframework.binding.mapping.results;
 
 import org.springframework.binding.expression.EvaluationException;
+import org.springframework.binding.expression.PropertyNotFoundException;
 import org.springframework.binding.mapping.Result;
 
+/**
+ * Indicates an exception occurred accessing the source object to be mapped. Used to report source
+ * {@link PropertyNotFoundException} errors and general {@link EvaluationException} errors.
+ * @author Keith Donald
+ */
 public class SourceAccessError extends Result {
 
 	private EvaluationException error;
 
+	/**
+	 * Creates a new source access error.
+	 * @param error the underlying evaluation exception that occurred
+	 */
 	public SourceAccessError(EvaluationException error) {
 		this.error = error;
 	}
 
+	/**
+	 * Returns the backing source evaluation exception that occurred.
+	 */
 	public EvaluationException getException() {
 		return error;
 	}
@@ -28,7 +41,11 @@ public class SourceAccessError extends Result {
 	}
 
 	public String getErrorCode() {
-		return "sourceAccess";
+		if (error instanceof PropertyNotFoundException) {
+			return "propertyNotFound";
+		} else {
+			return "sourceAccess";
+		}
 	}
 
 }

spring-binding/src/main/java/org/springframework/binding/mapping/results/Success.java

@@ -2,11 +2,21 @@ package org.springframework.binding.mapping.results;
 
 import org.springframework.binding.mapping.Result;
 
+/**
+ * Indicates a successful mapping operation.
+ * @author Keith Donald
+ */
 public class Success extends Result {
 
-	private Object originalValue;
 	private Object mappedValue;
 
+	private Object originalValue;
+
+	/**
+	 * Creates a new success result.
+	 * @param mappedValue the successfully mapped value
+	 * @param originalValue the original value
+	 */
 	public Success(Object mappedValue, Object originalValue) {
 		this.mappedValue = mappedValue;
 		this.originalValue = originalValue;

spring-binding/src/main/java/org/springframework/binding/mapping/results/TargetAccessError.java

@@ -4,17 +4,30 @@ import org.springframework.binding.expression.EvaluationException;
 import org.springframework.binding.expression.PropertyNotFoundException;
 import org.springframework.binding.mapping.Result;
 
+/**
+ * Indicates an exception occurred accessing the target object to be mapped to. Used to report source
+ * {@link PropertyNotFoundException} errors and general {@link EvaluationException} errors.
+ * @author Keith Donald
+ */
 public class TargetAccessError extends Result {
 
 	private Object originalValue;
 
 	private EvaluationException error;
 
+	/**
+	 * Creates a new target access error.
+	 * @param originalValue the value that was attempted to be mapped
+	 * @param error the underlying evaluation exception that occurred
+	 */
 	public TargetAccessError(Object originalValue, EvaluationException error) {
 		this.originalValue = originalValue;
 		this.error = error;
 	}
 
+	/**
+	 * Returns the backing target evaluation exception that occurred.
+	 */
 	public EvaluationException getException() {
 		return error;
 	}

spring-binding/src/main/java/org/springframework/binding/mapping/results/TypeConversionError.java

@@ -2,12 +2,22 @@ package org.springframework.binding.mapping.results;
 
 import org.springframework.binding.mapping.Result;
 
+/**
+ * Indicates a type conversion occurred during a mapping operation.
+ * 
+ * @author Keith Donald
+ */
 public class TypeConversionError extends Result {
 
 	private Object originalValue;
 
 	private Class targetType;
 
+	/**
+	 * Creates a new type conversion error.
+	 * @param originalValue the value that could not be converted
+	 * @param targetType the target type of the conversion
+	 */
 	public TypeConversionError(Object originalValue, Class targetType) {
 		this.originalValue = originalValue;
 		this.targetType = targetType;
@@ -17,10 +27,6 @@ public class TypeConversionError extends Result {
 		return originalValue;
 	}
 
-	public Class getTargetType() {
-		return targetType;
-	}
-
 	public Object getMappedValue() {
 		return null;
 	}
@@ -33,4 +39,13 @@ public class TypeConversionError extends Result {
 		return "typeMismatch";
 	}
 
+	// impl
+
+	/**
+	 * Returns the target type of the conversion attempt.
+	 */
+	public Class getTargetType() {
+		return targetType;
+	}
+
 }