sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1578162 - /sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/
Date Sun, 16 Mar 2014 21:15:57 GMT
Author: desruisseaux
Date: Sun Mar 16 21:15:56 2014
New Revision: 1578162

URL: http://svn.apache.org/r1578162
Log:
Javadoc.

Modified:
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterBuilder.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterFormat.java
    sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/package-info.java

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java?rev=1578162&r1=1578161&r2=1578162&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptorGroup.java
[UTF-8] Sun Mar 16 21:15:56 2014
@@ -48,12 +48,12 @@ import static org.apache.sis.util.Utilit
  * to be shared by all users of that projection or process.
  *
  * {@section Instantiation}
- * Map projection or process <em>implementors</em> may use the {@link ParameterBuilder}
class for making
+ * Coordinate operation or process <em>implementors</em> may use the {@link ParameterBuilder}
class for making
  * their task easier.
  *
  * <div class="note"><b>Example:</b>
- * The following example creates a <cite>Mercator (variant A)</cite> projection
valid
- * from 80°S to 84°N on all the longitude range (±180°).
+ * The following example declares the parameters for a <cite>Mercator (variant A)</cite>
projection method
+ * valid from 80°S to 84°N on all the longitude range (±180°).
  *
  * {@preformat java
  *     public class Mercator {
@@ -76,14 +76,15 @@ import static org.apache.sis.util.Utilit
  *         }
  *     }
  * }
+ * </div>
  *
- * Users can simply reference the descriptor provided par projection or process providers
like below:
+ * {@section Usage}
+ * Users can simply reference the descriptor provided par a coordinate operation or process
providers like below:
  *
  * {@preformat java
  *     ParameterValueGroup parameters = Mercator.PARAMETERS.createValue();
  *     // See DefaultParameterValueGroup for examples on 'parameters' usage.
  * }
