You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2017/01/15 10:36:24 UTC
svn commit: r1778901 [3/4] - in /sis/trunk: ./
application/sis-console/src/main/java/org/apache/sis/console/
core/sis-metadata/src/main/java/org/apache/sis/internal/metadata/
core/sis-metadata/src/main/java/org/apache/sis/metadata/
core/sis-metadata/sr...
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/SpecializedIdentifier.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/SpecializedIdentifier.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/SpecializedIdentifier.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/SpecializedIdentifier.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -19,6 +19,7 @@ package org.apache.sis.internal.jaxb;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.UUID;
+import java.util.Objects;
import java.io.Serializable;
import java.util.logging.Level;
import org.opengis.metadata.Identifier;
@@ -31,16 +32,13 @@ import org.apache.sis.util.Debug;
import org.apache.sis.util.resources.Messages;
import org.apache.sis.internal.util.Citations;
-// Branch-dependent imports
-import java.util.Objects;
-
/**
* Wraps a {@link XLink}, {@link URI} or {@link UUID} as an identifier in the {@link IdentifierMap}.
* The {@linkplain #authority} is typically an instance of {@link NonMarshalledAuthority}. The value
* is an object of a type constrained by the authority.
*
- * @param <T> The value type, typically {@link XLink}, {@link UUID} or {@link String}.
+ * @param <T> the value type, typically {@link XLink}, {@link UUID} or {@link String}.
*
* @author Martin Desruisseaux (Geomatys)
* @since 0.3
@@ -77,8 +75,8 @@ public final class SpecializedIdentifier
/**
* Creates a new adapter for the given authority and identifier value.
*
- * @param authority The identifier authority.
- * @param value The identifier value, or {@code null} if not yet defined.
+ * @param authority the identifier authority.
+ * @param value the identifier value, or {@code null} if not yet defined.
*/
public SpecializedIdentifier(final IdentifierSpace<T> authority, final T value) {
this.authority = authority;
@@ -91,8 +89,8 @@ public final class SpecializedIdentifier
* authorities declared in the {@link IdentifierSpace} interface. Otherwise a
* plain {@link IdentifierMapEntry} is created.
*
- * @param authority The authority, typically as one of the {@link IdentifierSpace} constants.
- * @param code The identifier code to parse.
+ * @param authority the authority, typically as one of the {@link IdentifierSpace} constants.
+ * @param code the identifier code to parse.
*
* @see IdentifierMapAdapter#put(Citation, String)
*/
@@ -144,10 +142,10 @@ public final class SpecializedIdentifier
* <p>This method assumes that {@link IdentifierMap#put(Object, Object)} is
* the public API by which this method has been invoked.</p>
*
- * @param context The marshalling context, or {@code null} if none.
- * @param value The value that we failed to parse.
- * @param type The target type of the parsing process.
- * @param cause The exception that occurred during the parsing process.
+ * @param context the marshalling context, or {@code null} if none.
+ * @param value the value that we failed to parse.
+ * @param type the target type of the parsing process.
+ * @param cause the exception that occurred during the parsing process.
*/
static void parseFailure(final Context context, final String value, final Class<?> type, final Exception cause) {
Context.warningOccured(context, Level.WARNING, IdentifierMap.class, "put", cause,
@@ -157,7 +155,7 @@ public final class SpecializedIdentifier
/**
* Returns the authority specified at construction time.
*
- * @return The identifier authority.
+ * @return the identifier authority.
*/
@Override
public Citation getAuthority() {
@@ -168,7 +166,7 @@ public final class SpecializedIdentifier
* Returns the identifier value. This is the {@linkplain #getCode() code} expressed as
* an object more specialized than {@link String}.
*
- * @return The identifier value, or {@code null} if none.
+ * @return the identifier value, or {@code null} if none.
*/
public T getValue() {
return value;
@@ -178,7 +176,7 @@ public final class SpecializedIdentifier
* Returns a string representation of the {@linkplain #getValue() identifier value},
* or {@code null} if none.
*
- * @return The identifier value.
+ * @return the identifier value.
*/
@Override
public String getCode() {
@@ -197,7 +195,7 @@ public final class SpecializedIdentifier
/**
* Compares this identifier with the given object for equality.
*
- * @param other The object to compare with this identifier for equality.
+ * @param other the object to compare with this identifier for equality.
*/
@Override
public boolean equals(final Object other) {
@@ -212,7 +210,7 @@ public final class SpecializedIdentifier
/**
* Returns a clone of this identifier.
*
- * @return A shallow clone of this identifier.
+ * @return a shallow clone of this identifier.
*/
@Override
public Object clone() {
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/ObjectReference.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/ObjectReference.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/ObjectReference.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/ObjectReference.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -87,11 +87,11 @@ final class ObjectReference {
*
* <p>This method is invoked at unmarshalling time by {@link PropertyType#resolve(Context)}.</p>
*
- * @param <T> The compile-time type of the {@code type} argument.
- * @param context The marshalling context, or {@code null} if none.
- * @param type The expected type of the metadata object.
- * @param metadata The metadata object, or {@code null}.
- * @return A metadata object for the identifiers, or {@code null}
+ * @param <T> the compile-time type of the {@code type} argument.
+ * @param context the marshalling context, or {@code null} if none.
+ * @param type the expected type of the metadata object.
+ * @param metadata the metadata object, or {@code null}.
+ * @return a metadata object for the identifiers, or {@code null}
*/
final <T> T resolve(final Context context, final Class<T> type, T metadata) {
if (metadata == null) {
@@ -99,8 +99,10 @@ final class ObjectReference {
if ((uuid == null || (metadata = resolver.resolve(context, type, uuid )) == null) &&
(xlink == null || (metadata = resolver.resolve(context, type, xlink)) == null))
{
- // Failed to find an existing metadata instance.
- // Creates an empty instance with the identifiers.
+ /*
+ * Failed to find an existing metadata instance.
+ * Creates an empty instance with the identifiers.
+ */
int count = 0;
SpecializedIdentifier<?>[] identifiers = new SpecializedIdentifier<?>[2];
if (uuid != null) identifiers[count++] = new SpecializedIdentifier<>(IdentifierSpace.UUID, uuid);
@@ -109,8 +111,10 @@ final class ObjectReference {
metadata = resolver.newIdentifiedObject(context, type, identifiers);
}
} else {
- // In principle, the XML should contain a full metadata object OR a uuidref attribute.
- // However if both are present, assign the identifiers to that instance.
+ /*
+ * In principle, the XML should contain a full metadata object OR a uuidref attribute.
+ * However if both are present, assign the identifiers to that instance.
+ */
if (metadata instanceof IdentifiedObject) {
final IdentifierMap map = ((IdentifiedObject) metadata).getIdentifierMap();
putInto(context, map, IdentifierSpace.UUID, uuid);
@@ -138,9 +142,9 @@ final class ObjectReference {
* the previous value if they are not equal. The previous value is the "{@code uuid}" attribute, which is
* assumed more closely tied to the actual metadata than the {@code uuidref} attribute.
*
- * @param map The map in which to write the identifier.
- * @param authority The identifier authority.
- * @param value The identifier value, or {@code null} if not yet defined.
+ * @param map the map in which to write the identifier.
+ * @param authority the identifier authority.
+ * @param value the identifier value, or {@code null} if not yet defined.
*/
private static <T> void putInto(final Context context, final IdentifierMap map,
final IdentifierSpace<T> authority, final T value)
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/PropertyType.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/PropertyType.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/PropertyType.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gco/PropertyType.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -153,8 +153,8 @@ public abstract class PropertyType<Value
* Builds a {@code PropertyType} wrapper for the given primitive type wrapper.
* This constructor checks for nil reasons only if {@code check} is {@code true}.
*
- * @param value The primitive type wrapper.
- * @param mayBeNil {@code true} if we should check for nil reasons.
+ * @param value the primitive type wrapper.
+ * @param mayBeNil {@code true} if we should check for nil reasons.
*/
PropertyType(final BoundType value, final boolean mayBeNil) {
metadata = value;
@@ -172,7 +172,7 @@ public abstract class PropertyType<Value
* implements the {@link NilObject} or {@link IdentifiedObject} interface. If the object implements
* both of them (should not happen, but we never know), then the identifiers will have precedence.
*
- * @param value The interface to wrap.
+ * @param value the interface to wrap.
*/
protected PropertyType(final BoundType value) {
/*
@@ -291,7 +291,7 @@ public abstract class PropertyType<Value
XLink xlink = ref.xlink;
if (create && xlink == null) {
ref.xlink = xlink = new XLink();
- xlink.setType(XLink.Type.SIMPLE); // The "simple" type is fixed in the "gco" schema.
+ xlink.setType(XLink.Type.SIMPLE); // The "simple" type is fixed in the "gco" schema.
}
return xlink;
}
@@ -313,7 +313,7 @@ public abstract class PropertyType<Value
* non-null {@linkplaih #reference} exists, since in such case the object can
* not be nil.
*
- * @param nilReason The new attribute value.
+ * @param nilReason the new attribute value.
* @category gco:PropertyType
*/
public final void setNilReason(final String nilReason) {
@@ -330,7 +330,7 @@ public abstract class PropertyType<Value
* @return the current value, or {@code null} if none.
* @category gco:ObjectReference
*/
- @XmlAttribute(name = "uuidref") // Defined in "gco" as unqualified attribute.
+ @XmlAttribute(name = "uuidref") // Defined in "gco" as unqualified attribute.
public final String getUUIDREF() {
final ObjectReference ref = reference(false);
return (ref != null) ? toString(ref.uuid) : null;
@@ -339,8 +339,8 @@ public abstract class PropertyType<Value
/**
* Sets the {@code uuidref} attribute value.
*
- * @param uuid The new attribute value.
- * @throws IllegalArgumentException If the given UUID can not be parsed.
+ * @param uuid the new attribute value.
+ * @throws IllegalArgumentException if the given UUID can not be parsed.
* @category gco:ObjectReference
*/
public final void setUUIDREF(final String uuid) throws IllegalArgumentException {
@@ -381,8 +381,8 @@ public abstract class PropertyType<Value
/**
* Sets the {@code href} attribute value.
*
- * @param href The new attribute value.
- * @throws URISyntaxException If th given string can not be parsed as a URI.
+ * @param href the new attribute value.
+ * @throws URISyntaxException if the given string can not be parsed as a URI.
* @category xlink
*/
public final void setHRef(final String href) throws URISyntaxException {
@@ -405,8 +405,8 @@ public abstract class PropertyType<Value
/**
* Sets the {@code role} attribute value.
*
- * @param role The new attribute value.
- * @throws URISyntaxException If th given string can not be parsed as a URI.
+ * @param role the new attribute value.
+ * @throws URISyntaxException if the given string can not be parsed as a URI.
* @category xlink
*/
public final void setRole(final String role) throws URISyntaxException {
@@ -429,8 +429,8 @@ public abstract class PropertyType<Value
/**
* Sets the {@code arcrole} attribute value.
*
- * @param arcrole The new attribute value.
- * @throws URISyntaxException If th given string can not be parsed as a URI.
+ * @param arcrole the new attribute value.
+ * @throws URISyntaxException if the given string can not be parsed as a URI.
* @category xlink
*/
public final void setArcRole(final String arcrole) throws URISyntaxException {
@@ -453,7 +453,7 @@ public abstract class PropertyType<Value
/**
* Sets the {@code title} attribute value.
*
- * @param title The new attribute value.
+ * @param title the new attribute value.
* @category xlink
*/
public final void setTitle(String title) {
@@ -486,7 +486,7 @@ public abstract class PropertyType<Value
/**
* Sets the {@code show} attribute value.
*
- * @param show The new attribute value.
+ * @param show the new attribute value.
* @category xlink
*/
public final void setShow(final XLink.Show show) {
@@ -516,7 +516,7 @@ public abstract class PropertyType<Value
/**
* Sets the {@code actuate} attribute value.
*
- * @param actuate The new attribute value.
+ * @param actuate the new attribute value.
* @category xlink
*/
public final void setActuate(final XLink.Actuate actuate) {
@@ -536,7 +536,7 @@ public abstract class PropertyType<Value
* a value from the object fields, because this method is invoked from
* the constructor.
*
- * @return The bound type, which is typically the GeoAPI interface.
+ * @return the bound type, which is typically the GeoAPI interface.
*/
protected abstract Class<BoundType> getBoundType();
@@ -545,8 +545,8 @@ public abstract class PropertyType<Value
* This method is invoked by {@link #marshal} after making sure that
* {@code value} is not null.
*
- * @param value The GeoAPI interface to wrap.
- * @return The adapter.
+ * @param value the GeoAPI interface to wrap.
+ * @return the adapter.
*/
protected abstract ValueType wrap(final BoundType value);
@@ -555,8 +555,8 @@ public abstract class PropertyType<Value
* marshalled into an XML file or stream. JAXB calls automatically this method at
* marshalling time.
*
- * @param value The bound type value, here the interface.
- * @return The adapter for the given value.
+ * @param value the bound type value, here the interface.
+ * @return the adapter for the given value.
*/
@Override
public final ValueType marshal(final BoundType value) {
@@ -570,9 +570,9 @@ public abstract class PropertyType<Value
* Converts an adapter read from an XML stream to the GeoAPI interface which will
* contains this value. JAXB calls automatically this method at unmarshalling time.
*
- * @param value The adapter for a metadata value.
- * @return An instance of the GeoAPI interface which represents the metadata value.
- * @throws URISyntaxException If a URI can not be parsed.
+ * @param value the adapter for a metadata value.
+ * @return an instance of the GeoAPI interface which represents the metadata value.
+ * @throws URISyntaxException if a URI can not be parsed.
*/
@Override
public final BoundType unmarshal(final ValueType value) throws URISyntaxException {
@@ -583,7 +583,7 @@ public abstract class PropertyType<Value
* If the {@linkplain #metadata} is still null, tries to resolve it using UUID, XLink
* or NilReason information. This method is invoked at unmarshalling time.
*
- * @throws URISyntaxException If a nil reason is present and can not be parsed.
+ * @throws URISyntaxException if a nil reason is present and can not be parsed.
*/
final BoundType resolve(final Context context) throws URISyntaxException {
final ObjectReference ref = reference(false);
@@ -608,8 +608,8 @@ public abstract class PropertyType<Value
* This method is not invoked if the missing component is flagged as mandatory by GML,
* but is not mandatory for SIS working.
*
- * @param missing The name of the missing XML component.
- * @throws IllegalArgumentException Always thrown.
+ * @param missing the name of the missing XML component.
+ * @throws IllegalArgumentException always thrown.
*
* @since 0.7
*/
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/GMLAdapter.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/GMLAdapter.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/GMLAdapter.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/jaxb/gml/GMLAdapter.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -82,12 +82,12 @@ public abstract class GMLAdapter {
* <p>This constructor is typically invoked at marshalling time. The {@link #id}
* value set by this constructor will be used by JAXB for producing the XML.</p>
*
- * @param wrapped An instance of a GeoAPI interface to be wrapped.
+ * @param wrapped an instance of a GeoAPI interface to be wrapped.
*/
protected GMLAdapter(final Object wrapped) {
if (wrapped instanceof IdentifiedObject) {
final IdentifierMap map = ((IdentifiedObject) wrapped).getIdentifierMap();
- if (map != null) { // Should not be null, but let be safe.
+ if (map != null) { // Should not be null, but let be safe.
id = map.get(IdentifierSpace.ID);
}
}
@@ -98,12 +98,12 @@ public abstract class GMLAdapter {
* is typically invoked at unmarshalling time in order to assign the ID of this
* temporary wrapper to the "real" GeoAPI implementation instance.
*
- * @param wrapped The GeoAPI implementation for which to assign the ID.
+ * @param wrapped the GeoAPI implementation for which to assign the ID.
*/
public final void copyIdTo(final Object wrapped) {
if (id != null && wrapped instanceof IdentifiedObject) {
final IdentifierMap map = ((IdentifiedObject) wrapped).getIdentifierMap();
- if (map != null) { // Should not be null, but let be safe.
+ if (map != null) { // Should not be null, but let be safe.
map.put(IdentifierSpace.ID, id);
}
}
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/simple/CitationConstant.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/simple/CitationConstant.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/simple/CitationConstant.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/simple/CitationConstant.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -135,8 +135,10 @@ public class CitationConstant extends Si
if (c == null) {
c = MetadataServices.getInstance().createCitation(title);
if (c == null) {
- // 'sis-metadata' module not on the classpath (should be very rare)
- // or no citation defined for the given primary key.
+ /*
+ * 'sis-metadata' module not on the classpath (should be very rare)
+ * or no citation defined for the given primary key.
+ */
c = new SimpleCitation(title);
}
delegate = c;
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/internal/util/Citations.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -19,6 +19,7 @@ package org.apache.sis.internal.util;
import java.util.Collection;
import java.util.Iterator;
import java.util.Locale;
+import java.util.Objects;
import org.opengis.metadata.Identifier;
import org.opengis.metadata.citation.Citation;
import org.opengis.util.InternationalString;
@@ -30,11 +31,8 @@ import org.apache.sis.util.Static;
import static org.apache.sis.util.iso.DefaultNameSpace.DEFAULT_SEPARATOR;
-// Branch-dependent imports
-import java.util.Objects;
import org.opengis.referencing.ReferenceIdentifier;
-
/**
* Utility methods working on {@link Citation} objects. The public facade of those methods is
* defined in the {@link org.apache.sis.metadata.iso.citation.Citations} class, but the actual
@@ -59,8 +57,8 @@ public final class Citations extends Sta
* <p>This method can be used for identifying where in Apache SIS source code the relationship between
* EPSG authority and IOGP code space is hard-coded.</p>
*
- * @param codeSpace The identifier code space, or {@code null}.
- * @param code The identifier code, or {@code null}.
+ * @param codeSpace the identifier code space, or {@code null}.
+ * @param code the identifier code, or {@code null}.
* @return {@code true} if the given identifier is {@code "IOGP:EPSG"}.
*
* @see org.apache.sis.metadata.iso.citation.Citations#EPSG
@@ -76,9 +74,9 @@ public final class Citations extends Sta
* Returns the collection iterator, or {@code null} if the given collection is null
* or empty. We use this method as a paranoiac safety against broken implementations.
*
- * @param <E> The type of elements in the collection.
- * @param collection The collection from which to get the iterator, or {@code null}.
- * @return The iterator over the given collection elements, or {@code null}.
+ * @param <E> the type of elements in the collection.
+ * @param collection the collection from which to get the iterator, or {@code null}.
+ * @return the iterator over the given collection elements, or {@code null}.
*/
public static <E> Iterator<E> iterator(final Collection<E> collection) {
return (collection != null && !collection.isEmpty()) ? collection.iterator() : null;
@@ -105,8 +103,8 @@ public final class Citations extends Sta
* The method to be used consistently for comparing titles or identifiers in all {@code fooMathes(\u2026)}
* methods declared in this class.
*
- * @param s1 The first characters sequence to compare, or {@code null}.
- * @param s2 The second characters sequence to compare, or {@code null}.
+ * @param s1 the first characters sequence to compare, or {@code null}.
+ * @param s2 the second characters sequence to compare, or {@code null}.
* @return {@code true} if both arguments are {@code null} or if the two given texts are equal,
* ignoring case and any characters other than digits and letters.
*
@@ -122,14 +120,14 @@ public final class Citations extends Sta
* See {@link org.apache.sis.metadata.iso.citation.Citations#titleMatches(Citation, Citation)}
* for the public documentation of this method.
*
- * @param c1 The first citation to compare, or {@code null}.
- * @param c2 the second citation to compare, or {@code null}.
+ * @param c1 the first citation to compare, or {@code null}.
+ * @param c2 the second citation to compare, or {@code null}.
* @return {@code true} if both arguments are non-null, and at least one title or alternate title matches.
*/
public static boolean titleMatches(final Citation c1, final Citation c2) {
if (c1 != null && c2 != null) {
if (c1 == c2) {
- return true; // Optimisation for a common case.
+ return true; // Optimisation for a common case.
}
InternationalString candidate = c2.getTitle();
Iterator<? extends InternationalString> iterator = null;
@@ -163,8 +161,8 @@ public final class Citations extends Sta
* See {@link org.apache.sis.metadata.iso.citation.Citations#titleMatches(Citation, String)}
* for the public documentation of this method.
*
- * @param citation The citation to check for, or {@code null}.
- * @param title The title or alternate title to compare, or {@code null}.
+ * @param citation the citation to check for, or {@code null}.
+ * @param title the title or alternate title to compare, or {@code null}.
* @return {@code true} if both arguments are non-null, and the title or an alternate
* title matches the given string.
*/
@@ -203,8 +201,8 @@ public final class Citations extends Sta
* See {@link org.apache.sis.metadata.iso.citation.Citations#identifierMatches(Citation, Citation)}
* for the public documentation of this method.
*
- * @param c1 The first citation to compare, or {@code null}.
- * @param c2 the second citation to compare, or {@code null}.
+ * @param c1 the first citation to compare, or {@code null}.
+ * @param c2 the second citation to compare, or {@code null}.
* @return {@code true} if both arguments are non-null, and at least one identifier matches.
*/
public static boolean identifierMatches(Citation c1, Citation c2) {
@@ -243,9 +241,9 @@ public final class Citations extends Sta
* See {@link org.apache.sis.metadata.iso.citation.Citations#identifierMatches(Citation, String)}
* for the public documentation of this method.
*
- * @param citation The citation to check for, or {@code null}.
- * @param identifier The identifier to compare, or {@code null} if unknown.
- * @param code Value of {@code identifier.getCode()}, or {@code null}.
+ * @param citation the citation to check for, or {@code null}.
+ * @param identifier the identifier to compare, or {@code null} if unknown.
+ * @param code value of {@code identifier.getCode()}, or {@code null}.
* @return {@code true} if both arguments are non-null, and an identifier matches the given string.
*/
public static boolean identifierMatches(final Citation citation, final Identifier identifier, final CharSequence code) {
@@ -278,9 +276,9 @@ public final class Citations extends Sta
* If one of the authority is null, then the comparison fallback on the given {@code codeSpace}.
* If the code spaces are also null, then this method conservatively returns {@code false}.
*
- * @param identifier The identifier to compare.
- * @param authority The desired authority, or {@code null}.
- * @param codeSpace The desired code space or {@code null}, used as a fallback if an authority is null.
+ * @param identifier the identifier to compare.
+ * @param authority the desired authority, or {@code null}.
+ * @param codeSpace the desired code space or {@code null}, used as a fallback if an authority is null.
* @return {@code true} if the authority or code space (as a fallback only) matches.
*/
private static boolean authorityMatches(final Identifier identifier, final Citation authority, final String codeSpace) {
@@ -309,8 +307,8 @@ public final class Citations extends Sta
* at least in the case of {@linkplain org.apache.sis.referencing.operation.DefaultOperationMethod operation methods} and
* {@linkplain org.apache.sis.parameter.AbstractParameterDescriptor parameters}.</p>
*
- * @param id1 The first collection of identifiers, or {@code null}.
- * @param id2 The second collection of identifiers, or {@code null}.
+ * @param id1 the first collection of identifiers, or {@code null}.
+ * @param id2 the second collection of identifiers, or {@code null}.
* @return {@code TRUE}�or {@code FALSE} on match or mismatch respectively, or {@code null} if this method
* can not determine if there is a match or mismatch.
*/
@@ -351,9 +349,9 @@ public final class Citations extends Sta
* <li>For assigning a value to a {@code codeSpace} field, use {@link #getUnicodeIdentifier(Citation)}.</li>
* </ul>
*
- * @param citation The citation for which to get the identifier, or {@code null}.
- * @param strict {@code true}�for returning a non-null value only if the identifier is a valid Unicode identifier.
- * @return A non-empty identifier for the given citation without leading or trailing whitespaces,
+ * @param citation the citation for which to get the identifier, or {@code null}.
+ * @param strict {@code true}�for returning a non-null value only if the identifier is a valid Unicode identifier.
+ * @return a non-empty identifier for the given citation without leading or trailing whitespaces,
* or {@code null} if the given citation is null or does not declare any identifier or title.
*
* @see <a href="https://issues.apache.org/jira/browse/SIS-201">SIS-201</a>
@@ -386,8 +384,10 @@ public final class Citations extends Sta
if (!Character.isUnicodeIdentifierPart(c) &&
(strict || (c != '.' && c != '-')))
{
- // Above special case for '.' and '-' characters is documented
- // in the public Citations.getIdentifier(Citation) method.
+ /*
+ * Above special case for '.' and '-' characters is documented
+ * in the public Citations.getIdentifier(Citation) method.
+ */
isUnicode = false;
break;
}
@@ -464,8 +464,8 @@ public final class Citations extends Sta
* use {@code getIdentifier(citation, true)} instead, which will produce the same result but preserving the
* ignorable characters, which can be useful for formatting purpose.
*
- * @param citation The citation for which to get the Unicode identifier, or {@code null}.
- * @return A non-empty Unicode identifier for the given citation without leading or trailing whitespaces,
+ * @param citation the citation for which to get the Unicode identifier, or {@code null}.
+ * @return a non-empty Unicode identifier for the given citation without leading or trailing whitespaces,
* or {@code null} if the given citation is null or does not have any Unicode identifier or title.
*
* @since 0.6
@@ -501,8 +501,10 @@ public final class Citations extends Sta
buffer.appendCodePoint(c);
}
}
- // No need to verify if the buffer is empty, because ignorable
- // characters are not legal Unicode identifier start.
+ /*
+ * No need to verify if the buffer is empty, because ignorable
+ * characters are not legal Unicode identifier start.
+ */
return buffer.toString();
}
i += n;
@@ -524,8 +526,8 @@ public final class Citations extends Sta
* behavior of this method close to the behavior of {@link #getUnicodeIdentifier(Citation)}, which is the
* method having a public facade.</p>
*
- * @param citation The citation for which to infer the code space, or {@code null}.
- * @return A non-empty code space for the given citation without leading or trailing whitespaces,
+ * @param citation the citation for which to infer the code space, or {@code null}.
+ * @return a non-empty code space for the given citation without leading or trailing whitespaces,
* or {@code null} if the given citation is null or does not have any Unicode identifier or title.
*
* @since 0.6
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/TabularFormat.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/TabularFormat.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/TabularFormat.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/io/TabularFormat.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -65,10 +65,11 @@ import org.apache.sis.util.resources.Err
* @version 0.3
* @module
*
- * @param <T> The base type of objects parsed and formatted by this class.
+ * @param <T> the base type of objects parsed and formatted by this class.
*
* @see TableAppender
*/
+@SuppressWarnings("CloneableClassWithoutClone") // Because this class does not contain field that need to be cloned.
public abstract class TabularFormat<T> extends CompoundFormat<T> {
/**
* For cross-version compatibility.
@@ -120,17 +121,18 @@ public abstract class TabularFormat<T> e
private boolean isParsePatternDefined;
/**
- * The pattern used at parsing time for finding the column separators, or {@code null}
- * if not yet constructed. This field is serialized because it may be a user-specified pattern.
+ * The pattern used at parsing time for finding the column separators, or {@code null} if not
+ * yet constructed. This field is serialized because it may be a user-specified pattern.
+ * The same {@code Pattern} instance can be safely shared by many {@code TabularFormat} instances.
*/
private Pattern parsePattern;
/**
* Creates a new tabular format.
*
- * @param locale The locale to use for numbers, dates and angles formatting,
- * or {@code null} for the {@linkplain Locale#ROOT root locale}.
- * @param timezone The timezone, or {@code null} for UTC.
+ * @param locale the locale to use for numbers, dates and angles formatting,
+ * or {@code null} for the {@linkplain Locale#ROOT root locale}.
+ * @param timezone the timezone, or {@code null} for UTC.
*/
public TabularFormat(final Locale locale, final TimeZone timezone) {
super(locale, timezone);
@@ -143,7 +145,7 @@ public abstract class TabularFormat<T> e
/**
* Returns the current line separator. The default value is system-dependent.
*
- * @return The current line separator.
+ * @return the current line separator.
*/
public String getLineSeparator() {
return lineSeparator;
@@ -152,7 +154,7 @@ public abstract class TabularFormat<T> e
/**
* Sets the line separator. Can not be a null or empty string.
*
- * @param separator The new line separator.
+ * @param separator the new line separator.
*/
public void setLineSeparator(final String separator) {
ArgumentChecks.ensureNonEmpty("separator", separator);
@@ -164,7 +166,7 @@ public abstract class TabularFormat<T> e
* only if more than one column is formatted. See {@link #setColumnSeparatorPattern(String)}
* for a description of the pattern syntax.
*
- * @return The pattern of the current column separator.
+ * @return the pattern of the current column separator.
*/
public String getColumnSeparatorPattern() {
final StringBuilder buffer = new StringBuilder(8);
@@ -223,8 +225,8 @@ public abstract class TabularFormat<T> e
* then insert a space"</cite>.
* </div>
*
- * @param pattern The pattern of the new column separator.
- * @throws IllegalArgumentException If the given pattern is illegal.
+ * @param pattern the pattern of the new column separator.
+ * @throws IllegalArgumentException if the given pattern is illegal.
*/
public void setColumnSeparatorPattern(final String pattern) throws IllegalArgumentException {
ArgumentChecks.ensureNonEmpty("pattern", pattern);
@@ -238,9 +240,9 @@ public abstract class TabularFormat<T> e
scan: for (int i=0; i<length; i++) {
final char c = pattern.charAt(i);
switch (c) {
- case '\uFFFF': { // This "character" is reserved.
+ case '\uFFFF': { // This "character" is reserved.
prefix = null;
- break scan; // This will cause IllegalArgumentException to be thrown.
+ break scan; // This will cause IllegalArgumentException to be thrown.
}
case '\\': {
if (i != separatorIndex) {
@@ -262,7 +264,7 @@ scan: for (int i=0; i<length; i++) {
if (i != separatorIndex) {
if (separatorIndex >= 0) {
prefix = null;
- break scan; // This will cause IllegalArgumentException to be thrown.
+ break scan; // This will cause IllegalArgumentException to be thrown.
}
separatorIndex = i+1;
}
@@ -312,8 +314,8 @@ scan: for (int i=0; i<length; i++) {
* Returns a matcher for the column separators in the given text.
* This method is invoked by subclasses in their {@code parse(\u2026)} implementations.
*
- * @param text The text for which to get a matcher.
- * @return A matcher for the column separators in the given text.
+ * @param text the text for which to get a matcher.
+ * @return a matcher for the column separators in the given text.
*/
protected Matcher getColumnSeparatorMatcher(final CharSequence text) {
if (parsePattern == null) {
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/setup/InstallationResources.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -46,6 +46,12 @@ import java.io.BufferedReader;
* META-INF/services/org.apache.sis.setup.InstallationResources
* }
*
+ * Above registration is usually done automatically when extension modules are added on the classpath.
+ * For example adding the {@code org.apache.sis.non-free:\u200bsis-epsg} Maven dependency as documented on
+ * the <a href="http://sis.apache.org/epsg.html">Apache SIS web site</a> is the only step needed for
+ * allowing Apache SIS to read the EPSG scripts (however SIS still needs an installation directory
+ * for writing the database; see above-cited web page for more information).
+ *
* @author Martin Desruisseaux (Geomatys)
* @since 0.7
* @version 0.7
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/ComparisonMode.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -175,7 +175,7 @@ public enum ComparisonMode {
* This method currently returns {@code true} for {@code IGNORE_METADATA}, {@code APPROXIMATIVE}
* or {@code DEBUG} only, but this list may be extended in future SIS versions.
*
- * @return Whether this comparison ignore metadata.
+ * @return whether this comparison ignore metadata.
*
* @since 0.6
*/
@@ -188,7 +188,7 @@ public enum ComparisonMode {
* This method currently returns {@code true} for {@code APPROXIMATIVE} or {@code DEBUG} only,
* but this list may be extended in future SIS versions.
*
- * @return Whether this comparison uses a tolerance threshold.
+ * @return whether this comparison uses a tolerance threshold.
*
* @since 0.6
*/
@@ -202,9 +202,9 @@ public enum ComparisonMode {
*
* <p><b>Note:</b> this method never return the {@link #DEBUG} mode.</p>
*
- * @param o1 The first object to compare, or {@code null}.
- * @param o2 The second object to compare, or {@code null}.
- * @return The most suitable comparison mode, or {@code null} if the two given objects
+ * @param o1 the first object to compare, or {@code null}.
+ * @param o2 the second object to compare, or {@code null}.
+ * @return the most suitable comparison mode, or {@code null} if the two given objects
* are not equal according any mode in this enumeration.
*/
public static ComparisonMode equalityLevel(final Object o1, Object o2) {
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/LenientComparable.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -137,8 +137,8 @@ public interface LenientComparable {
* {@code APPROXIMATIVE} mode is incompatible with the transitivity contract.</li>
* </ul>
*
- * @param other The object to compare to {@code this}.
- * @param mode The strictness level of the comparison.
+ * @param other the object to compare to {@code this}.
+ * @param mode the strictness level of the comparison.
* @return {@code true} if both objects are equal according the given comparison mode.
*
* @see Utilities#deepEquals(Object, Object, ComparisonMode)
@@ -170,7 +170,7 @@ public interface LenientComparable {
* subclasses override the above {@link #equals(Object, ComparisonMode)} method instead
* than this one.
*
- * @param other The object to compare to {@code this}.
+ * @param other the object to compare to {@code this}.
* @return {@code true} if both objects are strictly equal.
*
* @see ComparisonMode#STRICT
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/DefaultTreeTable.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/DefaultTreeTable.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/DefaultTreeTable.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/DefaultTreeTable.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -22,6 +22,7 @@ import java.util.Map;
import java.util.LinkedHashMap;
import java.util.Collection;
import java.util.Collections;
+import java.util.Objects;
import java.io.Serializable;
import org.apache.sis.util.ArgumentChecks;
import org.apache.sis.util.resources.Errors;
@@ -32,9 +33,6 @@ import static org.apache.sis.util.CharSe
import static org.apache.sis.util.collection.Containers.isNullOrEmpty;
import static org.apache.sis.util.collection.Containers.hashMapCapacity;
-// Branch-dependent imports
-import java.util.Objects;
-
/**
* A {@link TreeTable} implementation with a {@linkplain #getColumns() list of columns} given at
@@ -119,7 +117,7 @@ public class DefaultTreeTable implements
* Creates a new tree table with the given columns. The given array shall not be null or
* empty, and shall not contain null or duplicated elements.
*
- * @param columns The list of table columns.
+ * @param columns the list of table columns.
*/
public DefaultTreeTable(TableColumn<?>... columns) {
ArgumentChecks.ensureNonNull("columns", columns);
@@ -137,7 +135,7 @@ public class DefaultTreeTable implements
* Creates a new tree table initialized to the given root.
* The {@linkplain #getColumns() list of columns} is inferred from the given node.
*
- * @param root The tree table root (can not be null).
+ * @param root the tree table root (can not be null).
*/
public DefaultTreeTable(final Node root) {
ArgumentChecks.ensureNonNull("root", root);
@@ -149,8 +147,8 @@ public class DefaultTreeTable implements
* Creates a map of column indices from the given list of columns.
* This method is invoked for initializing the {@link #columnIndices} field.
*
- * @param columns The list of columns.
- * @return The map of column indices.
+ * @param columns the list of columns.
+ * @return the map of column indices.
*/
static Map<TableColumn<?>,Integer> createColumnIndices(final TableColumn<?>[] columns) {
Map<TableColumn<?>,Integer> map;
@@ -176,7 +174,7 @@ public class DefaultTreeTable implements
* Returns all columns in the given map, sorted by increasing index value.
* This method relies on {@link LinkedHashMap} preserving insertion order.
*
- * @return The columns in an array of elements of type {@code TableColumn},
+ * @return the columns in an array of elements of type {@code TableColumn},
* <strong>not a subtype</strong> for allowing usage in
* {@link UnmodifiableArrayList#wrap(Object[])}.
*/
@@ -192,6 +190,7 @@ public class DefaultTreeTable implements
* @see Node#setValue(TableColumn, Object)
*/
@Override
+ @SuppressWarnings("ReturnOfCollectionOrArrayField") // Safe because returned list is unmodifiable.
public final List<TableColumn<?>> getColumns() {
if (columns == null) {
columns = UnmodifiableArrayList.wrap(getColumns(columnIndices));
@@ -216,8 +215,8 @@ public class DefaultTreeTable implements
* Sets the root to the given node. If a root already existed prior this method call,
* then the previous root node will be discarded.
*
- * @param root The new root node (can not be null).
- * @throws IllegalArgumentException If the table columns in the given node are inconsistent
+ * @param root the new root node (can not be null).
+ * @throws IllegalArgumentException if the table columns in the given node are inconsistent
* with the table columns in this {@code DefaultTreeTable}.
*/
public void setRoot(final TreeTable.Node root) {
@@ -236,8 +235,8 @@ public class DefaultTreeTable implements
* If the root is an instance of {@link Node}, then cloning the root will recursively clone
* all its {@linkplain Node#getChildren() children}.
*
- * @return A clone of this table.
- * @throws CloneNotSupportedException If this table, the root node or one of its children
+ * @return a clone of this table.
+ * @throws CloneNotSupportedException if this table, the root node or one of its children
* can not be cloned.
*
* @see Node#clone()
@@ -255,7 +254,7 @@ public class DefaultTreeTable implements
* later is an instance of the {@link Node} inner class, then all node values and children
* will be compared recursively.
*
- * @param other The object to compare with this table.
+ * @param other the object to compare with this table.
* @return {@code true} if the two objects are equal.
*
* @see Node#equals(Object)
@@ -291,7 +290,7 @@ public class DefaultTreeTable implements
* developers are encouraged to create and configure their own {@link TreeTableFormat}
* instance.
*
- * @return A string representation of this tree table.
+ * @return a string representation of this tree table.
*/
@Override
public String toString() {
@@ -304,15 +303,14 @@ public class DefaultTreeTable implements
/**
- * A {@link TreeTable.Node} implementation which can store values for a pre-defined list
- * of columns. The list of columns is specified by a {@link TreeTable}, or inherited from
- * a parent node.
+ * A {@link TreeTable.Node} implementation which can store values for a pre-defined list of columns.
+ * The list of columns is specified by a {@link TreeTable}, or inherited from a parent node.
*
* <div class="section">Note on the parent node</div>
- * The value returned by the {@link #getParent()} method is updated automatically when
- * this node is <em>added to</em> or <em>removed from</em> the {@linkplain #getChildren()
- * list of children} of another {@code Node} instance - there is no {@code setParent(Node)}
- * method. As a derived value, the parent is ignored by the {@link #clone()},
+ * The value returned by the {@link #getParent()} method is updated automatically when this node
+ * is <em>added to</em> or <em>removed from</em> the {@linkplain #getChildren() list of children}
+ * of another {@code Node} instance - there is no {@code setParent(Node)} method. Since the parent
+ * is inferred rather than user-specified, it is ignored by the {@link #clone()},
* {@link #equals(Object)} and {@link #hashCode()} methods.
*
* @author Martin Desruisseaux (Geomatys)
@@ -344,7 +342,7 @@ public class DefaultTreeTable implements
* Creates a new, initially empty, node list. The node given in argument to this
* constructor will be the parent of all nodes added as children to this list.
*
- * @param parent The node which will own this list.
+ * @param parent the node which will own this list.
*/
Children(final TreeTable.Node parent) {
super(parent);
@@ -410,7 +408,7 @@ public class DefaultTreeTable implements
* is the caller responsibility to {@linkplain DefaultTreeTable#setRoot set the table root
* node}.</p>
*
- * @param table The table for which this node is created.
+ * @param table the table for which this node is created.
*/
public Node(final TreeTable table) {
ArgumentChecks.ensureNonNull("table", table);
@@ -428,7 +426,7 @@ public class DefaultTreeTable implements
* {@linkplain #getChildren() list of children}. The new node will be able to store values
* for the same columns than the parent node.
*
- * @param parent The parent of the new node.
+ * @param parent the parent of the new node.
*/
public Node(final Node parent) {
ArgumentChecks.ensureNonNull("parent", parent);
@@ -443,8 +441,8 @@ public class DefaultTreeTable implements
* {@linkplain #getChildren() list of children} at the given index. The new node
* will be able to store values for the same columns than the parent node.
*
- * @param parent The parent of the new node.
- * @param index The index where to add the new node in the parent list of children.
+ * @param parent the parent of the new node.
+ * @param index the index where to add the new node in the parent list of children.
*/
public Node(final Node parent, final int index) {
ArgumentChecks.ensureNonNull("parent", parent);
@@ -465,7 +463,7 @@ public class DefaultTreeTable implements
* <tr><td>"Name"</td> <td>{@link CharSequence}</td> <td>{@code name}</td></tr>
* </table>
*
- * @param name The initial value for the "Name" column (can be {@code null}).
+ * @param name the initial value for the "Name" column (can be {@code null}).
*/
public Node(final CharSequence name) {
columnIndices = TableColumn.NAME_MAP;
@@ -529,6 +527,7 @@ public class DefaultTreeTable implements
* cast will need to be replaced by an "instanceof" check.
*/
@Override
+ @SuppressWarnings("ReturnOfCollectionOrArrayField") // Returned list modifiable on intend.
public final List<TreeTable.Node> getChildren() {
if (children == null) {
if (isLeaf()) {
@@ -554,7 +553,7 @@ public class DefaultTreeTable implements
*
* Subclasses may override this method with different behavior.
*
- * @throws UnsupportedOperationException If this node {@linkplain #isLeaf() is a leaf}.
+ * @throws UnsupportedOperationException if this node {@linkplain #isLeaf() is a leaf}.
*/
@Override
public Node newChild() {
@@ -567,9 +566,9 @@ public class DefaultTreeTable implements
/**
* Returns the value in the given column, or {@code null} if none.
*
- * @param <V> The base type of values in the given column.
- * @param column Identifier of the column from which to get the value.
- * @return The value in the given column, or {@code null} if none.
+ * @param <V> the base type of values in the given column.
+ * @param column identifier of the column from which to get the value.
+ * @return the value in the given column, or {@code null} if none.
*/
@Override
public <V> V getValue(final TableColumn<V> column) {
@@ -588,10 +587,10 @@ public class DefaultTreeTable implements
* The {@link #isEditable(TableColumn)} method can be invoked before this setter method
* for determining if the given column is modifiable.
*
- * @param <V> The base type of values in the given column.
- * @param column Identifier of the column into which to set the value.
- * @param value The value to set.
- * @throws IllegalArgumentException If the given column is not a legal column for this node.
+ * @param <V> the base type of values in the given column.
+ * @param column identifier of the column into which to set the value.
+ * @param value the value to set.
+ * @throws IllegalArgumentException if the given column is not a legal column for this node.
*
* @see #isEditable(TableColumn)
*/
@@ -634,8 +633,8 @@ public class DefaultTreeTable implements
* but does not clone the column {@linkplain #getValue(TableColumn) values}.
* The parent of the cloned node is set to {@code null}.
*
- * @return A clone of this node without parent.
- * @throws CloneNotSupportedException If this node or one of its children can not be cloned.
+ * @return a clone of this node without parent.
+ * @throws CloneNotSupportedException if this node or one of its children can not be cloned.
*/
@Override
public Node clone() throws CloneNotSupportedException {
@@ -675,7 +674,7 @@ public class DefaultTreeTable implements
* <li>For making possible to compare branches instead than only whole trees.</li>
* </ul></div>
*
- * @param other The object to compare with this node.
+ * @param other the object to compare with this node.
* @return {@code true} if the two objects are equal, ignoring the parent node.
*/
@Override
@@ -689,7 +688,7 @@ public class DefaultTreeTable implements
if (columnIndices.equals(that.columnIndices)) {
final Object[] v1 = this.values;
final Object[] v2 = that.values;
- if (v1 != v2) { // For skipping the loop if v1 and v2 are null.
+ if (v1 != v2) { // For skipping the loop if v1 and v2 are null.
for (int i=columnIndices.size(); --i>=0;) {
if (!Objects.equals((v1 != null) ? v1[i] : null,
(v2 != null) ? v2[i] : null))
@@ -724,14 +723,18 @@ public class DefaultTreeTable implements
int hash = 0;
final Object[] values = this.values;
if (values != null) {
- // Do not use Objects.hashCode(...) because we want the result of array
- // containing only null elements to be the same than null array (zero).
+ /*
+ * Do not use Objects.hashCode(\u2026) because we want the result of array
+ * containing only null elements to be the same than null array (zero).
+ */
for (int i=values.length; --i>=0;) {
hash = 31*hash + Objects.hashCode(values[i]);
}
}
- // Do not use Objects.hashCode(...) because we
- // want the same result for null and empty list.
+ /*
+ * Do not use Objects.hashCode(\u2026) because we
+ * want the same result for null and empty list.
+ */
if (!isNullOrEmpty(children)) {
hash += 37 * children.hashCode();
}
@@ -746,7 +749,7 @@ public class DefaultTreeTable implements
* where <var>Node</var> is the {@linkplain Class#getSimpleName() simple classname}
* and <var>i</var> is the index of this node in the parent node.
*
- * @return A string representation of this node.
+ * @return a string representation of this node.
*/
@Override
public String toString() {
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeNodeList.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeNodeList.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeNodeList.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeNodeList.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -102,9 +102,9 @@ abstract class TreeNodeList extends Abst
* Returns {@code true} if the node associated to this list is already the parent of the given
* node, {@code false} if the given node has no parent, or throws an exception otherwise.
*
- * @param node The node for which to check the parent.
+ * @param node the node for which to check the parent.
* @return {@code true} if the given node already has its parent set, or {@code false} otherwise.
- * @throws IllegalArgumentException If the given node is the children of another list.
+ * @throws IllegalArgumentException if the given node is the children of another list.
*/
private boolean isParentOf(final TreeTable.Node node) throws IllegalArgumentException {
if (node == parent) {
@@ -130,16 +130,16 @@ abstract class TreeNodeList extends Abst
* do not change the node parent yet.</li>
* </ul>
*
- * @param node The node on which to set the parent (never {@code null}).
- * @param mode One of the {@link #NULL}, {@link #THIS} or {@link #DRY_RUN} constants.
- * @throws IllegalArgumentException If this method can not set the parent of the given node.
+ * @param node the node on which to set the parent (never {@code null}).
+ * @param mode one of the {@link #NULL}, {@link #THIS} or {@link #DRY_RUN} constants.
+ * @throws IllegalArgumentException if this method can not set the parent of the given node.
*/
protected abstract void setParentOf(TreeTable.Node node, int mode) throws IllegalArgumentException;
/**
* Returns the type of elements in this list.
*
- * @return Fixed to {@code TreeTable.Node}.
+ * @return fixed to {@code TreeTable.Node}.
*/
@Override
public final Class<TreeTable.Node> getElementType() {
@@ -149,7 +149,7 @@ abstract class TreeNodeList extends Abst
/**
* Returns the number of nodes in this list.
*
- * @return The number of nodes.
+ * @return the number of nodes.
*/
@Override
public final int size() {
@@ -159,8 +159,8 @@ abstract class TreeNodeList extends Abst
/**
* Returns the node at the specified index in this list.
*
- * @param index The index of the node to fetch.
- * @return The node at the given index (never {@code null}).
+ * @param index the index of the node to fetch.
+ * @return the node at the given index (never {@code null}).
*/
@Override
public TreeTable.Node get(final int index) {
@@ -171,10 +171,10 @@ abstract class TreeNodeList extends Abst
/**
* Sets the node at the specified index in this list.
*
- * @param index The index of the node to set.
- * @param node The node to store at the given index (can not be {@code null}).
- * @return The node which was previously stored at the given index (never {@code null}).
- * @throws IllegalArgumentException If this list can not add the given node, for example
+ * @param index the index of the node to set.
+ * @param node the node to store at the given index (can not be {@code null}).
+ * @return the node which was previously stored at the given index (never {@code null}).
+ * @throws IllegalArgumentException if this list can not add the given node, for example
* if the node is already an element of another {@code TreeNodeList}.
*/
@Override
@@ -201,9 +201,9 @@ abstract class TreeNodeList extends Abst
* Adds the given node at the given index in this list, shifting all nodes currently at
* and after the given index.
*
- * @param index The index where to insert the node.
- * @param node The node to store at the given index (can not be {@code null}).
- * @throws IllegalArgumentException If this list can not add the given node, for example
+ * @param index the index where to insert the node.
+ * @param node the node to store at the given index (can not be {@code null}).
+ * @throws IllegalArgumentException if this list can not add the given node, for example
* if the node is already an element of another {@code TreeNodeList}.
*/
@Override
@@ -241,8 +241,8 @@ abstract class TreeNodeList extends Abst
* occur either because the node is a custom user implementation with pre-set parent, or
* because the node is already presents in this list.
*
- * @param node The node to check.
- * @throws IllegalArgumentException If the given node is already present in this list.
+ * @param node the node to check.
+ * @throws IllegalArgumentException if the given node is already present in this list.
*/
private void ensureNotPresent(final TreeTable.Node node) throws IllegalArgumentException {
for (int i=size; --i>=0;) {
@@ -257,7 +257,7 @@ abstract class TreeNodeList extends Abst
* reverse order (last added nodes are removed first). If this method failed to remove a
* node, then that node and all nodes at lower index will be left in the list.
*
- * @throws IllegalArgumentException If this method failed to remove a node in the given range.
+ * @throws IllegalArgumentException if this method failed to remove a node in the given range.
*/
@Override
protected void removeRange(final int lower, final int upper) throws IllegalArgumentException {
@@ -266,7 +266,7 @@ abstract class TreeNodeList extends Abst
try {
while (i != lower) {
setParentOf(children[i-1], NULL);
- i--; // Must be decremented only after 'setParentOf' returned successfully.
+ i--; // Must be decremented only after 'setParentOf' returned successfully.
}
} finally {
modCount++;
@@ -282,8 +282,8 @@ abstract class TreeNodeList extends Abst
* Removes from this list the node at the given index.
* All nodes after the given index will be shifted by one.
*
- * @param index The index of the node to remove.
- * @return The node which was previously at the given index (never {@code null}).
+ * @param index the index of the node to remove.
+ * @return the node which was previously at the given index (never {@code null}).
*/
@Override
public final TreeTable.Node remove(final int index) throws IllegalArgumentException {
@@ -301,10 +301,10 @@ abstract class TreeNodeList extends Abst
* The default implementation searches the node using the {@link #indexOf(Object)},
* then removes it (if the node has been found) using the {@link #remove(int)} method.
*
- * @param node The node to remove. {@code null} values are ignored.
- * @return {@code true} if the node has been removed, or {@code false} if this list doesn't
+ * @param node the node to remove. {@code null} values are ignored.
+ * @return {@code true} if the node has been removed, or {@code false} if this list does not
* contain the given node.
- * @throws IllegalArgumentException If the node has been found but this list can not remove it.
+ * @throws IllegalArgumentException if the node has been found but this list can not remove it.
*/
@Override
public boolean remove(final Object node) throws IllegalArgumentException {
@@ -321,7 +321,7 @@ abstract class TreeNodeList extends Abst
* if the {@linkplain TreeTable.Node#getParent() node parent} is the {@link #parent} instance.
* This implementation does not iterate over the children.
*
- * @param node The node to check (can be {@code null}).
+ * @param node the node to check (can be {@code null}).
* @return {@code true} if this list contains the given node.
*/
@Override
@@ -334,8 +334,8 @@ abstract class TreeNodeList extends Abst
* This method delegates to {@link #lastIndexOf(Object)} because the list is not
* expected to contain duplicated values.
*
- * @param node The node to search (can be {@code null}).
- * @return Index of the given node, or -1 if not found.
+ * @param node the node to search (can be {@code null}).
+ * @return index of the given node, or -1 if not found.
*/
@Override
public final int indexOf(final Object node) {
@@ -345,8 +345,8 @@ abstract class TreeNodeList extends Abst
/**
* Returns the index of the last occurrence of the specified node in this list.
*
- * @param node The node to search (can be {@code null}).
- * @return Index of the given node, or -1 if not found.
+ * @param node the node to search (can be {@code null}).
+ * @return index of the given node, or -1 if not found.
*/
@Override
public final int lastIndexOf(final Object node) {
Modified: sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeTable.java
URL: http://svn.apache.org/viewvc/sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeTable.java?rev=1778901&r1=1778900&r2=1778901&view=diff
==============================================================================
--- sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeTable.java [UTF-8] (original)
+++ sis/trunk/core/sis-utility/src/main/java/org/apache/sis/util/collection/TreeTable.java [UTF-8] Sun Jan 15 10:36:23 2017
@@ -74,7 +74,7 @@ public interface TreeTable {
* tree. However any {@link Node} instance can return {@code null} for a
* particular column if the node doesn't have that column.
*
- * @return The union of all table columns in every tree node.
+ * @return the union of all table columns in every tree node.
*
* @see Node#getValue(TableColumn)
* @see Node#setValue(TableColumn, Object)
@@ -84,7 +84,7 @@ public interface TreeTable {
/**
* Returns the root node of the tree.
*
- * @return The root node of the tree.
+ * @return the root node of the tree.
*/
Node getRoot();
@@ -119,7 +119,7 @@ public interface TreeTable {
*
* @author Martin Desruisseaux (IRD, Geomatys)
* @since 0.3
- * @version 0.3
+ * @version 0.8
* @module
*/
public static interface Node {
@@ -131,7 +131,7 @@ public interface TreeTable {
* modifiable, then implementations are encouraged to update automatically the parent when a child
* is <em>added to</em> or <em>removed from</em> that collection.</p>
*
- * @return The parent, or {@code null} if none.
+ * @return the parent, or {@code null} if none.
* @category tree
*/
Node getParent();
@@ -163,7 +163,7 @@ public interface TreeTable {
* {@linkplain org.apache.sis.metadata.AbstractMetadata#asTreeTable() metadata tree table view},
* compliance to the {@code List} contract is impractical or inefficient.
*
- * @return The children, or an empty collection if none.
+ * @return the children, or an empty collection if none.
* @category tree
*/
Collection<Node> getChildren();
@@ -174,17 +174,17 @@ public interface TreeTable {
* the end of the collection, but this is not mandatory: implementations can add the child
* at whatever position they see fit.
*
- * @return The new child.
- * @throws UnsupportedOperationException If this node can not add new children.
+ * @return the new child.
+ * @throws UnsupportedOperationException if this node can not add new children.
*/
Node newChild() throws UnsupportedOperationException;
/**
* Returns the value in the given column, or {@code null} if none.
*
- * @param <V> The base type of values in the given column.
- * @param column Identifier of the column from which to get the value.
- * @return The value in the given column, or {@code null} if none.
+ * @param <V> the base type of values in the given column.
+ * @param column identifier of the column from which to get the value.
+ * @return the value in the given column, or {@code null} if none.
*
* @see TreeTable#getColumns()
* @category table
@@ -196,11 +196,11 @@ public interface TreeTable {
* The {@link #isEditable(TableColumn)} method can be invoked before this setter method
* for determining if the given column is modifiable.
*
- * @param <V> The base type of values in the given column.
- * @param column Identifier of the column into which to set the value.
- * @param value The value to set.
- * @throws IllegalArgumentException If the given column is not a legal column for this node.
- * @throws UnsupportedOperationException If values in the given column can not be modified.
+ * @param <V> the base type of values in the given column.
+ * @param column identifier of the column into which to set the value.
+ * @param value the value to set.
+ * @throws IllegalArgumentException if the given column is not a legal column for this node.
+ * @throws UnsupportedOperationException if values in the given column can not be modified.
*
* @see TreeTable#getColumns()
* @see #isEditable(TableColumn)
@@ -213,7 +213,7 @@ public interface TreeTable {
* column is not a legal column for this {@code Node} instance, then this method
* returns {@code false}.
*
- * @param column The column to query.
+ * @param column the column to query.
* @return {@code true} if the given column is a legal column for this {@code Node}
* implementation and the corresponding value is editable, or {@code false}
* otherwise.
@@ -231,9 +231,112 @@ public interface TreeTable {
* <var>longitude</var>) tuple, then a {@code TreeTable.Node} could be defined to have 3 columns for the
* above 3 tuple components, and the user object could be the original {@code CityLocation} instance.</div>
*
- * @return Any object stored at this node by the user, or {@code null} if none.
+ * @return any object stored at this node by the user, or {@code null} if none.
* @category tree
*/
Object getUserObject();
+
+ /**
+ * Returns {@code true} if the given object is a node with the same content than this node.
+ * For this method, the meaning of <cite>same content</cite> is defined as below:
+ *
+ * <ul>
+ * <li>The given object is also a {@code Node}.</li>
+ * <li>The list returned by {@link TreeTable#getColumns()} is equals for both nodes.</li>
+ * <li>The objects returned by {@link #getValue(TableColumn)} are equal for each column.</li>
+ * <li>The list returned by {@linkplain #getChildren() children} is equals for both node.</li>
+ * </ul>
+ *
+ * The node returned by {@link #getParent()} shall <strong>not</strong> be taken in account.
+ * It is necessary to ignore the parent for consistency with {@linkplain DefaultTreeTable#clone() clone}
+ * and for avoiding infinite recursivity when comparing the children.
+ * A third reason is given in the <cite>purpose</cite> example below.
+ *
+ * <div class="note"><b>Purpose of this method: example with ISO metadata</b><br>
+ * Consider the following tree made of ISO 19115 metadata objects: a platform containing a list of instruments,
+ * and an instrument containing a reference to the platform on which the instrument is installed. In this example,
+ * nodes 2 and 4 contain a reference to the same {@code Platform} instance, so we have a cyclic graph:
+ *
+ * <table class="compact" summary="Metadata tree example">
+ * <tr><th>Node 1:</th><td>{@code �}{@linkplain org.apache.sis.metadata.iso.acquisition.DefaultAcquisitionInformation Acquisition information}</td></tr>
+ * <tr><th>Node 2:</th><td>{@code ��\u2514\u2500}{@linkplain org.apache.sis.metadata.iso.acquisition.DefaultPlatform Platform}</td></tr>
+ * <tr><th>Node 3:</th><td>{@code �����\u2514\u2500}{@linkplain org.apache.sis.metadata.iso.acquisition.DefaultInstrument Instrument}</td></tr>
+ * <tr><th>Node 4:</th><td>{@code ��������\u2514\u2500}{@linkplain org.apache.sis.metadata.iso.acquisition.DefaultPlatform Platform} (same instance than above)</td></tr>
+ * <tr><th>Node 5:</th><td>{@code �����������\u2514\u2500}<i>etc\u2026</i></td></tr>
+ * </table>
+ *
+ * The {@link org.apache.sis.metadata.AbstractMetadata#asTreeTable()} method gives a view in which each node
+ * has its content fully generated from wrapped metadata object. Consequently a naive walk over the above tree
+ * causes an infinite loop with {@code TreeTable}�generating nodes with identical content as we bounce between
+ * {@code Platform} and {@code Instrument} metadata objects. To break this loop, we need to know when the
+ * <em>content</em> of a node (in this example, the wrapped metadata object) has already been visited.
+ * The parent shall <strong>not</strong> be taken in account since node 2 and 4 have different parents
+ * despite having the same {@code Platform}�content.
+ *
+ * <p>In this use case, the {@code Node.equals(Object)} implementation needs only to compare the wrapped
+ * metadata (usually given by the {@linkplain #getUserObject() user object}) since the node content,
+ * including the list of children, is fully determined by those metadata. An identity comparison
+ * (with {@code ==}) is sufficient for the purpose of avoiding infinite recursivity.</p></div>
+ *
+ * <div class="section">Flexibility in implementations</div>
+ * The above list specifies minimal conditions that must be true when two nodes are considered equal.
+ * Implementations should not relax those conditions, but are free to make them more restrictive.
+ * In particular, many implementations will require that the two nodes are instances of the same class.
+ * Some implementations may also perform identity comparisons (with the {@code ==} operator) between values
+ * instead than using {@link Object#equals(Object)}. This flexibility means that even if all above conditions
+ * are true, this is not a guarantee that this method will return {@code true}.
+ *
+ * <p>It is okay to <em>not</em> override this method at all since the identity comparison inherited from
+ * {@link Object#equals(Object)} is consistent with this method contract. Alternatively, {@code Node}
+ * implementations having a content fully determined by the wrapped {@linkplain #getUserObject() user
+ * object} need only the following implementation:</p>
+ *
+ * {@preformat java
+ * @Override
+ * public boolean equals(Object obj) {
+ * return (obj instanceof MyNode) && ((MyNode) obj).getUserObject() == getUserObject();
+ * }
+ * }
+ *
+ * Implementation details may vary, for example in the way to compare {@code null} user objects or by invoking
+ * {@link Object#equals(Object)} instead than performing identity comparisons. Note however that since this
+ * method purpose is to detect cyclic graphs (see above example), user objects should be compared with
+ * {@code equals(Object)} only if their implementations are known to be safe against infinite recursivity.
+ *
+ * @param other the other object to compare with this node.
+ * @return whether the two objects are nodes with equal values and equal children, ignoring parents.
+ *
+ * @since 0.8
+ */
+ @Override
+ boolean equals(Object other);
+
+ /**
+ * Returns a hash code value consistent with the {@code equals(Object)} implementation for this node.
+ * If the {@link #equals(Object)} method has not been overridden, then this {@code hashCode()} method
+ * should not be overridden neither. Otherwise if this node content ({@linkplain #getValue values} and
+ * {@linkplain #getChildren() children}) is fully generated from the {@linkplain #getUserObject() user
+ * object}, then the {@code equals(\u2026)} and {@code hashCode()} methods may be implemented like below:
+ *
+ * {@preformat java
+ * @Override
+ * public boolean equals(Object obj) {
+ * return (obj instanceof MyNode) && ((MyNode) obj).getUserObject() == getUserObject();
+ * }
+ *
+ * @Override
+ * public int hashCode() {
+ * return System.identityHashCode(getUserObject());
+ * }
+ * }
+ *
+ * Otherwise this method should compute a hash code based on values and children of this node, ignoring parent.
+ *
+ * @return a hash code for this node, potentially based on values and children but ignoring parent.
+ *
+ * @since 0.8
+ */
+ @Override
+ int hashCode();
}
}