sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1553253 - in /sis/branches/JDK7: core/sis-metadata/src/main/java/org/apache/sis/metadata/ core/sis-referencing/src/main/java/org/apache/sis/referencing/ core/sis-utility/src/main/java/org/apache/sis/internal/converter/ core/sis-utility/src...
Date Tue, 24 Dec 2013 06:35:36 GMT
Author: desruisseaux
Date: Tue Dec 24 06:35:36 2013
New Revision: 1553253

URL: http://svn.apache.org/r1553253
Log:
Replaced the @ThreadSafe annotation by javadoc, in order to explain
better the context or conditions (if any) for thread-safety to hold
(SIS-156).

Removed:
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/ThreadSafe.java
Modified:
    sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
    sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
    sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/ConverterRegistry.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/SystemRegistry.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/ClassFormat.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/DefaultFormat.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/Cache.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/CacheEntries.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakHashSet.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakValueHashMap.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultInternationalString.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerFactory.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/MonolineFormatter.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListeners.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/resources/IndexedResourceBundle.java
    sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
    sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
    sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
    sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java

Modified: sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/AbstractMetadata.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -63,6 +63,7 @@ import org.apache.sis.util.logging.Loggi
  * </tr>
  * </table>
  *
+ * {@section Thread safety}
  * Instances of this class are <strong>not</strong> synchronized for multi-threading.
  * Synchronization, if needed, is caller's responsibility. Note that synchronization locks
  * are not necessarily the metadata instances. For example an other common approach is to

Modified: sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/MetadataStandard.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -31,7 +31,6 @@ import org.opengis.metadata.ExtendedElem
 import org.opengis.referencing.ReferenceIdentifier;
 import org.apache.sis.util.Debug;
 import org.apache.sis.util.Classes;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.ComparisonMode;
 import org.apache.sis.util.resources.Errors;
 import org.apache.sis.util.collection.TreeTable;
@@ -81,6 +80,12 @@ import static org.apache.sis.util.Argume
  *       method must be overridden in a {@code MetadataStandard} subclass.</li>
  * </ul>
  *
+ * {@section Thread safety}
+ * The same {@code MetadataStandard} instance can be safely used by many threads without
synchronization
+ * on the part of the caller. Subclasses shall make sure that any overridden methods remain
safe to call
+ * from multiple threads, because the same {@code MetadataStandard} instances are typically
referenced
+ * by a large amount of {@link ModifiableMetadata}.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-2.4)
  * @version 0.3
@@ -88,7 +93,6 @@ import static org.apache.sis.util.Argume
  *
  * @see AbstractMetadata
  */
