Author: desruisseaux
Date: Sun Mar 3 21:23:47 2013
New Revision: 1452127
URL: http://svn.apache.org/r1452127
Log:
Minor clarifications in javadoc and method names.
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java?rev=1452127&r1=1452126&r2=1452127&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] Sun Mar 3 21:23:47 2013
@@ -113,10 +113,6 @@ public abstract class AbstractMetadata i
* for better performances, or for comparing "hidden" attributes not
specified
* by the GeoAPI (or other standard) interface.
*
- * <p>This method performs a <cite>deep</cite> comparison: if this
metadata contains
- * other metadata, then the comparison will invoke the {@link
Object#equals(Object)}
- * method on those children as well.</p>
- *
* @param object The object to compare with this metadata.
* @param mode The strictness level of the comparison.
* @return {@code true} if the given object is equal to this metadata.
@@ -151,7 +147,7 @@ public abstract class AbstractMetadata i
* Edit: actually, even if we could synchronize the two objects
atomically, a deadlock
* risk would still exists for the reason documented in this
class's javadoc.
*/
- return standard.shallowEquals(this, object, mode, false);
+ return standard.equals(this, object, mode);
}
/**
@@ -177,8 +173,8 @@ public abstract class AbstractMetadata i
/**
* Computes a hash code value for this metadata using Java reflection. The
hash code
- * is defined as the sum of hash code values of all non-null properties.
This is the
- * same contract than {@link java.util.Set#hashCode()} and ensure that the
hash code
+ * is defined as the sum of hash code values of all non-empty properties.
This is a
+ * similar contract than {@link java.util.Set#hashCode()} and ensures that
the hash code
* value is insensitive to the ordering of properties.
*
* {@section Performance note}
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java?rev=1452127&r1=1452126&r2=1452127&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] Sun Mar 3 21:23:47 2013
@@ -93,7 +93,7 @@ public class MetadataStandard {
private static final MetadataStandard[] INSTANCES;
/**
- * An instance working on ISO 19123 standard as defined by GeoAPI
interfaces
+ * An instance working on ISO 19111 standard as defined by GeoAPI
interfaces
* in the {@link org.opengis.referencing} package and sub-packages.
*/
public static final MetadataStandard ISO_19111;
@@ -234,6 +234,8 @@ public class MetadataStandard {
* </ul>
*
* @param implementation The implementation class.
+ * @param mandatory Whether this method shall throw an exception or
return {@code null}
+ * if no accessor is found for the given implementation class.
* @return The accessor for the given implementation, or {@code null} if
the given class does
* not implement a metadata interface of the expected package and
{@code mandatory}
* is {@code false}.
@@ -448,30 +450,25 @@ public class MetadataStandard {
* this {@code MetadataStandard}, otherwise an exception will be thrown.
However the two
* arguments do not need to be the same implementation class.
*
- * <p>This method can optionally excludes null values from the comparison.
In metadata,
- * null value often means "don't know", so in some occasions we want to
consider two
- * metadata as different only if a property value is know for sure to be
different.</p>
- *
* {@section Shallow or deep comparisons}
* This method implements a <cite>shallow</cite> comparison in that
properties are compared by
* invoking their {@code properties.equals(…)} method without
<em>explicit</em> recursive call
- * to this {@code shallowEquals(…)} method for children metadata. However
the comparison will
+ * to this {@code standard.equals(…)} method for children metadata.
However the comparison will
* do <em>implicit</em> recursive calls if the {@code
properties.equals(…)} implementations
- * invoke this {@code shallowEquals(…)} method. In the later case, the
final result is a deep
- * comparison.
+ * delegate their work to this {@code standard.equals(…)} method, as
{@link AbstractMetadata} does.
+ * In the later case, the final result is a deep comparison.
*
* @param metadata1 The first metadata object to compare.
* @param metadata2 The second metadata object to compare.
* @param mode The strictness level of the comparison.
- * @param skipNulls If {@code true}, only non-null values will be compared.
* @return {@code true} if the given metadata objects are equals.
* @throws ClassCastException if at least one metadata object don't
* implements a metadata interface of the expected package.
*
* @see AbstractMetadata#equals(Object, ComparisonMode)
*/
- public boolean shallowEquals(final Object metadata1, final Object
metadata2,
- final ComparisonMode mode, final boolean skipNulls) throws
ClassCastException
+ public boolean equals(final Object metadata1, final Object metadata2,
+ final ComparisonMode mode) throws ClassCastException
{
if (metadata1 == metadata2) {
return true;
@@ -483,14 +480,14 @@ public class MetadataStandard {
if (accessor.type != findInterface(metadata2.getClass())) {
return false;
}
- return accessor.shallowEquals(metadata1, metadata2, mode, skipNulls);
+ return accessor.equals(metadata1, metadata2, mode, false);
}
/**
* Computes a hash code for the specified metadata. The hash code is
defined as the
- * sum of hash code values of all non-null properties. This is the same
contract than
- * {@link java.util.Set#hashCode} and ensure that the hash code value is
insensitive
- * to the ordering of properties.
+ * sum of hash code values of all non-empty properties. This is a similar
contract
+ * than {@link java.util.Set#hashCode()} and ensures that the hash code
value is
+ * insensitive to the ordering of properties.
*
* @param metadata The metadata object to compute hash code.
* @return A hash code value for the specified metadata.
Modified:
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java?rev=1452127&r1=1452126&r2=1452127&view=diff
==============================================================================
---
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
[UTF-8] (original)
+++
sis/branches/JDK7/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
[UTF-8] Sun Mar 3 21:23:47 2013
@@ -62,7 +62,7 @@ import static org.apache.sis.internal.ut
* <ul>
* <li>The standard properties defined by the GeoAPI (or other standard)
interfaces.
* Those properties are the only one accessible by most methods in this
class,
- * except {@link #shallowEquals(Object, Object, ComparisonMode,
boolean)},
+ * except {@link #equals(Object, Object, ComparisonMode, boolean)},
* {@link #shallowCopy(Object, Object, boolean)} and {@link
#freeze(Object)}.</li>
*
* <li>Extra properties defined by the {@link IdentifiedObject} interface.
Those properties
@@ -508,10 +508,13 @@ final class PropertyAccessor {
* Returns the index of the specified property, or -1 if none.
* The search is case-insensitive.
*
- * @param key The property to search.
- * @return The index of the given key, or -1 if none.
+ * @param name The name of the property to search.
+ * @param mandatory Whether this method shall throw an exception or
return {@code -1}
+ * if the given name is not found.
+ * @return The index of the given name, or -1 if none and {@code
mandatory} is {@code false}.
+ * @throws IllegalArgumentException if the name is not found and {@code
mandatory} is {@code true}.
*/
- final int indexOf(final String name) {
+ final int indexOf(final String name, final boolean mandatory) {
Integer index = mapping.get(name);
if (index == null) {
/*
@@ -521,29 +524,16 @@ final class PropertyAccessor {
*/
final String key = CharSequences.trimWhitespaces(name.replace(" ",
"").toLowerCase(Locale.ROOT));
if (key == name || (index = mapping.get(key)) == null) { //
Identity comparison is okay here.
- return -1;
+ if (!mandatory) {
+ return -1;
+ }
+ throw new
IllegalArgumentException(Errors.format(Errors.Keys.NoSuchProperty_2, name,
type));
}
}
return index;
}
/**
- * Always returns the index of the specified property (never -1).
- * The search is case-insensitive.
- *
- * @param key The property to search.
- * @return The index of the given key.
- * @throws IllegalArgumentException if the given key is not found.
- */
- final int requiredIndexOf(final String key) throws
IllegalArgumentException {
- final int index = indexOf(key);
- if (index >= 0) {
- return index;
- }
- throw new
IllegalArgumentException(Errors.format(Errors.Keys.NoSuchProperty_2, key,
type));
- }
-
- /**
* Returns the declaring class of the getter at the given index.
*
* @param index The index of the property for which to get the declaring
class.
@@ -958,12 +948,13 @@ final class PropertyAccessor {
}
/**
- * Compares the two specified metadata objects. The comparison is
<cite>shallow</cite>,
- * i.e. all metadata properties are compared using their {@code
properties.equals(…)}
- * method without explicit calls to this {@code shallowEquals} method for
children.
+ * Compares the two specified metadata objects. This method implements a
<cite>shallow</cite>
+ * comparison, i.e. all metadata properties are compared using their
{@code properties.equals(…)}
+ * method without explicit calls to this {@code accessor.equals(…)} method
for children.
+ * However the final result may still be a deep comparison.
*
* <p>This method can optionally excludes null values from the comparison.
In metadata,
- * null value often means "don't know", so in some occasion we want to
consider two
+ * null value often means "don't know", so in some occasions we want to
consider two
* metadata as different only if a property value is know for sure to be
different.</p>
*
* @param metadata1 The first metadata object to compare. This object
determines the accessor.
@@ -972,9 +963,12 @@ final class PropertyAccessor {
* @param skipNulls If {@code true}, only non-null values will be
compared.
* @throws BackingStoreException If the implementation threw a checked
exception.
*
- * @see MetadataStandard#shallowEquals(Object, Object, ComparisonMode,
boolean)
+ * @see MetadataStandard#equals(Object, Object, ComparisonMode, boolean)
+ *
+ * @todo The semantic of the <code>skipNulls</code> argument should be
revisited
+ * in order to provide a behavior more like a
<code>contains(Object)</code> method.
*/
- public boolean shallowEquals(final Object metadata1, final Object
metadata2,
+ public boolean equals(final Object metadata1, final Object metadata2,
final ComparisonMode mode, final boolean skipNulls) throws
BackingStoreException
{
assert type.isInstance(metadata1) : metadata1;
@@ -985,13 +979,13 @@ final class PropertyAccessor {
final Method method = getters[i];
final Object value1 = get(method, metadata1);
final Object value2 = get(method, metadata2);
- final boolean empty1 = isEmpty(value1);
- final boolean empty2 = isEmpty(value2);
+ final boolean empty1 = isNullOrEmpty(value1);
+ final boolean empty2 = isNullOrEmpty(value2);
if (empty1 && empty2) {
continue;
}
if (!Utilities.deepEquals(value1, value2, mode)) {
- if (mode.ordinal() < ComparisonMode.APPROXIMATIVE.ordinal() &&
floatEpsilonEqual(value1, value2)) {
+ if (mode.ordinal() >= ComparisonMode.APPROXIMATIVE.ordinal()
&& floatEpsilonEqual(value1, value2)) {
continue; // Accept this slight difference.
}
if (!skipNulls || (!empty1 && !empty2)) {
@@ -1003,9 +997,12 @@ final class PropertyAccessor {
}
/**
- * Copies all metadata from source to target. The source can be any
implementation of
- * the metadata interface, but the target must be the implementation
expected by this
- * class.
+ * Copies all non-empty metadata from source to target. The source can be
any implementation
+ * of the metadata interface, but the target must be the implementation
expected by this class.
+ *
+ * <p>If {@code skipNulls} is {@code true} and the source contains any
null or empty properties,
+ * then those properties will <strong>not</strong> overwrite the
corresponding properties in the
+ * destination metadata.</p>
*
* @param source The metadata to copy.
* @param target The target metadata.
@@ -1027,7 +1024,7 @@ final class PropertyAccessor {
for (int i=0; i<standardCount; i++) {
final Method getter = getters[i];
arguments[0] = get(getter, source);
- if (!skipNulls || !isEmpty(arguments[0])) {
+ if (!skipNulls || !isNullOrEmpty(arguments[0])) {
if (setters == null) {
return false;
}
@@ -1079,10 +1076,10 @@ final class PropertyAccessor {
}
/**
- * Returns a hash code for the specified metadata. The hash code is
defined as the
- * sum of hash code values of all non-null properties. This is the same
contract than
- * {@link java.util.Set#hashCode} and ensure that the hash code value is
insensitive
- * to the ordering of properties.
+ * Computes a hash code for the specified metadata. The hash code is
defined as the
+ * sum of hash code values of all non-empty properties. This is a similar
contract
+ * than {@link java.util.Set#hashCode()} and ensures that the hash code
value is
+ * insensitive to the ordering of properties.
*
* @throws BackingStoreException If the implementation threw a checked
exception.
*/
@@ -1091,7 +1088,7 @@ final class PropertyAccessor {
int code = 0;
for (int i=0; i<standardCount; i++) {
final Object value = get(getters[i], metadata);
- if (!isEmpty(value)) {
+ if (!isNullOrEmpty(value)) {
code += value.hashCode();
}
}
@@ -1099,7 +1096,7 @@ final class PropertyAccessor {
}
/**
- * Counts the number of non-null properties.
+ * Counts the number of non-empty properties.
*
* @throws BackingStoreException If the implementation threw a checked
exception.
*/
@@ -1107,7 +1104,7 @@ final class PropertyAccessor {
assert type.isInstance(metadata) : metadata;
int count = 0;
for (int i=0; i<standardCount; i++) {
- if (!isEmpty(get(getters[i], metadata))) {
+ if (!isNullOrEmpty(get(getters[i], metadata))) {
if (++count >= max) {
break;
}
@@ -1123,7 +1120,7 @@ final class PropertyAccessor {
* is invoked from methods doing shallow copy or comparison. If we were
inspecting elements,
* we would need to add a check against infinite recursivity.</p>
*/
- static boolean isEmpty(final Object value) {
+ static boolean isNullOrEmpty(final Object value) {
return value == null
|| ((value instanceof CharSequence) &&
CharSequences.trimWhitespaces((CharSequence) value).length() == 0)
|| ((value instanceof Collection<?>) && ((Collection<?>)
value).isEmpty())
