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