-@ThreadSafe
 public class MetadataStandard implements Serializable {
     /**
      * For cross-version compatibility.

Modified: sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-metadata/src/main/java/org/apache/sis/metadata/PropertyAccessor.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -36,7 +36,6 @@ import org.apache.sis.util.Classes;
 import org.apache.sis.util.Numbers;
 import org.apache.sis.util.ArraysExt;
 import org.apache.sis.util.Utilities;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Workaround;
 import org.apache.sis.util.CharSequences;
 import org.apache.sis.util.ComparisonMode;
@@ -76,12 +75,17 @@ import static org.apache.sis.util.collec
  *       XML marshalling.</li>
  * </ul>
  *
+ * {@section Thread safety}
+ * The same {@code PropertyAccessor} instance can be safely used by many threads without
synchronization
+ * on the part of the caller. Subclasses shall make sure that any overridden methods remain
safe to call
+ * from multiple threads, because the same {@code PropertyAccessor} instances are typically
used by many
+ * {@link ModifiableMetadata} instances.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-2.4)
  * @version 0.3
  * @module
  */
-@ThreadSafe
 class PropertyAccessor {
     /**
      * Getters shared between many instances of this class. Two different implementations

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/referencing/AbstractIdentifiedObject.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -42,8 +42,6 @@ import org.apache.sis.internal.referenci
 import org.apache.sis.internal.jaxb.referencing.Code;
 import org.apache.sis.io.wkt.FormattableObject;
 import org.apache.sis.xml.Namespaces;
-import org.apache.sis.util.Immutable;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Deprecable;
 import org.apache.sis.util.ComparisonMode;
 import org.apache.sis.util.LenientComparable;
@@ -100,13 +98,18 @@ import java.util.Objects;
  *       All other information are fetched from the database.</li>
  * </ul>
  *
+ * {@section Thread safety}
+ * This base class is immutable if the {@link Citation}, {@link ReferenceIdentifier}, {@link
GenericName} and
+ * {@link InternationalString} instances given to the constructor are also immutable. Most
SIS subclasses are
+ * immutable under the same conditions. This means that unless otherwise noted in the javadoc,
+ * {@code IdentifiedObject} instances created by SIS factories can be shared by many objects
and passed between
+ * threads without synchronization.
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-1.2)
  * @version 0.4
  * @module
  */
-@Immutable
-@ThreadSafe
 @XmlType(name="IdentifiedObjectType", propOrder={
     "identifier",
     "names",

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/ConverterRegistry.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/ConverterRegistry.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/ConverterRegistry.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/ConverterRegistry.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -21,7 +21,6 @@ import java.util.LinkedHashMap;
 import org.apache.sis.util.Debug;
 import org.apache.sis.util.Classes;
 import org.apache.sis.util.Numbers;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.ObjectConverter;
 import org.apache.sis.util.UnconvertibleObjectException;
@@ -41,17 +40,19 @@ import org.apache.sis.util.resources.Err
  * initialized with default converters is provided by the {@link SystemRegistry#INSTANCE}
constant.</p>
  *
  * {@section Note about conversions from interfaces}
- * {@code ConverterRegistry} is primarily designed for handling converters from classes to
- * other classes. Handling of interfaces are not prohibited (and actually sometime supported),
- * but their behavior may be more ambiguous than in the case of classes because of
- * multi-inheritance in interface hierarchy.
+ * {@code ConverterRegistry} is primarily designed for handling converters from classes to
other classes.
+ * Handling of interfaces are not prohibited (and actually sometime supported), but their
behavior may be
+ * more ambiguous than in the case of classes because of multi-inheritance in interface hierarchy.
+ *
+ * {@section Thread safety}
+ * This base class is thread-safe. Subclasses shall make sure that any overridden methods
remain safe to call
+ * from multiple threads.
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.00)
  * @version 0.3
  * @module
  */
-@ThreadSafe
 public class ConverterRegistry {
     /**
      * The map of converters of any kind. For any key of type {@code ClassPair<S,T>},

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/SystemRegistry.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/SystemRegistry.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/SystemRegistry.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/internal/converter/SystemRegistry.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -20,7 +20,6 @@ import java.util.Date;
 import java.util.ServiceLoader;
 import org.opengis.util.CodeList;
 import org.apache.sis.util.Numbers;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.ObjectConverter;
 import org.apache.sis.util.UnconvertibleObjectException;
 import org.apache.sis.internal.system.SystemListener;
@@ -46,12 +45,14 @@ import org.apache.sis.internal.system.Mo
  * of the above-cited heuristic rules. This differs from the {@link ConverterRegistry} behavior,
  * where only registered converters are used.
  *
+ * {@section Thread safety}
+ * The same {@link #INSTANCE} can be safely used by many threads without synchronization
on the part of the caller.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.02)
  * @version 0.3
  * @module
  */
-@ThreadSafe
 public final class SystemRegistry extends ConverterRegistry {
     /**
      * The default system-wide instance. This register is initialized with conversions between

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/ClassFormat.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/ClassFormat.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/ClassFormat.java [UTF-8]
(original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/ClassFormat.java [UTF-8]
Tue Dec 24 06:35:36 2013
@@ -20,19 +20,21 @@ import java.text.Format;
 import java.text.FieldPosition;
 import java.text.ParsePosition;
 import java.io.InvalidObjectException;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Classes;
 
 
 /**
  * Used by {@link CompoundFormat} for formatting the names of object of type {@link Class}.
  *
+ * {@section Thread safety}
+ * The same {@link #INSTANCE} can be safely used by many threads without synchronization
on the part of the caller.
+ * Note that this is specific to {@code ClassFormat} and generally not true for arbitrary
{@code Format} classes.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
  * @version 0.3
  * @module
  */
-@ThreadSafe
 final class ClassFormat extends Format {
     /**
      * For cross-version compatibility.

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/DefaultFormat.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/DefaultFormat.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/DefaultFormat.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/io/DefaultFormat.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -22,7 +22,6 @@ import java.text.ParsePosition;
 import java.text.ParseException;
 import java.io.InvalidObjectException;
 import org.apache.sis.util.Numbers;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.CharSequences;
 import org.apache.sis.internal.util.LocalizedParseException;
 
@@ -33,12 +32,16 @@ import org.apache.sis.internal.util.Loca
  * than the {@link java.text} package because the former provide the best guarantees
  * to format all significant digits.
  *
+ * {@section Thread safety}
+ * The same {@linkplain #getInstance instance} can be safely used by many threads without
synchronization
+ * on the part of the caller. Note that this is specific to {@code DefaultFormat} and generally
not true
+ * for arbitrary {@code Format} classes.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
  * @version 0.3
  * @module
  */
-@ThreadSafe
 final class DefaultFormat extends Format {
     /**
      * For cross-version compatibility.

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/Cache.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/Cache.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/Cache.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/Cache.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -28,7 +28,6 @@ import java.util.concurrent.locks.Reentr
 import java.lang.ref.Reference;
 import java.lang.ref.WeakReference;
 import java.lang.ref.SoftReference;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Disposable;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.resources.Errors;
@@ -139,7 +138,6 @@ import org.apache.sis.internal.jdk8.Supp
  * @version 0.4
  * @module
  */
-@ThreadSafe
 public class Cache<K,V> extends AbstractMap<K,V> {
     /**
      * The map that contains the cached values. If a value is under the process of being
@@ -862,6 +860,8 @@ public class Cache<K,V> extends Abstract
      * than the ones documented in the {@link ConcurrentHashMap#entrySet()} method, except
that
      * it doesn't support removal of elements (including through the {@link Iterator#remove}
      * method call).
+     *
+     * @return A view of the entries contained in this map.
      */
     @Override
     public Set<Entry<K,V>> entrySet() {

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/CacheEntries.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/CacheEntries.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/CacheEntries.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/CacheEntries.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -23,7 +23,6 @@ import java.util.AbstractSet;
 import java.util.AbstractMap.SimpleEntry;
 import java.util.NoSuchElementException;
 import java.lang.ref.Reference;
-import org.apache.sis.util.ThreadSafe;
 
 
 /**
@@ -33,6 +32,9 @@ import org.apache.sis.util.ThreadSafe;
  * <p>This class is not needed for the normal working of {@link Cache}. it is used
only if
  * the user wants to see the cache entries through the standard Java collection API.</p>
  *
+ * {@section Thread safety}
+ * This class is thread-safe if and only if the {@code Set} given to the constructor is thread-safe.
+ *
  * @param <K> The type of key objects.
  * @param <V> The type of value objects.
  *
@@ -41,7 +43,6 @@ import org.apache.sis.util.ThreadSafe;
  * @version 0.3
  * @module
  */
-@ThreadSafe // Assuming that the set given to the constructor is concurrent.
 final class CacheEntries<K,V> extends AbstractSet<Map.Entry<K,V>> {
     /**
      * The set of entries in the {@link Cache#map}.
@@ -50,6 +51,8 @@ final class CacheEntries<K,V> extends Ab
 
     /**
      * Wraps the given set of entries of a {@link Cache#map}.
+     *
+     * @param entries The set of entries. Implementation shall support concurrency.
      */
     CacheEntries(final Set<Map.Entry<K,Object>> entries) {
         this.entries = entries;

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakHashSet.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakHashSet.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakHashSet.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakHashSet.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -23,7 +23,6 @@ import java.lang.reflect.Array;
 import org.apache.sis.util.Debug;
 import org.apache.sis.util.ArraysExt;
 import org.apache.sis.util.Utilities;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Workaround;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.NullArgumentException;
@@ -63,8 +62,12 @@ import java.util.Objects;
  *     }
  * }
  *
- * Thus, {@code WeakHashSet} can be used inside a factory to prevent creating duplicate
- * immutable objects.
+ * Thus, {@code WeakHashSet} can be used inside a factory to prevent creating duplicate immutable
objects.
+ *
+ * {@section Thread safety}
+ * The same {@code WeakHashSet} instance can be safely used by many threads without synchronization
on the part of
+ * the caller. But if a sequence of two or more method calls need to appear atomic from other
threads perspective,
+ * then the caller can synchronize on {@code this}.
  *
  * @param <E> The type of elements in the set.
  *
@@ -75,7 +78,6 @@ import java.util.Objects;
  *
  * @see java.util.WeakHashMap
  */
-@ThreadSafe
 public class WeakHashSet<E> extends AbstractSet<E> implements CheckedContainer<E>
{
     /**
      * A weak reference to an element. This is an element in a linked list.

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakValueHashMap.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakValueHashMap.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakValueHashMap.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/collection/WeakValueHashMap.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -27,7 +27,6 @@ import java.lang.ref.WeakReference;
 import org.apache.sis.util.Debug;
 import org.apache.sis.util.ArraysExt;
 import org.apache.sis.util.Utilities;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Workaround;
 import org.apache.sis.util.NullArgumentException;
 import org.apache.sis.util.resources.Errors;
@@ -71,6 +70,11 @@ import java.util.Objects;
  * <p>{@code WeakValueHashMap} works with array keys as one would expect. For example
arrays of {@code int[]} are
  * compared using the {@link java.util.Arrays#equals(int[], int[])} method.</p>
  *
+ * {@section Thread safety}
+ * The same {@code WeakValueHashMap} instance can be safely used by many threads without
synchronization on the part
+ * of the caller. But if a sequence of two or more method calls need to appear atomic from
other threads perspective,
+ * then the caller can synchronize on {@code this}.
+ *
  * @param <K> The class of key elements.
  * @param <V> The class of value elements.
  *
@@ -83,7 +87,6 @@ import java.util.Objects;
  * @see WeakHashSet
  * @see Cache
  */
-@ThreadSafe
 public class WeakValueHashMap<K,V> extends AbstractMap<K,V> {
     /**
      * Comparison mode for key objects. The standard mode is {@code EQUALS}, which means
that keys are compared

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultInternationalString.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultInternationalString.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultInternationalString.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultInternationalString.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -30,7 +30,6 @@ import java.util.logging.Level;
 import java.util.logging.LogRecord;
 import org.opengis.util.InternationalString;
 import org.apache.sis.util.Locales;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.logging.Logging;
 import org.apache.sis.util.resources.Errors;
@@ -49,6 +48,10 @@ import java.util.Objects;
  * This behavior is a compromise between making constructions easier, and being suitable
for
  * use in immutable objects.
  *
+ * {@section Thread safety}
+ * Instances of {@code DefaultInternationalString} are thread-safe. While those instances
are not strictly immutable,
+ * SIS typically references them as if they were immutable because of their <cite>add-only</cite>
behavior.
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.3 (derived from geotk-2.1)
  * @version 0.3
@@ -56,7 +59,6 @@ import java.util.Objects;
  *
  * @see Types#toInternationalString(Map, String)
  */
-@ThreadSafe
 public class DefaultInternationalString extends AbstractInternationalString implements Serializable
{
     /**
      * Serial number for inter-operability with different versions.

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/iso/DefaultNameFactory.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -28,7 +28,6 @@ import org.opengis.util.MemberName;
 import org.opengis.util.GenericName;
 import org.opengis.util.NameFactory;
 import org.opengis.util.InternationalString;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.resources.Errors;
 import org.apache.sis.util.NullArgumentException;
 import org.apache.sis.util.collection.WeakHashSet;
@@ -61,12 +60,16 @@ import static org.apache.sis.util.iso.De
  *   <li>{@link #parseGenericName(NameSpace, CharSequence)}</li>
  * </ul>
  *
+ * {@section Thread safety}
+ * The same {@code DefaultNameFactory} instance can be safely used by many threads without
synchronization
+ * on the part of the caller. Subclasses should make sure that any overridden methods remain
safe to call
+ * from multiple threads.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-2.1)
  * @version 0.3
  * @module
  */
-@ThreadSafe
 public class DefaultNameFactory extends AbstractFactory implements NameFactory {
     /**
      * Weak references to the name created by this factory.

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerFactory.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerFactory.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerFactory.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/LoggerFactory.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -17,7 +17,6 @@
 package org.apache.sis.util.logging;
 
 import java.util.logging.Logger;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.collection.WeakValueHashMap;
 
 
@@ -38,6 +37,10 @@ import org.apache.sis.util.collection.We
  * The {@link #getLogger(String)} method shall return some {@link Logger} subclass
  * (typically {@link LoggerAdapter}) which forwards directly all log methods to the other
framework.
  *
+ * {@section Thread safety}
+ * This base class is safe for multi-threads usage. Subclasses registered in {@code META-INF/services/}
+ * shall make sure that any overridden methods remain safe to call from multiple threads.
+ *
  * @param <L> The type of loggers used for the implementation backend.
  *            This is the type used by external frameworks like Log4J.
  *
@@ -49,7 +52,6 @@ import org.apache.sis.util.collection.We
  * @see Logging
  * @see LoggerAdapter
  */
-@ThreadSafe
 public abstract class LoggerFactory<L> {
     /**
      * The logger class. We ask for this information right at construction time in order
to

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/MonolineFormatter.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/MonolineFormatter.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/MonolineFormatter.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/MonolineFormatter.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -36,7 +36,6 @@ import org.apache.sis.io.LineAppender;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.CharSequences;
 import org.apache.sis.util.Configuration;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Debug;
 
 
@@ -99,6 +98,11 @@ import org.apache.sis.util.Debug;
  *     java.util.logging.ConsoleHandler.level = FINE
  * }
  *
+ * {@section Thread safety}
+ * The same {@code MonolineFormatter} instance can be safely used by many threads without
synchronization
+ * on the part of the caller. Subclasses should make sure that any overridden methods remain
safe to call
+ * from multiple threads.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-2.0)
  * @version 0.4
@@ -107,7 +111,6 @@ import org.apache.sis.util.Debug;
  * @see SimpleFormatter
  * @see Handler#setFormatter(Formatter)
  */
-@ThreadSafe
 public class MonolineFormatter extends Formatter {
     /** Do not format source class name.       */ private static final int NO_SOURCE    =
0;
     /** Format the source logger without base. */ private static final int LOGGER_SHORT =
1;

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListeners.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListeners.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListeners.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/logging/WarningListeners.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -22,7 +22,6 @@ import java.util.logging.Logger;
 import java.util.logging.LogRecord;
 import java.util.NoSuchElementException;
 import org.apache.sis.util.Localized;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Exceptions;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.resources.Errors;
@@ -42,6 +41,11 @@ import org.apache.sis.util.resources.Err
  *   <li>Otherwise the warning is logged to the logger returned by {@link #getLogger()}.</li>
  * </ul>
  *
+ * {@section Thread safety}
+ * The same {@code WarningListeners} instance can be safely used by many threads without
synchronization
+ * on the part of the caller. Subclasses should make sure that any overridden methods remain
safe to call
+ * from multiple threads.
+ *
  * @param <S> The type of the source of warnings.
  *
  * @author  Martin Desruisseaux (Geomatys)
@@ -52,7 +56,6 @@ import org.apache.sis.util.resources.Err
  * @see WarningListener
  * @see org.apache.sis.storage.DataStore#listeners
  */
-@ThreadSafe
 public class WarningListeners<S> implements Localized {
     /**
      * The declared source of warnings. This is not necessarily the real source,
@@ -166,8 +169,7 @@ public class WarningListeners<S> impleme
             trace = Thread.currentThread().getStackTrace();
             record = new LogRecord(Level.WARNING, message);
         }
-        for (int i=0; i<trace.length; i++) {
-            StackTraceElement e = trace[i];
+        for (final StackTraceElement e : trace) {
             if (isPublic(e)) {
                 record.setSourceClassName(e.getClassName());
                 record.setSourceMethodName(e.getMethodName());

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/resources/IndexedResourceBundle.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/resources/IndexedResourceBundle.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/resources/IndexedResourceBundle.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/util/resources/IndexedResourceBundle.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -33,7 +33,6 @@ import org.opengis.util.InternationalStr
 import org.apache.sis.util.Debug;
 import org.apache.sis.util.Classes;
 import org.apache.sis.util.Localized;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Exceptions;
 import org.apache.sis.util.CharSequences;
 import org.apache.sis.util.iso.Types;
@@ -60,12 +59,16 @@ import org.apache.sis.util.logging.Loggi
  *   <li>{@link Class} and {@link Throwable} instances are summarized.</li>
  * </ul>
  *
+ * {@section Thread safety}
+ * The same {@code IndexedResourceBundle} instance can be safely used by many threads without
synchronization
+ * on the part of the caller. Subclasses should make sure that any overridden methods remain
safe to call from
+ * multiple threads.
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.3 (derived from geotk-1.2)
  * @version 0.4
  * @module
  */
-@ThreadSafe
 public class IndexedResourceBundle extends ResourceBundle implements Localized {
     /**
      * Maximum string length for text inserted into another text. This parameter is used
by

Modified: sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/xml/MarshallerPool.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -25,7 +25,6 @@ import javax.xml.bind.JAXBContext;
 import javax.xml.bind.JAXBException;
 import javax.xml.bind.Marshaller;
 import javax.xml.bind.Unmarshaller;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.logging.Logging;
 import org.apache.sis.internal.system.DelayedExecutor;
 import org.apache.sis.internal.system.DelayedRunnable;
@@ -50,6 +49,11 @@ import org.apache.sis.util.ArgumentCheck
  * The (un)marshallers created by this class can optionally by configured with the SIS-specific
  * properties defined in the {@link XML} class, in addition to JAXB standard properties.
  *
+ * {@section Thread safety}
+ * The same {@code MarshallerPool} instance can be safely used by many threads without synchronization
+ * on the part of the caller. Subclasses should make sure that any overridden methods remain
safe to call
+ * from multiple threads.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3 (derived from geotk-3.00)
  * @version 0.3
@@ -58,7 +62,6 @@ import org.apache.sis.util.ArgumentCheck
  * @see XML
  * @see <a href="http://jaxb.java.net/guide/Performance_and_thread_safety.html">JAXB
Performance and thread-safety</a>
  */
-@ThreadSafe
 public class MarshallerPool {
     /**
      * The indentation string, fixed to 2 spaces instead of 4 because ISO/OGC XML are very
verbose.

Modified: sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStore.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -103,6 +103,8 @@ public class NetcdfStore extends DataSto
     /**
      * Returns a string representation of this NetCDF store for debugging purpose.
      * The content of the string returned by this method may change in any future SIS version.
+     *
+     * @return A string representation of this datastore for debugging purpose.
      */
     @Debug
     @Override

Modified: sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-netcdf/src/main/java/org/apache/sis/storage/netcdf/NetcdfStoreProvider.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -36,7 +36,6 @@ import org.apache.sis.storage.DataStoreE
 import org.apache.sis.storage.ProbeResult;
 import org.apache.sis.util.logging.WarningListeners;
 import org.apache.sis.util.logging.Logging;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.Version;
 
 
@@ -47,6 +46,10 @@ import org.apache.sis.util.Version;
  * on the classpath, then this class tries to instantiate a {@code NetcdfStore} backed by
  * the UCAR library.
  *
+ * {@section Thread safety}
+ * The same {@code NetcdfStoreProvider} instance can be safely used by many threads without
synchronization on
+ * the part of the caller. However the {@link NetcdfStore} instances created by this factory
are not thread-safe.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.3
  * @version 0.4
@@ -54,7 +57,6 @@ import org.apache.sis.util.Version;
  *
  * @see NetcdfStore
  */
-@ThreadSafe
 public class NetcdfStoreProvider extends DataStoreProvider {
     /**
      * The MIME type for NetCDF files.
@@ -199,7 +201,9 @@ public class NetcdfStoreProvider extends
     /**
      * Returns a {@link NetcdfStore} implementation associated with this provider.
      *
-     * @param storage Information about the storage (URL, stream, {@link ucar.nc2.NetcdfFile}
instance, <i>etc</i>).
+     * @param  storage Information about the storage (URL, stream, {@link ucar.nc2.NetcdfFile}
instance, <i>etc</i>).
+     * @return A data store implementation associated with this provider for the given storage.
+     * @throws DataStoreException If an error occurred while creating the data store instance.
      */
     @Override
     public DataStore open(final StorageConnector storage) throws DataStoreException {

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -16,8 +16,6 @@
  */
 package org.apache.sis.storage;
 
-import org.apache.sis.util.ThreadSafe;
-
 
 /**
  * Provides information about a specific {@link DataStore} implementation.
@@ -42,7 +40,7 @@ import org.apache.sis.util.ThreadSafe;
  * where each line is the fully qualified name of the implementation class.
  * See {@link java.util.ServiceLoader} for more general discussion about this lookup mechanism.
  *
- * {@section Thread safety policy}
+ * {@section Thread safety}
  * All {@code DataStoreProvider} implementations shall be thread-safe.
  * However the {@code DataStore} instances created by the providers do not need to be thread-safe.
  *
@@ -51,7 +49,6 @@ import org.apache.sis.util.ThreadSafe;
  * @version 0.4
  * @module
  */
-@ThreadSafe
 public abstract class DataStoreProvider {
     /**
      * Creates a new provider.
@@ -123,7 +120,6 @@ public abstract class DataStoreProvider 
      *
      * @param  storage Information about the storage (URL, stream, JDBC connection, <i>etc</i>).
      * @return A data store implementation associated with this provider for the given storage.
-     * @throws IllegalArgumentException If the set contains an invalid combination of options.
      * @throws DataStoreException If an error occurred while creating the data store instance.
      *
      * @see DataStores#open(Object)

Modified: sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java?rev=1553253&r1=1553252&r2=1553253&view=diff
==============================================================================
--- sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
[UTF-8] (original)
+++ sis/branches/JDK7/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreRegistry.java
[UTF-8] Tue Dec 24 06:35:36 2013
@@ -20,7 +20,6 @@ import java.util.List;
 import java.util.LinkedList;
 import java.util.Iterator;
 import java.util.ServiceLoader;
-import org.apache.sis.util.ThreadSafe;
 import org.apache.sis.util.ArgumentChecks;
 import org.apache.sis.util.resources.Errors;
 
@@ -33,12 +32,15 @@ import org.apache.sis.util.resources.Err
  * {@note This class is package-private for now in order to get more experience about what
could be a good API.
  *        This class may become public in a future SIS version.}
  *
+ * {@section Thread safety}
+ * The same {@code DataStoreRegistry} instance can be safely used by many threads without
synchronization
+ * on the part of the caller.
+ *
  * @author  Martin Desruisseaux (Geomatys)
  * @since   0.4
  * @version 0.4
  * @module
  */
-@ThreadSafe
 final class DataStoreRegistry {
     /**
      * The loader to use for searching for {@link DataStoreProvider} implementations.



Mime
View raw message