sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1404560 - in /sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis: math/FunctionProperty.java util/Arrays.java util/ObjectConverter.java util/UnconvertibleObjectException.java
Date Thu, 01 Nov 2012 12:30:50 GMT
Author: desruisseaux
Date: Thu Nov  1 12:30:50 2012
New Revision: 1404560

URL: http://svn.apache.org/viewvc?rev=1404560&view=rev
Log:
Ported the ObjectConverter interface, which will needed for metadata.
This interface will also allow us to refactor DerivedSet and DerivedMap
in a way which will hide them for public API, which will help to reduce
the API size.

Added:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
  (with props)
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java 
 (with props)
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java
  (with props)
Modified:
    sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java

Added: 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=1404560&view=auto
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
(added)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
Thu Nov  1 12:30:50 2012
@@ -0,0 +1,123 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.math;
+
+
+/**
+ * The manners in which the inputs of a function are mapped to the outputs.
+ * The function doesn't need to be mathematical. For example this enumeration
+ * 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>
+ *
+ * {@preformat java
+ *     private static final Set<FunctionProperty> BIJECTIVE = EnumSet.of(INJECTIVE,
SURJECTIVE);
+ *
+ *     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>
+ * <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,
+ *       and potentially more elements (the <cite>codomain</cite>). For example
the set of output
+ *       values of the {@link Integer#toString()} function is included in a larger set, which
is
+ *       the set of all possible {@link String} values. In this Javadoc, <var>T</var>
stands for
+ *       the later set.</li>
+ * </ul>
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.3
+ * @version 0.3
+ * @module
+ */
+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.
+     *
+     * @see org.apache.sis.util.ObjectConverter#inverse()
+     */
+    INVERTIBLE,
+
+    /**
+     * A function is <cite>injective</cite> if each value of <var>T</var>
is either unrelated
+     * to <var>S</var>, or is the output of exactly one value of <var>S</var>.
+     *
+     * <blockquote><font size="-1"><b>Example:</b>
+     * A {@code ObjectConverter} doing conversions from {@code Integer} to {@code String}
is an
+     * injective function, because no pair of integers can produce the same string.
+     * </font></blockquote>
+     *
+     * A function which is both injective and {@linkplain #SURJECTIVE surjective} is a
+     * <cite>bijective</cite> function. In such functions, there is a one-to-one
relationship
+     * between all input and output values.
+     */
+    INJECTIVE,
+
+    /**
+     * A function is <cite>surjective</cite> if any value of <var>T</var>
can be created
+     * from one or many values of <var>S</var>.
+     *
+     * <blockquote><font size="-1"><b>Example:</b>
+     * A {@code ObjectConverter} doing conversions from {@link String} to {@link Integer}
is a
+     * surjective function, since there is always at least one string for each integer value.
+     * Note that such function can not be {@linkplain #INJECTIVE injective} since many different
+     * strings can represent the same integer value.
+     * </font></blockquote>
+     *
+     * A function which is both {@linkplain #INJECTIVE injective} and surjective is a
+     * <cite>bijective</cite> function. In such functions, there is a one-to-one
relationship
+     * between all input and output values.
+     */
+    SURJECTIVE,
+
+    /**
+     * A function preserves order if any sequence of increasing <var>S</var>
values is mapped
+     * to a sequence of increasing <var>T</var> values. This enumeration constant
can be used
+     * only with {@link Comparable} types or primitive types having a comparable wrapper.
+     *
+     * <p>Strictly ordered input values are not necessarily mapped to strictly ordered
output values.
+     * Strictness is preserved only if the function is also {@linkplain #INJECTIVE injective}.</p>
+     *
+     * <p>A function may be both order preserving and {@linkplain #ORDER_REVERSING
order reversing}
+     * if all input values are mapped to a constant output value.</p>
+     */
+    ORDER_PRESERVING,
+
+    /**
+     * A function reverses order if any sequence of increasing <var>S</var> values
is mapped
+     * to a sequence of decreasing <var>T</var> values. This enumeration constant
can be used
+     * only with {@link Comparable} types or primitive types having a comparable wrapper.
+     *
+     * <p>Strictly ordered input values are not necessarily mapped to strictly ordered
output values.
+     * Strictness is preserved only if the function is also {@linkplain #INJECTIVE injective}.</p>
+     *
+     * <p>A function may be both {@linkplain #ORDER_PRESERVING order preserving} and
order reversing
+     * if all input values are mapped to a constant output value.</p>
+     */
+    ORDER_REVERSING
+}

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/math/FunctionProperty.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Modified: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java?rev=1404560&r1=1404559&r2=1404560&view=diff
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java (original)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/Arrays.java Thu Nov  1
12:30:50 2012
@@ -1433,7 +1433,7 @@ public final class Arrays extends Static
      *                    elements are not allowed), or {@code false} otherwise.
      * @return {@code true} if all elements in the given array are sorted in increasing order.
      */