- * </div>
  *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @author  Johann Sorel (Geomatys)

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java?rev=1578162&r1=1578161&r2=1578162&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValue.java
[UTF-8] Sun Mar 16 21:15:56 2014
@@ -46,11 +46,14 @@ import java.nio.file.Path;
 
 
 /**
- * A single parameter value used by an operation method. Most CRS parameter values are numeric
and can be obtained
- * by the {@link #intValue()} or {@link #doubleValue()} methods. But other types of parameter
values are possible
- * and can be handled by the more generic {@link #getValue()} and {@link #setValue(Object)}
methods.
+ * A single parameter value used by an operation method. {@code ParameterValue} instances
are elements in
+ * a {@linkplain DefaultParameterValueGroup parameter value group}, in a way similar to {@code
Map.Entry}
+ * instances in a {@code java.util.Map}.
  *
- * <p>All {@code xxxValue()} methods in this class are convenience methods converting
the value from {@code Object}
+ * <p>In the context of coordinate operations, most parameter values are numeric and
can be obtained by the
+ * {@link #intValue()} or {@link #doubleValue()} methods. But other types of parameter values
are possible
+ * and can be handled by the more generic {@link #getValue()} and {@link #setValue(Object)}
methods.
+ * All {@code xxxValue()} methods in this class are convenience methods converting the value
from {@code Object}
  * to some commonly used types. Those types are specified in ISO 19111 as an union of attributes,
listed below with
  * the corresponding getter and setter methods:</p>
  *

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java?rev=1578162&r1=1578161&r2=1578162&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterValueGroup.java
[UTF-8] Sun Mar 16 21:15:56 2014
@@ -38,19 +38,30 @@ import java.util.Objects;
 
 
 /**
- * A group of related parameter values. {@code ParameterValueGroup} instances are typically
created by calls to
+ * A group of related parameter values. Parameter groups have some similarities with {@code
java.util.Map}:
+ *
+ * <ul>
+ *   <li>{@link #parameter(String)} is similar in purpose to {@link java.util.Map#get(Object)},
+ *       with an additional level of indirection in both the argument and the return value.</li>
+ *   <li>{@link #values()} is similar in purpose to {@link java.util.Map#entrySet()},
+ *       with {@code ParameterValue} playing a role similar to {@code Map.Entry}.</li>
+ * </ul>
+ *
+ * {@section Instantiation and validity constraints}
+ * {@code ParameterValueGroup} instances are typically created by calls to
  * <code>descriptor.{@linkplain DefaultParameterDescriptorGroup#createValue() createValue()}</code>
on a descriptor
- * supplied by a map projection or process provider. New instances are initialized with a
{@linkplain #values() list
- * of values} containing all mandatory parameters, and no optional parameter. The values
list is modifiable, but all
- * operations will first ensure that the modification would not violate the cardinality constraints
(i.e. the minimum
+ * supplied by a coordinate operation or process provider. New instances are initialized
with a {@linkplain #values()
+ * list of values} containing all mandatory parameters, and no optional parameter. The values
list is modifiable, but
+ * all methods will first ensure that the modification would not violate the cardinality
constraints (i.e. the minimum
  * and maximum occurrences of that parameter allowed by the descriptor). If a cardinality
constraint is violated, then
  * an {@link InvalidParameterCardinalityException} will be thrown.
  *
- * <p>After a new {@code ParameterValueGroup} instance has been created, the parameter
values can be set by chaining
+ * {@section Setting the parameter values}
+ * After a new {@code ParameterValueGroup} instance has been created, the parameter values
can be set by chaining
  * calls to {@link #parameter(String)} with one of the {@code setValue(…)} methods defined
in the returned object
  * (see the {@linkplain DefaultParameterValue table of setter methods}). The {@code parameter(String)}
method can
  * be invoked regardless of whether the parameter is mandatory or optional: if the parameter
was optional and not
- * yet present in this group, it will be created.</p>
+ * yet present in this group, it will be created.
  *
  * <div class="note"><b>Example:</b>
  * Assuming the descriptor defined in the {@link DefaultParameterDescriptorGroup} example,

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterBuilder.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterBuilder.java?rev=1578162&r1=1578161&r2=1578162&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterBuilder.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterBuilder.java
[UTF-8] Sun Mar 16 21:15:56 2014
@@ -29,11 +29,10 @@ import static org.apache.sis.util.Argume
 
 
 /**
- * Provides convenience methods for easier {@code ParameterDescriptor} instantiations.
- * This builder can be helpful for map projection <em>providers</em>, or for
implementation of
- * any process that use parameters. Map projection or process <em>users</em>
do not need this
- * builder since they can invoke {@link ParameterDescriptor#createValue()} on the descriptor
- * provided by the implementor.
+ * Helper class for {@linkplain DefaultParameterDescriptor parameter descriptor} instantiations.
+ * This builder can be helpful to operation or process <em>providers</em> (e.g.
map projection
+ * implementors). Operation <em>users</em> do not need this builder since they
can invoke
+ * {@link ParameterDescriptor#createValue()} on the descriptor provided by the implementor.
  *
  * {@section Identification properties}
  * Each parameter must have a name, which can be specified by any of the {@code addName(…)}
methods.

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterFormat.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterFormat.java?rev=1578162&r1=1578161&r2=1578162&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterFormat.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/ParameterFormat.java
[UTF-8] Sun Mar 16 21:15:56 2014
@@ -122,7 +122,7 @@ public class ParameterFormat extends Tab
     private static final String SEPARATOR = " │ ";
 
     /**
-     * The amount of information to put in the table to be formatted by {@link ParameterFormat}.
+     * The amount of information to include in the table formatted by {@link ParameterFormat}.
      * The content level controls whether the formatter should write all names and aliases
      * (at the cost of multi-line rows), or to pickup one name per parameter for a more compact
table.
      *

Modified: sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/package-info.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/package-info.java?rev=1578162&r1=1578161&r2=1578162&view=diff
==============================================================================
--- sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/package-info.java
[UTF-8] (original)
+++ sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/package-info.java
[UTF-8] Sun Mar 16 21:15:56 2014
@@ -21,16 +21,38 @@
  * The remaining discussion on this page is specific to the SIS implementation.
  *
  * <p>Parameters are organized in <cite>groups</cite>. A group may be for
example the set of all parameters needed
- * for the definition of a <cite>Mercator projection</cite>. When using this
{@code org.apache.sis.parameter} package,
- * the starting point is usually to obtain a {@linkplain org.apache.sis.parameter.DefaultParameterDescriptorGroup
- * parameter group descriptor} for the operation of interest. Those groups are provided by
the operation implementors,
- * so users do not need to create their own.</p>
- *
- * <p>Each parameter have a name and a cardinality (i.e. the parameter may be mandatory
or optional). Parameter values
- * may also be constrained to a {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getValueDomain()
domain},
- * have a {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getDefaultValue()
default value} and a
- * {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getUnit() unit of measurement}.
- * All those information are provided by the descriptors.</p>
+ * for the definition of a <cite>Mercator projection</cite>.
+ * Parameter groups have some similarity with {@code java.util.Map} where:</p>
+ *
+ * <ul>
+ *   <li>Keys are (indirectly) parameter
+ *       {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getName() names}.</li>
+ *   <li>Values are typically (but not restricted to) {@code int}, {@code int[]}, {@code
double}, {@code double[]},
+ *       {@code boolean}, {@link java.lang.String}, {@link java.net.URI} or
+ *       {@link org.apache.sis.metadata.iso.citation.DefaultCitation Citation}
+ *       (note: there is a level of indirection through those values).</li>
+ *   <li>Each parameter (equivalent to map entry) defines its own set of constraints
on acceptable values:
+ *     <ul>
+ *       <li>The base {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getValueClass()
value class}.</li>
+ *       <li>Optionally the {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getValueDomain()
+ *           value domain} (i.e. minimum and maximum valid values) or an enumeration of
+ *           {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getValidValues()
valid values}.</li>
+ *     </ul>
+ *   </li>
+ *   <li>Each entry can have a
+ *       {@linkplain org.apache.sis.parameter.DefaultParameterDescriptor#getDefaultValue()
default value} and an
+ *       {@linkplain org.apache.sis.parameter.DefaultParameterValue#getUnit() unit of measurement}.</li>
+ *   <li>Some parameters are mandatory ({@link org.apache.sis.parameter.DefaultParameterDescriptor#getMinimumOccurs()
+ *       minimum occurrence} = 1), meaning that they can not be removed from the group.
+ *       They can be left to their default value however.</li>
+ *   <li>Group may contain other groups.</li>
+ * </ul>
+ *
+ * {@section Usage}
+ * When using this {@code org.apache.sis.parameter} package, the starting point is usually
to obtain a
+ * {@linkplain org.apache.sis.parameter.DefaultParameterDescriptorGroup parameter group descriptor}
for
+ * the operation of interest. Those groups are provided by the operation implementors, so
users do not
+ * need to create their own.</p>
  *
  * <p>Given a group descriptor, users can obtain a new instance of parameter values
by a call to the
  * {@link org.apache.sis.parameter.DefaultParameterDescriptorGroup#createValue() createValue()}
method.
@@ -49,6 +71,11 @@
  * }
  * </div>
  *
+ * Calls to {@code parameter(…)} throw a {@link org.opengis.parameter.InvalidParameterNameException}
+ * if the given name is unknown to the group.
+ * Calls to {@code setValue(…)} throw a {@link org.opengis.parameter.InvalidParameterValueException}
+ * if the given value is not assignable to the expected class or is not inside the value
domain.
+ *
  * @author  Martin Desruisseaux (IRD, Geomatys)
  * @since   0.4 (derived from geotk-2.0)
  * @version 0.4



Mime
View raw message