sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1404671 - in /sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis: internal/util/X364.java math/FunctionProperty.java util/ObjectConverter.java util/collection/DerivedMap.java util/collection/DerivedSet.java
Date Thu, 01 Nov 2012 16:49:45 GMT
Author: desruisseaux
Date: Thu Nov  1 16:49:45 2012
New Revision: 1404671

URL: http://svn.apache.org/viewvc?rev=1404671&view=rev
Log:
Javadoc clarification.

Modified:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/internal/util/X364.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedMap.java
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedSet.java

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/internal/util/X364.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/internal/util/X364.java?rev=1404671&r1=1404670&r2=1404671&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/internal/util/X364.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/internal/util/X364.java Thu
Nov  1 16:49:45 2012
@@ -83,7 +83,7 @@ public enum X364 {
     /**
      * The X3.64 escape sequence, built when first needed.
      */
-    private transient volatile String sequence;
+    private transient String sequence;
 
     /**
      * Foreground or background flavors of this enum.
@@ -136,11 +136,14 @@ public enum X364 {
      * @return The X3.64 escape sequence.
      */
     public String sequence() {
-        String s = sequence;
-        if (s == null) {
-            sequence = s = START + code + END;
+        if (sequence == null) {
+            sequence = (START + code + END).intern();
+            // We used the string.intern() method in order to avoid worrying about memory
barrier
+            // (synchronization or volatile variable) since intern() does its own synchronization.
+            // The String will live for the whole library lifetime anyway, and if there is
other
+            // X3.64 libraries on the JVM we may share the strings with them as a side effect.
         }
-        return s;
+        return sequence;
     }
 
     /**

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java?rev=1404671&r1=1404670&r2=1404671&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
(original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
Thu Nov  1 16:49:45 2012
@@ -26,23 +26,23 @@ import java.util.EnumSet;
  * can be used with {@link org.apache.sis.util.ObjectConverter}.
  *
  * <p>Any given function can have zero, one or more properties from this enumeration.
- * Some properties not included in this enumeration can be tested by a combination of
- * other properties. For example in order to test if a function is <cite>bijective</cite>
- * (i.e. if there is a one-to-one relationship between all input and output values),
- * one can use:</p>
+ * Some properties not included in this enumeration can be expressed by a combination of
+ * other properties:</p>
  *
- * {@preformat java
- *     private static final Set<FunctionProperty> BIJECTIVE = EnumSet.of(INJECTIVE,
SURJECTIVE);
+ * <table class="sis">
+ *   <tr><th>Property</th> <th>How to build</th></tr>
+ *   <tr><td>{@linkplain #isBijective(Set) Bijective}</td>
+ *       <td><code>EnumSet.of({@linkplain #INJECTIVE}, {@linkplain #SURJECTIVE})</code></td>
+ *   <tr><td>{@linkplain #isMonotonic(Set) Monotonic}</td>
+ *       <td><code>EnumSet.of({@linkplain #INJECTIVE})</code>
+ *        or <code>EnumSet.of({@linkplain #SURJECTIVE})</code></td>
+ *   <tr><td>Strictly increasing</td>
+ *       <td><code>EnumSet.of({@linkplain #ORDER_PRESERVING}, {@linkplain #INJECTIVE})</code></td>
+ *   <tr><td>Strictly decreasing</td>
+ *       <td><code>EnumSet.of({@linkplain #ORDER_REVERSING}, {@linkplain #INJECTIVE})</code></td>
+ * </table>
  *
- *     public void doSomeStuff(Set<FunctionProperty> properties) {
- *         if (properties.containsAll(BIJECTIVE)) {
- *             // At this point, we have determined that a function
- *             // having the given properties is bijective.
- *         }
- *     }
- * }
- *
- * <p>The Javadoc in this class uses the following terms:</p>
+ * The Javadoc in this class uses the following terms:
  * <ul>
  *   <li><var>S</var> (as in <cite>source</cite>) is the set
of all possible input values (the <cite>domain</cite>).
  *   <li><var>T</var> (as in <cite>target</cite>) is a set
containing all possible output values,
@@ -56,12 +56,20 @@ import java.util.EnumSet;
  * @since   0.3
  * @version 0.3
  * @module
+ *
+ * @see org.apache.sis.util.ObjectConverter#properties()
  */
 public enum FunctionProperty {
     /**
      * A function is <cite>invertible</cite> if it can provide an other function
mapping
      * <var>T</var> values to <var>S</var> values.
      *
+     * <p>While other values defined in this enumeration are more about the mathematical
aspects
+     * of functions, this particular value is more about the programmatical aspect. A function
+     * may be conceptually invertible (all {@linkplain #isBijective(Set) bijective} functions
+     * should be), but the inverse operation may not be implemented. In such case, the function
+     * properties shall not include this {@code INVERTIBLE} value.</p>
+     *
      * @see org.apache.sis.util.ObjectConverter#inverse()
      */
     INVERTIBLE,
@@ -145,6 +153,7 @@ public enum FunctionProperty {
 
     /**
      * Returns {@code true} if a function having the given set of properties is <cite>bijective</cite>.
+     * Bijective functions have a one-to-one relationship between all input and output values.
      * This convenience method tests if the given set contains <em>all</em> following
properties:
      *
      * <ul>
@@ -161,7 +170,8 @@ public enum FunctionProperty {
 
     /**
      * Returns {@code true} if a function having the given set of properties is <cite>monotonic</cite>.
-     * This convenience method tests if the given set contains <em>at least one</em>
following properties:
+     * This convenience method tests if the given set contains <em>at least one</em>
of the following
+     * properties:
      *
      * <ul>
      *   <li>{@link #ORDER_PRESERVING}</li>

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java?rev=1404671&r1=1404670&r2=1404671&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java Thu
Nov  1 16:49:45 2012
@@ -23,10 +23,28 @@ import org.apache.sis.math.FunctionPrope
 /**
  * A function which converts instances of <var>source</var> type to instances
of <var>target</var> type.
  * The source and target types may be the same, in which case the {@code ObjectConverter}
actually converts
- * the values.
+ * the values rather than the type.
  *
- * <p>The characteristics of the <var>S</var> to <var>T</var>
mapping are given by
- * the {@link #properties()} enumeration set.</p>
+ * <p>The main method of this interface is {@link #convert(Object)}, which receive
an object of type
+ * <var>S</var> and returns an object of type <var>T</var>. Some
characteristics about the <var>S</var>
+ * to <var>T</var> mapping are given by the {@link #properties()} enumeration,
together with the
+ * {@link #getSourceClass()} and {@link #getTargetClass()} methods.</p>
+ *
+ * <p>The <cite>domain</cite> of this function is the set of all values
of type <var>S</var> for
+ * which the {@link #convert(Object)} method does not throw {@link UnconvertibleObjectException}.
+ * Note that values for which {@code convert(S)} returns {@code null} are considered as part
of
+ * the domain, even if the {@code null} target value stands for unconvertible source values.</p>
+ *
+ * <p>The above definition affects the function {@linkplain #properties() properties}
+ * that this converter can declare:</p>
+ *
+ * <ul>
+ *   <li>IF {@code convert(S)} returns {@code null} for unconvertible objects, then
this {@code ObjectConverter}
+ *       can not declare {@link FunctionProperty#INJECTIVE} in its set of {@linkplain #properties()
properties},
+ *       because more than one source value can produce the same target value (namely {@code
null}).</li>
+ *   <li>If {@code convert(S)} throws an exception for unconvertible objects, then
this {@code ObjectConverter}
+ *       can be declared as an injective function if the other values meet the criteria.
+ * </ul>
  *
  * @param <S> The type of objects to convert.
  * @param <T> The type of converted objects.
@@ -47,8 +65,8 @@ public interface ObjectConverter<S,T> {
      *   <li>{@linkplain FunctionProperty#SURJECTIVE Surjective} if every values of
<var>T</var> can be
      *       created from one or many values of <var>S</var> (e.g.: conversions
from {@link String} to
      *       {@link Integer}).</li>
-     *   <li>Bijective if there is a one-to-one relationship between the <var>S</var>
and <var>T</var>
-     *       values.</li>
+     *   <li>{@linkplain FunctionProperty#isBijective Bijective} if there is a one-to-one
+     *       relationship between the <var>S</var> and <var>T</var>
values.</li>
      *   <li>{@linkplain FunctionProperty#ORDER_PRESERVING Order preserving} if any
sequence of
      *       increasing <var>S</var> values (in the sense of {@link Comparable})
is mapped to a
      *       sequence of increasing <var>T</var> values.</li>
@@ -57,33 +75,38 @@ public interface ObjectConverter<S,T> {
      *       a sequence of decreasing <var>T</var> values.</li>
      * </ul>
      *
+     * Note that if the {@link #convert(Object)} method returns {@code null} for any non-convertible
+     * source value, then this properties set can not contain the {@link FunctionProperty#INJECTIVE}
+     * value. See class javadoc for more discussion.
+     *
      * @return The manners in which source values are mapped to target values.
      *         May be an empty set, but never null.
      */
     Set<FunctionProperty> properties();
 
     /**
-     * Returns the type of source values.
+     * Returns the type of objects to convert.
      *
-     * @return The type of source values.
+     * @return The type of objects to convert.
      */
-    Class<? super S> getSourceClass();
+    Class<S> getSourceClass();
 
     /**
-     * Returns the base type of converted values.
+     * Returns the type of converted objects.
      *
-     * @return The base type of target values.
+     * @return The type of converted objects.
      */
-    Class<? extends T> getTargetClass();
+    Class<T> getTargetClass();
 
     /**
      * Converts the given object from the source type <var>S</var> to the target
type <var>T</var>.
      * If the given object can not be converted, then this method may either returns {@code
null} or
-     * throws an exception, depending on the implementation.
+     * throws an exception, at implementation choice. Note that this choice may affect the
set of
+     * function {@linkplain #properties() properties} - see the class Javadoc for more discussion.
      *
      * @param  object The object to convert, or {@code null}.
      * @return The converted object, or {@code null}.
-     * @throws UnconvertibleObjectException If the given object can not be converted.
+     * @throws UnconvertibleObjectException If the given object is not an element of the
function domain.
      */
     T convert(S object) throws UnconvertibleObjectException;
 

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedMap.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedMap.java?rev=1404671&r1=1404670&r2=1404671&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedMap.java
(original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedMap.java
Thu Nov  1 16:49:45 2012
@@ -203,19 +203,19 @@ class DerivedMap<BK,BV,K,V> extends Abst
 
         @Override
         public final V get(final Object key) {
-            final Class<? extends K> type = keyConverter.getTargetClass();
+            final Class<K> type = keyConverter.getTargetClass();
             return type.isInstance(key) ? valueConverter.convert(base.get(keyInverse.convert(type.cast(key))))
: null;
         }
 
         @Override
         public final V remove(final Object key) throws UnsupportedOperationException {
-            final Class<? extends K> type = keyConverter.getTargetClass();
+            final Class<K> type = keyConverter.getTargetClass();
             return type.isInstance(key) ? valueConverter.convert(base.remove(keyInverse.convert(type.cast(key))))
: null;
         }
 
         @Override
         public final boolean containsKey(final Object key) {
-            final Class<? extends K> type = keyConverter.getTargetClass();
+            final Class<K> type = keyConverter.getTargetClass();
             return type.isInstance(key) && base.containsKey(keyInverse.convert(type.cast(key)));
         }
     }
@@ -241,7 +241,7 @@ class DerivedMap<BK,BV,K,V> extends Abst
 
         @Override
         public boolean containsValue(final Object value) {
-            final Class<? extends V> type = valueConverter.getTargetClass();
+            final Class<V> type = valueConverter.getTargetClass();
             return type.isInstance(value) && base.containsValue(valueInverse.convert(type.cast(value)));
         }
     }
@@ -270,7 +270,7 @@ class DerivedMap<BK,BV,K,V> extends Abst
 
         @Override
         public boolean containsValue(final Object value) {
-            final Class<? extends V> type = valueConverter.getTargetClass();
+            final Class<V> type = valueConverter.getTargetClass();
             return type.isInstance(value) && base.containsValue(valueInverse.convert(type.cast(value)));
         }
 
@@ -331,8 +331,9 @@ class DerivedMap<BK,BV,K,V> extends Abst
      * Defined because the interface requires so but not used.
      */
     @Override
-    public final Class<? super Entry<BK,BV>> getSourceClass() {
-        return Entry.class;
+    @SuppressWarnings({"unchecked","rawtypes"})
+    public final Class<Entry<BK,BV>> getSourceClass() {
+        return (Class) Entry.class;
     }
 
     /**
@@ -341,7 +342,7 @@ class DerivedMap<BK,BV,K,V> extends Abst
      */
     @Override
     @SuppressWarnings({"unchecked","rawtypes"})
-    public final Class<? extends Entry<K,V>> getTargetClass() {
+    public final Class<Entry<K,V>> getTargetClass() {
         return (Class) Entry.class;
     }
 

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedSet.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedSet.java?rev=1404671&r1=1404670&r2=1404671&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedSet.java
(original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/collection/DerivedSet.java
Thu Nov  1 16:49:45 2012
@@ -110,7 +110,7 @@ class DerivedSet<B,E> extends AbstractSe
      * Returns the derived element type.
      */
     @Override
-    public final Class<? extends E> getElementType() {
+    public final Class<E> getElementType() {
         return converter.getTargetClass();
     }
 



Mime
View raw message