-    public static <E> boolean isSorted(final E[] array, final Comparator<E> comparator,
final boolean strict) {
+    public static <E> boolean isSorted(final E[] array, final Comparator<? super
E> comparator, final boolean strict) {
         for (int i=1; i<array.length; i++) {
             final int c = comparator.compare(array[i], array[i-1]);
             if (strict ? c <= 0 : c < 0) {

Added: 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=1404560&view=auto
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java (added)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java Thu
Nov  1 12:30:50 2012
@@ -0,0 +1,107 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.util;
+
+import java.util.Set;
+import org.apache.sis.math.FunctionProperty;
+
+
+/**
+ * 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.
+ *
+ * <p>The characteristics of the <var>S</var> to <var>T</var>
mapping are given by
+ * the {@link #properties()} enumeration set.</p>
+ *
+ * @param <S> The type of objects to convert.
+ * @param <T> The type of converted objects.
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.3
+ * @version 0.3
+ * @module
+ */
+public interface ObjectConverter<S,T> {
+    /**
+     * Returns the manner in which source values (<var>S</var>) are mapped to
target values
+     * (<var>T</var>). Some possible function properties are:
+     *
+     * <ul>
+     *   <li>{@linkplain FunctionProperty#INJECTIVE Injective} if no pair of <var>S</var>
can produce
+     *       the same <var>T</var> value (e.g.: conversions from {@link Integer}
to {@code String}).</li>
+     *   <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#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>
+     *   <li>{@linkplain FunctionProperty#ORDER_REVERSING Order reversing} if any sequence
of
+     *       increasing <var>S</var> values (in the sense of {@link Comparable})
is mapped to
+     *       a sequence of decreasing <var>T</var> values.</li>
+     * </ul>
+     *
+     * @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.
+     *
+     * @return The type of source values.
+     */
+    Class<? super S> getSourceClass();
+
+    /**
+     * Returns the base type of converted values.
+     *
+     * @return The base type of target values.
+     */
+    Class<? extends 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.
+     *
+     * @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.
+     */
+    T convert(S object) throws UnconvertibleObjectException;
+
+    /**
+     * Returns a converter capable to convert instances of <var>T</var> back
to instances of
+     * <var>S</var>. Before to invoke this method, callers can verify if this
converter is
+     * invertible as below:
+     *
+     * {@preformat java
+     *     if (converter.properties().contains(FunctionProperty.INVERTIBLE)) {
+     *         // Call to converter.inverse() is allowed here.
+     *     }
+     * }
+     *
+     * @return A converter for converting instances of <var>T</var> back to instances
of <var>S</var>.
+     * @throws UnsupportedOperationException If this converter is not invertible.
+     *
+     * @see FunctionProperty#INVERTIBLE
+     */
+    ObjectConverter<T,S> inverse() throws UnsupportedOperationException;
+}

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/ObjectConverter.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java?rev=1404560&view=auto
==============================================================================
--- sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java
(added)
+++ sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java
Thu Nov  1 12:30:50 2012
@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.sis.util;
+
+
+/**
+ * Thrown when an object can not be {@linkplain ObjectConverter#convert converted}
+ * from the <cite>source</cite> type to the <cite>target</cite> type.
+ *
+ * <p>Some converters may attempt many strategies before to give up, resulting in more
than
+ * one exception being caught. In such case, all the failed attempts will be reported as
+ * {@linkplain #getSuppressed() suppressed exceptions} and the {@linkplain #getCause() cause}
+ * will be an arbitrary item of this list.</p>
+ *
+ * @author  Martin Desruisseaux (Geomatys)
+ * @since   0.3 (derived from geotk-3.00)
+ * @version 0.3
+ * @module
+ */
+public class UnconvertibleObjectException extends IllegalArgumentException {
+    /**
+     * For cross-version compatibility.
+     */
+    private static final long serialVersionUID = 3434744387048059588L;
+
+    /**
+     * Constructs a new exception with no message.
+     */
+    public UnconvertibleObjectException() {
+        super();
+    }
+
+    /**
+     * Constructs a new exception with the specified detail message.
+     *
+     * @param message The detail message.
+     */
+    public UnconvertibleObjectException(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new exception with the specified detail message and cause.
+     *
+     * @param message The detail message.
+     * @param cause The cause.
+     */
+    public UnconvertibleObjectException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Constructs a new exception with the specified cause.
+     *
+     * @param cause The cause.
+     */
+    public UnconvertibleObjectException(Throwable cause) {
+        super(cause);
+    }
+}

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: sis/branches/JDK7/sis-utility/src/main/java/org/apache/sis/util/UnconvertibleObjectException.java
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message