sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1759104 - in /sis/branches/JDK8/core/sis-metadata/src: main/java/org/apache/sis/metadata/ main/java/org/apache/sis/metadata/iso/extent/ test/java/org/apache/sis/metadata/
Date Sat, 03 Sep 2016 16:37:10 GMT
Author: desruisseaux
Date: Sat Sep  3 16:37:10 2016
New Revision: 1759104

URL: http://svn.apache.org/viewvc?rev=1759104&view=rev
Log:
Javadoc formatting. There is no significant code change in this commit.

Modified:
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
    sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/DefaultTemporalExtent.java
    sis/branches/JDK8/core/sis-metadata/src/test/java/org/apache/sis/metadata/PropertyAccessorTest.java

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java?rev=1759104&r1=1759103&r2=1759104&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/ModifiableMetadata.java
[UTF-8] Sat Sep  3 16:37:10 2016
@@ -163,7 +163,7 @@ public abstract class ModifiableMetadata
      *       {@linkplain #freeze() freeze} the clone before to return it.</li>
      * </ul>
      *
-     * @return An unmodifiable copy of this metadata.
+     * @return an unmodifiable copy of this metadata.
      */
     public AbstractMetadata unmodifiable() {
         // Reminder: 'unmodifiable' is reset to null by checkWritePermission().
@@ -260,11 +260,11 @@ public abstract class ModifiableMetadata
      *   <li>Copies the content of the given {@code source} into the target.</li>
      * </ul>
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  source      The source list, or {@code null}.
-     * @param  target      The target list, or {@code null} if not yet created.
-     * @param  elementType The base type of elements to put in the list.
-     * @return A list (possibly the {@code target} instance) containing the {@code source}
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  source       the source list, or {@code null}.
+     * @param  target       the target list, or {@code null} if not yet created.
+     * @param  elementType  the base type of elements to put in the list.
+     * @return a list (possibly the {@code target} instance) containing the {@code source}
      *         elements, or {@code null} if the source was null.
      * @throws UnmodifiableMetadataException if this metadata is unmodifiable.
      *
@@ -307,11 +307,11 @@ public abstract class ModifiableMetadata
      *   <li>Copies the content of the given {@code source} into the target.</li>
      * </ul>
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  source      The source set, or {@code null}.
-     * @param  target      The target set, or {@code null} if not yet created.
-     * @param  elementType The base type of elements to put in the set.
-     * @return A set (possibly the {@code target} instance) containing the {@code source}
elements,
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  source       the source set, or {@code null}.
+     * @param  target       the target set, or {@code null} if not yet created.
+     * @param  elementType  the base type of elements to put in the set.
+     * @return a set (possibly the {@code target} instance) containing the {@code source}
elements,
      *         or {@code null} if the source was null.
      * @throws UnmodifiableMetadataException if this metadata is unmodifiable.
      *
@@ -362,11 +362,11 @@ public abstract class ModifiableMetadata
      * implementor choice. The default implementation invokes {@link #collectionType(Class)}
      * in order to get a hint about whether a {@link List} or a {@link Set} should be used.
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  source      The source collection, or {@code null}.
-     * @param  target      The target collection, or {@code null} if not yet created.
-     * @param  elementType The base type of elements to put in the collection.
-     * @return A collection (possibly the {@code target} instance) containing the {@code
source} elements,
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  source       the source collection, or {@code null}.
+     * @param  target       the target collection, or {@code null} if not yet created.
+     * @param  elementType  the base type of elements to put in the collection.
+     * @return a collection (possibly the {@code target} instance) containing the {@code
source} elements,
      *         or {@code null} if the source was null.
      * @throws UnmodifiableMetadataException if this metadata is unmodifiable.
      */
@@ -415,10 +415,10 @@ public abstract class ModifiableMetadata
      * or returns {@code null} if the source is {@code null} or empty.
      * This is a convenience method for copying fields in subclass copy constructors.
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  source      The source collection, or {@code null}.
-     * @param  elementType The base type of elements to put in the list.
-     * @return A list containing the {@code source} elements,
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  source       the source collection, or {@code null}.
+     * @param  elementType  the base type of elements to put in the list.
+     * @return a list containing the {@code source} elements,
      *         or {@code null} if the source was null or empty.
      */
     protected final <E> List<E> copyList(final Collection<? extends E>
source, final Class<E> elementType) {
@@ -435,10 +435,10 @@ public abstract class ModifiableMetadata
      * or returns {@code null} if the source is {@code null} or empty.
      * This is a convenience method for copying fields in subclass copy constructors.
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  source      The source collection, or {@code null}.
-     * @param  elementType The base type of elements to put in the set.
-     * @return A set containing the {@code source} elements,
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  source       the source collection, or {@code null}.
+     * @param  elementType  the base type of elements to put in the set.
+     * @return a set containing the {@code source} elements,
      *         or {@code null} if the source was null or empty.
      */
     protected final <E> Set<E> copySet(final Collection<? extends E> source,
final Class<E> elementType) {
@@ -458,10 +458,10 @@ public abstract class ModifiableMetadata
      * <p>The collection type is selected as described in the
      * {@link #nonNullCollection(Collection, Class)}.</p>
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  source      The source collection, or {@code null}.
-     * @param  elementType The base type of elements to put in the collection.
-     * @return A collection containing the {@code source} elements,
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  source       the source collection, or {@code null}.
+     * @param  elementType  the base type of elements to put in the collection.
+     * @return a collection containing the {@code source} elements,
      *         or {@code null} if the source was null or empty.
      */
     protected final <E> Collection<E> copyCollection(final Collection<? extends
E> source, final Class<E> elementType) {
@@ -486,10 +486,10 @@ public abstract class ModifiableMetadata
      * <p>The collection type is selected as described in the
      * {@link #nonNullCollection(Collection, Class)}.</p>
      *
-     * @param  <E>         The type represented by the {@code Class} argument.
-     * @param  value       The singleton value to put in the returned collection, or {@code
null}.
-     * @param  elementType The element type (used only if {@code value} is non-null).
-     * @return A new modifiable collection containing the given value,
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  value        the singleton value to put in the returned collection, or {@code
null}.
+     * @param  elementType  the element type (used only if {@code value} is non-null).
+     * @return a new modifiable collection containing the given value,
      *         or {@code null} if the given value was null.
      */
     protected final <E> Collection<E> singleton(final E value, final Class<E>
elementType) {
@@ -521,9 +521,9 @@ public abstract class ModifiableMetadata
      * Returns the specified list, or a new one if {@code c} is null.
      * This is a convenience method for implementation of {@code getFoo()} methods.
      *
-     * @param  <E> The type represented by the {@code Class} argument.
-     * @param  c The existing list, or {@code null} if the list has not yet been created.
-     * @param  elementType The element type (used only if {@code c} is null).
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  c            the existing list, or {@code null} if the list has not yet been
created.
+     * @param  elementType  the element type (used only if {@code c} is null).
      * @return {@code c}, or a new list if {@code c} is null.
      */
     protected final <E> List<E> nonNullList(final List<E> c, final Class<E>
elementType) {
@@ -550,9 +550,9 @@ public abstract class ModifiableMetadata
      * Returns the specified set, or a new one if {@code c} is null.
      * This is a convenience method for implementation of {@code getFoo()} methods.
      *
-     * @param  <E> The type represented by the {@code Class} argument.
-     * @param  c The existing set, or {@code null} if the set has not yet been created.
-     * @param  elementType The element type (used only if {@code c} is null).
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  c            the existing set, or {@code null} if the set has not yet been
created.
+     * @param  elementType  the element type (used only if {@code c} is null).
      * @return {@code c}, or a new set if {@code c} is null.
      */
     protected final <E> Set<E> nonNullSet(final Set<E> c, final Class<E>
elementType) {
@@ -573,16 +573,15 @@ public abstract class ModifiableMetadata
      * This is a convenience method for implementation of {@code getFoo()} methods.
      *
      * <div class="section">Choosing a collection type</div>
-     * Implementations shall invoke {@link #nonNullList nonNullList(…)} or {@link #nonNullSet
-     * nonNullSet(…)} instead than this method when the collection type is enforced by
ISO
-     * specification. When the type is not enforced by the specification, some freedom are
-     * allowed at implementor choice. The default implementation invokes
-     * {@link #collectionType(Class)} in order to get a hint about whether a {@link List}
-     * or a {@link Set} should be used.
-     *
-     * @param  <E> The type represented by the {@code Class} argument.
-     * @param  c The existing collection, or {@code null} if the collection has not yet been
created.
-     * @param  elementType The element type (used only if {@code c} is null).
+     * Implementations shall invoke {@link #nonNullList nonNullList(…)} or {@link #nonNullSet
nonNullSet(…)}
+     * instead than this method when the collection type is enforced by ISO specification.
+     * When the type is not enforced by the specification, some freedom are allowed at implementor
choice.
+     * The default implementation invokes {@link #collectionType(Class)} in order to get
a hint about whether
+     * a {@link List} or a {@link Set} should be used.
+     *
+     * @param  <E>          the type represented by the {@code Class} argument.
+     * @param  c            the existing collection, or {@code null} if the collection has
not yet been created.
+     * @param  elementType  the element type (used only if {@code c} is null).
      * @return {@code c}, or a new collection if {@code c} is null.
      */
     protected final <E> Collection<E> nonNullCollection(final Collection<E>
c, final Class<E> elementType) {
@@ -643,14 +642,14 @@ public abstract class ModifiableMetadata
      * versions may accept other types.
      *
      * <p>The default implementation returns <code>{@linkplain Set}.class</code>
if the element type
-     * is assignable to {@link CodeList}, {@link Enum}, {@link String}, {@link Charset},
{@link Locale}
-     * or {@link Currency}, and <code>{@linkplain List}.class</code> otherwise.
+     * is assignable to {@link CodeList}, {@link Enum}, {@link String}, {@link Charset},
+     * {@link Locale} or {@link Currency}, and <code>{@linkplain List}.class</code>
otherwise.
      * Subclasses can override this method for choosing different kind of collections.
      * <em>Note however that {@link Set} should be used only with immutable element
types</em>,
      * for {@linkplain Object#hashCode() hash code} stability.</p>
      *
-     * @param  <E> The type of elements in the collection to be created.
-     * @param  elementType The type of elements in the collection to be created.
+     * @param  <E>          the type of elements in the collection to be created.
+     * @param  elementType  the type of elements in the collection to be created.
      * @return {@code List.class} or {@code Set.class} depending on whether the
      *         property shall accept duplicated values or not.
      */
@@ -666,14 +665,21 @@ public abstract class ModifiableMetadata
     }
 
     /**
-     * Returns a shallow copy of this metadata.
-     * While {@linkplain Cloneable cloneable}, this class does not provides the {@code clone()}
-     * operation as part of the public API. The clone operation is required for the internal
-     * working of the {@link #unmodifiable()} method, which needs <em>shallow</em>
-     * copies of metadata entities. The default {@link Object#clone()} implementation is
-     * sufficient in most cases.
+     * Creates a <strong>shallow</strong> copy of this metadata.
+     * The clone operation is required for the internal working of the {@link #unmodifiable()}
method,
+     * which needs <em>shallow</em> copies of metadata entities.
+     *
+     * <div class="section">API note</div>
+     * While {@link Cloneable}, the {@code ModifiableMetadata} subclasses should not provide
+     * the {@code clone()} operation as part of their public API, because the cloned object
+     * share reference to the same collections than the original object.
+     *
+     * <div class="section">Note for subclass implementors</div>
+     * The default {@link Object#clone()} implementation is sufficient in most cases.
+     * The need to override this method should be rare, but may happen if the object
+     * contains for example connection to a database.
      *
-     * @return A <em>shallow</em> copy of this metadata.
+     * @return a <em>shallow</em> copy of this metadata.
      * @throws CloneNotSupportedException if the clone is not supported.
      */
     @Override

Modified: sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/DefaultTemporalExtent.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/DefaultTemporalExtent.java?rev=1759104&r1=1759103&r2=1759104&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/DefaultTemporalExtent.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/main/java/org/apache/sis/metadata/iso/extent/DefaultTemporalExtent.java
[UTF-8] Sat Sep  3 16:37:10 2016
@@ -85,7 +85,7 @@ public class DefaultTemporalExtent exten
      * This is a <cite>shallow</cite> copy constructor, since the other metadata
contained in the
      * given object are not recursively copied.
      *
-     * @param object The metadata to copy values from, or {@code null} if none.
+     * @param  object  the metadata to copy values from, or {@code null} if none.
      *
      * @see #castOrCopy(TemporalExtent)
      */
@@ -113,8 +113,8 @@ public class DefaultTemporalExtent exten
      *       metadata contained in the given object are not recursively copied.</li>
      * </ul>
      *
-     * @param  object The object to get as a SIS implementation, or {@code null} if none.
-     * @return A SIS implementation containing the values of the given object (may be the
+     * @param  object  the object to get as a SIS implementation, or {@code null} if none.
+     * @return a SIS implementation containing the values of the given object (may be the
      *         given object itself), or {@code null} if the argument was null.
      */
     public static DefaultTemporalExtent castOrCopy(final TemporalExtent object) {
@@ -134,7 +134,7 @@ public class DefaultTemporalExtent exten
      * then this method will build an extent from the {@linkplain #getStartTime() start
      * time} and {@linkplain #getEndTime() end time} if any.
      *
-     * @return The date and time for the content, or {@code null}.
+     * @return the date and time for the content, or {@code null}.
      */
     @Override
     @XmlElement(name = "extent", required = true)
@@ -145,7 +145,7 @@ public class DefaultTemporalExtent exten
     /**
      * Sets the date and time for the content of the dataset.
      *
-     * @param newValue The new content date.
+     * @param  newValue  the new content date.
      */
     public void setExtent(final TemporalPrimitive newValue) {
         checkWritePermission();
@@ -155,9 +155,9 @@ public class DefaultTemporalExtent exten
     /**
      * Infers a value from the extent as a {@link Date} object.
      *
-     * @param begin {@code true} if we are asking for the start time,
-     *              or {@code false} for the end time.
-     * @return The requested time as a Java date, or {@code null} if none.
+     * @param  begin  {@code true} if we are asking for the start time,
+     *                or {@code false} for the end time.
+     * @return the requested time as a Java date, or {@code null} if none.
      */
     static Date getTime(final TemporalPrimitive extent, final boolean begin) {
         final Instant instant;
@@ -175,7 +175,7 @@ public class DefaultTemporalExtent exten
      * The start date and time for the content of the dataset.
      * This method tries to infer it from the {@linkplain #getExtent() extent}.
      *
-     * @return The start time, or {@code null} if none.
+     * @return the start time, or {@code null} if none.
      */
     public Date getStartTime() {
         return getTime(extent, true);
@@ -185,7 +185,7 @@ public class DefaultTemporalExtent exten
      * Returns the end date and time for the content of the dataset.
      * This method tries to infer it from the {@linkplain #getExtent() extent}.
      *
-     * @return The end time, or {@code null} if none.
+     * @return the end time, or {@code null} if none.
      */
     public Date getEndTime() {
         return getTime(extent, false);
@@ -198,8 +198,8 @@ public class DefaultTemporalExtent exten
      * <p><b>Note:</b> this method is available only if the {@code sis-temporal}
module is available on the classpath,
      * or any other module providing an implementation of the {@link org.opengis.temporal.TemporalFactory}
interface.</p>
      *
-     * @param  startTime The start date and time for the content of the dataset, or {@code
null} if none.
-     * @param  endTime   The end date and time for the content of the dataset, or {@code
null} if none.
+     * @param  startTime  the start date and time for the content of the dataset, or {@code
null} if none.
+     * @param  endTime    the end date and time for the content of the dataset, or {@code
null} if none.
      * @throws UnsupportedOperationException if no implementation of {@code TemporalFactory}
has been found
      *         on the classpath.
      */
@@ -225,7 +225,7 @@ public class DefaultTemporalExtent exten
      * <p><b>Note:</b> this method is available only if the {@code sis-referencing}
module is
      * available on the classpath.</p>
      *
-     * @param  envelope The envelope to use for setting this temporal extent.
+     * @param  envelope  the envelope to use for setting this temporal extent.
      * @throws UnsupportedOperationException if the referencing module or the temporal module
is not on the classpath.
      * @throws TransformException if the envelope can not be transformed to a temporal extent.
      *

Modified: sis/branches/JDK8/core/sis-metadata/src/test/java/org/apache/sis/metadata/PropertyAccessorTest.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-metadata/src/test/java/org/apache/sis/metadata/PropertyAccessorTest.java?rev=1759104&r1=1759103&r2=1759104&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-metadata/src/test/java/org/apache/sis/metadata/PropertyAccessorTest.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-metadata/src/test/java/org/apache/sis/metadata/PropertyAccessorTest.java
[UTF-8] Sat Sep  3 16:37:10 2016
@@ -85,6 +85,7 @@ import static org.apache.sis.metadata.Pr
  * @version 0.5
  * @module
  */
+@SuppressWarnings("OverlyStrongTypeCast")
 @DependsOn(PropertyInformationTest.class)
 public final strictfp class PropertyAccessorTest extends TestCase {
     /**



Mime
View raw message