diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/Mapping.java b/spring-binding/src/main/java/org/springframework/binding/mapping/Mapping.java index 56b9806a..a6d50cd4 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/Mapping.java +++ b/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(); } \ No newline at end of file diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResult.java b/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResult.java index 9bbf8c1e..dd4bd417 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResult.java +++ b/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; } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResults.java b/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResults.java index 6d59f362..6094e861 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResults.java +++ b/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); } \ No newline at end of file diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResultsCriteria.java b/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResultsCriteria.java index fc46edd2..9b66b341 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/MappingResultsCriteria.java +++ b/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); } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/Result.java b/spring-binding/src/main/java/org/springframework/binding/mapping/Result.java index fcf08e00..8a28eec2 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/Result.java +++ b/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(); } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapper.java b/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapper.java index 5e249825..69984f53 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapper.java +++ b/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; } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapping.java b/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapping.java index 313f9519..b9d3a533 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMapping.java +++ b/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; } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingContext.java b/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingContext.java index b6a5e19b..4510d5ef 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingContext.java +++ b/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; } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingResults.java b/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingResults.java index bae9be94..b2b6a0a3 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/impl/DefaultMappingResults.java +++ b/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; diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/results/RequiredError.java b/spring-binding/src/main/java/org/springframework/binding/mapping/results/RequiredError.java index cf4e03ba..ba00d5db 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/results/RequiredError.java +++ b/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; } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/results/SourceAccessError.java b/spring-binding/src/main/java/org/springframework/binding/mapping/results/SourceAccessError.java index ac7c3f35..5c64b353 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/results/SourceAccessError.java +++ b/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"; + } } } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/results/Success.java b/spring-binding/src/main/java/org/springframework/binding/mapping/results/Success.java index 4a7e004f..69eec890 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/results/Success.java +++ b/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; diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/results/TargetAccessError.java b/spring-binding/src/main/java/org/springframework/binding/mapping/results/TargetAccessError.java index d4602c9b..effdd9bc 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/results/TargetAccessError.java +++ b/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; } diff --git a/spring-binding/src/main/java/org/springframework/binding/mapping/results/TypeConversionError.java b/spring-binding/src/main/java/org/springframework/binding/mapping/results/TypeConversionError.java index 8ccbde51..e113a803 100644 --- a/spring-binding/src/main/java/org/springframework/binding/mapping/results/TypeConversionError.java +++ b/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; + } + }