Author: desruisseaux
Date: Mon Mar 3 23:23:14 2014
New Revision: 1573804
URL: http://svn.apache.org/r1573804
Log:
Added a ParameterDescriptor builder in the hope to make the task easier.
Provided an example in javadoc for "Mercator (variant A)" projection.
Added:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java
(with props)
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java
(with props)
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/MeasurementRange.java
Modified:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java?rev=1573804&r1=1573803&r2=1573804&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DefaultParameterDescriptor.java
[UTF-8] Mon Mar 3 23:23:14 2014
@@ -291,7 +291,7 @@ public class DefaultParameterDescriptor<
}
/**
- * The minimum number of times that values for this parameter group or
parameter are required.
+ * The minimum number of times that values for this parameter are required.
* A value of 0 means an optional parameter and a value of 1 means a
mandatory parameter.
*
* @see #getMaximumOccurs()
@@ -302,7 +302,7 @@ public class DefaultParameterDescriptor<
}
/**
- * The maximum number of times that values for this parameter group or
parameter can be included.
+ * The maximum number of times that values for this parameter can be
included.
* For a {@code ParameterDescriptor}, the value is always 1.
*
* @return The maximum occurrence.
Added:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java?rev=1573804&view=auto
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java
(added)
+++
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java
[UTF-8] Mon Mar 3 23:23:14 2014
@@ -0,0 +1,264 @@
+/*
+ * 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.parameter;
+
+import java.util.Map;
+import java.util.HashMap;
+import javax.measure.unit.Unit;
+import org.opengis.metadata.citation.Citation;
+import org.opengis.parameter.ParameterDescriptor;
+import org.opengis.referencing.ReferenceIdentifier;
+import org.apache.sis.internal.util.Numerics;
+import org.apache.sis.measure.MeasurementRange;
+import org.apache.sis.measure.NumberRange;
+import org.apache.sis.measure.Range;
+
+
+/**
+ * Builds instances of {@link DefaultParameterDescriptor}.
+ * This convenience class aims to facilitate the creation of group of
parameter descriptors.
+ *
+ * {@section Example}
+ * The following example creates the parameters for "<cite>Mercator (variant
A)</cite>" projection method
+ * (EPSG:9804). All parameter names will be in the "EPSG" namespace. The
default values define a projection
+ * centered on (0°,0°) with no scale factor and no false easting/northing.
+ *
+ * {@preformat java
+ * DescriptorBuilder builder = new DescriptorBuilder();
+ * builder.codespace(Citations.OGP, "EPSG").mandatory();
+ * ParameterDescriptor<Double>[] parameters = {
+ * builder.name("Latitude of natural origin") .create( -80, +80, 0,
NonSI.DEGREE_ANGLE),
+ * builder.name("Longitude of natural origin") .create(-180, +180, 0,
NonSI.DEGREE_ANGLE),
+ * builder.name("Scale factor at natural origin")
.createStrictlyPositive(1, Unit.ONE),
+ * builder.name("False easting") .createUnbounded(0,
SI.METRE),
+ * builder.name("False northing") .createUnbounded(0,
SI.METRE)
+ * };
+ * }
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @since 0.4
+ * @version 0.4
+ * @module
+ */
+public class DescriptorBuilder {
+ /**
+ * The name, alias, identifiers and remarks properties.
+ */
+ private final Map<String,Object> properties;
+
+ /**
+ * {@code true} if the parameter is mandatory, or {@code false} if
optional.
+ */
+ private boolean required;
+
+ /**
+ * Creates a new builder.
+ */
+ public DescriptorBuilder() {
+ properties = new HashMap<>(4);
+ }
+
+ /**
+ * Sets the name to the given identifier. If an authority, {@linkplain
#codespace(Citation, String) code space}
+ * or {@linkplain #version(String) version} have been specified to this
builder, they will be ignored since the
+ * given identifier is expected to contain all those information.
+ *
+ * @param name The parameter name as an identifier.
+ * @return {@code this}, for method call chaining.
+ */
+ public DescriptorBuilder name(final ReferenceIdentifier name) {
+ properties.put(ParameterDescriptor.NAME_KEY, name);
+ return this;
+ }
+
+ /**
+ * Sets the name to the given string. The given string will be combined
with the authority,
+ * {@linkplain #codespace(Citation, String) code space} and {@linkplain
#version(String) version}
+ * information for creating a {@link ReferenceIdentifier}.
+ *
+ * @param code The parameter name as a string.
+ * @return {@code this}, for method call chaining.
+ */
+ public DescriptorBuilder name(final String code) {
+ properties.put(ParameterDescriptor.NAME_KEY, code);
+ return this;
+ }
+
+ /**
+ * Sets the authority and code space. This method is typically invoked
only once, since
+ * a group of parameters often uses the same code space for all individual
parameters.
+ *
+ * @param authority Bibliographic reference to the authority defining the
codes, or {@code null} if none.
+ * @param codespace The parameter codespace, or {@code null} for
inferring it from the authority.
+ * @return {@code this}, for method call chaining.
+ */
+ public DescriptorBuilder codespace(final Citation authority, final String
codespace) {
+ properties.put(ReferenceIdentifier.AUTHORITY_KEY, authority);
+ properties.put(ReferenceIdentifier.CODESPACE_KEY, codespace);
+ return this;
+ }
+
+ /**
+ * Sets the version of code definitions. This method is typically invoked
only once,
+ * since a group of parameters often uses the same version for all
individual parameters.
+ *
+ * @param version The version of code definitions, or {@code null} if
none.
+ * @return {@code this}, for method call chaining.
+ */
+ public DescriptorBuilder version(final String version) {
+ properties.put(ReferenceIdentifier.VERSION_KEY, version);
+ return this;
+ }
+
+ /**
+ * Sets the parameter as mandatory.
+ * The minimum number of times that values are required will be 1.
+ *
+ * @return {@code this}, for method call chaining.
+ */
+ public DescriptorBuilder mandatory() {
+ this.required = true;
+ return this;
+ }
+
+ /**
+ * Sets the parameter as optional.
+ * The minimum number of times that values are required will be 0.
+ *
+ * @return {@code this}, for method call chaining.
+ */
+ public DescriptorBuilder optional() {
+ this.required = false;
+ return this;
+ }
+
+ /**
+ * Constructs a descriptor for a parameter in a range of integer values.
+ *
+ * @param minimumValue The minimum parameter value (inclusive).
+ * @param maximumValue The maximum parameter value (inclusive).
+ * @param defaultValue The default value for the parameter.
+ * @return The parameter descriptor for the given range of values.
+ */
+ public ParameterDescriptor<Integer> create(final int minimumValue, final
int maximumValue,
+ final int defaultValue)
+ {
+ return new DefaultParameterDescriptor<>(properties, Integer.class,
+ NumberRange.create(minimumValue, true, maximumValue, true),
null, defaultValue, required);
+ }
+
+ /**
+ * Constructs a descriptor for a parameter in a range of floating point
values.
+ *
+ * @param minimumValue The minimum parameter value (inclusive), or {@link
Double#NEGATIVE_INFINITY} if none.
+ * @param maximumValue The maximum parameter value (inclusive), or {@link
Double#POSITIVE_INFINITY} if none.
+ * @param defaultValue The default value for the parameter, or {@link
Double#NaN} if none.
+ * @param unit The unit for default, minimum and maximum values,
or {@code null} if none.
+ * @return The parameter descriptor for the given range of values.
+ */
+ public ParameterDescriptor<Double> create(final double minimumValue, final
double maximumValue,
+ final double defaultValue, final Unit<?> unit)
+ {
+ final Range<Double> valueDomain;
+ if (unit != null) {
+ valueDomain = MeasurementRange.create(minimumValue, true,
maximumValue, true, unit);
+ } else if (minimumValue != Double.NEGATIVE_INFINITY || maximumValue !=
Double.POSITIVE_INFINITY) {
+ valueDomain = NumberRange.create(minimumValue, true, maximumValue,
true);
+ } else {
+ valueDomain = null;
+ }
+ return new DefaultParameterDescriptor<>(properties, Double.class,
+ valueDomain, null, Numerics.valueOf(defaultValue), required);
+ }
+
+ /**
+ * Constructs a descriptor for a strictly positive parameter value.
+ * The value must be greater than zero, and there is no maximum value.
+ *
+ * @param defaultValue The default value for the parameter, or {@link
Double#NaN} if none.
+ * @param unit The default unit, or {@code null} if none.
+ * @return The parameter descriptor for the given default value and unit.
+ */
+ public ParameterDescriptor<Double> createStrictlyPositive(final double
defaultValue, final Unit<?> unit) {
+ final Range<Double> valueDomain;
+ if (unit != null) {
+ valueDomain = MeasurementRange.create(0.0, false,
Double.POSITIVE_INFINITY, false, unit);
+ } else {
+ valueDomain = NumberRange.create(0.0, false,
Double.POSITIVE_INFINITY, false);
+ }
+ return new DefaultParameterDescriptor<>(properties, Double.class,
+ valueDomain, null, Numerics.valueOf(defaultValue), required);
+ }
+
+ /**
+ * Constructs a descriptor without any restriction on the range of values.
+ *
+ * @param defaultValue The default value for the parameter, or {@link
Double#NaN} if none.
+ * @param unit The default unit, or {@code null} if none.
+ * @return The parameter descriptor for the given default value and unit.
+ */
+ public ParameterDescriptor<Double> createUnbounded(final double
defaultValue, final Unit<?> unit) {
+ final Range<Double> valueDomain;
+ if (unit != null) {
+ valueDomain = MeasurementRange.create(Double.NEGATIVE_INFINITY,
false, Double.POSITIVE_INFINITY, false, unit);
+ } else {
+ valueDomain = null;
+ }
+ return new DefaultParameterDescriptor<>(properties, Double.class,
+ valueDomain, null, Numerics.valueOf(defaultValue), required);
+ }
+
+ /**
+ * Constructs a descriptor for a parameter in a range of values.
+ *
+ * @param <T> The compile-time type of the {@code valueClass}
argument.
+ * @param valueClass The class that describe the type of the parameter
values.
+ * @param minimumValue The minimum parameter value (inclusive), or {@code
null} if none.
+ * @param maximumValue The maximum parameter value (inclusive), or {@code
null} if none.
+ * @param defaultValue The default value for the parameter, or {@code
null} if none.
+ * @return The parameter descriptor for the given range of values.
+ */
+ @SuppressWarnings({"unchecked", "rawtypes"})
+ public <T extends Comparable<? super T>> ParameterDescriptor<T>
create(final Class<T> valueClass,
+ final T minimumValue, final T maximumValue, final T defaultValue)
+ {
+ final Range<T> valueDomain;
+ if (minimumValue == null && maximumValue == null) {
+ valueDomain = null;
+ } else if (Number.class.isAssignableFrom(valueClass)) {
+ valueDomain = new NumberRange((Class) valueClass, (Number)
minimumValue, true, (Number) maximumValue, true);
+ } else {
+ valueDomain = new Range<>(valueClass, minimumValue, true,
maximumValue, true);
+ }
+ return new DefaultParameterDescriptor<>(properties, valueClass,
valueDomain, null, defaultValue, required);
+ }
+
+ /**
+ * Constructs a descriptor for a parameter having a set of valid values.
+ * The descriptor has no minimal or maximal value and no unit.
+ *
+ * @param <T> The compile-time type of the {@code valueClass}
argument.
+ * @param valueClass The class that describe the type of the parameter
values.
+ * @param validValues A finite set of valid values (usually from a
{@linkplain CodeList code list})
+ * or {@code null} if it doesn't apply.
+ * @param defaultValue The default value for the parameter, or {@code
null} if none.
+ * @return The parameter descriptor for the given set of valid values.
+ */
+ public <T> ParameterDescriptor<T> createForEnumeration(final Class<T>
valueClass, final T[] validValues, final T defaultValue) {
+ return new DefaultParameterDescriptor<>(properties, valueClass, null,
validValues, defaultValue, required);
+ }
+}
Propchange:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK7/core/sis-referencing/src/main/java/org/apache/sis/parameter/DescriptorBuilder.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Added:
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java?rev=1573804&view=auto
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java
(added)
+++
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java
[UTF-8] Mon Mar 3 23:23:14 2014
@@ -0,0 +1,61 @@
+/*
+ * 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.parameter;
+
+import javax.measure.unit.Unit;
+import javax.measure.unit.SI;
+import javax.measure.unit.NonSI;
+import org.opengis.parameter.ParameterDescriptor;
+import org.apache.sis.metadata.iso.citation.HardCodedCitations;
+import org.apache.sis.test.DependsOn;
+import org.apache.sis.test.TestCase;
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+
+/**
+ * Tests {@link DescriptorBuilder}.
+ *
+ * @author Martin Desruisseaux (Geomatys)
+ * @since 0.4
+ * @version 0.4
+ * @module
+ */
+@DependsOn({DefaultParameterDescriptorTest.class,
DefaultParameterValueTest.class})
+public final strictfp class DescriptorBuilderTest extends TestCase {
+ /**
+ * Tests the "<cite>Mercator (variant A)</cite>" example given in Javadoc.
+ */
+ @Test
+ public void testMercatorExample() {
+ final DescriptorBuilder builder = new DescriptorBuilder();
+ builder.codespace(HardCodedCitations.OGP, "EPSG").mandatory();
+ final ParameterDescriptor[] parameters = {
+ builder.name("Latitude of natural origin") .create( -80, +80,
0, NonSI.DEGREE_ANGLE),
+ builder.name("Longitude of natural origin") .create(-180, +180,
0, NonSI.DEGREE_ANGLE),
+ builder.name("Scale factor at natural origin")
.createStrictlyPositive(1, Unit.ONE),
+ builder.name("False easting") .createUnbounded(0,
SI.METRE),
+ builder.name("False northing") .createUnbounded(0,
SI.METRE)
+ };
+ // Tests random properties.
+ assertEquals("EPSG",
parameters[0].getName().getCodeSpace());
+ assertEquals("False easting", parameters[3].getName().getCode());
+ assertEquals(Double.valueOf(80), parameters[0].getMaximumValue());
+ assertEquals(SI.METRE, parameters[4].getUnit());
+ }
+}
Propchange:
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange:
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/parameter/DescriptorBuilderTest.java
------------------------------------------------------------------------------
svn:mime-type = text/plain;charset=UTF-8
Modified:
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java?rev=1573804&r1=1573803&r2=1573804&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-referencing/src/test/java/org/apache/sis/test/suite/ReferencingTestSuite.java
[UTF-8] Mon Mar 3 23:23:14 2014
@@ -53,6 +53,7 @@ import org.junit.BeforeClass;
org.apache.sis.parameter.DefaultParameterDescriptorTest.class,
org.apache.sis.parameter.DefaultParameterValueTest.class,
org.apache.sis.parameter.ParametersTest.class,
+ org.apache.sis.parameter.DescriptorBuilderTest.class,
org.apache.sis.referencing.datum.BursaWolfParametersTest.class,
org.apache.sis.referencing.datum.TimeDependentBWPTest.class,
org.apache.sis.referencing.datum.DefaultEllipsoidTest.class,
Modified:
sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/MeasurementRange.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/MeasurementRange.java?rev=1573804&r1=1573803&r2=1573804&view=diff
==============================================================================
---
sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/MeasurementRange.java
[UTF-8] (original)
+++
sis/branches/JDK7/core/sis-utility/src/main/java/org/apache/sis/measure/MeasurementRange.java
[UTF-8] Mon Mar 3 23:23:14 2014
@@ -231,6 +231,8 @@ public class MeasurementRange<E extends
/**
* {@inheritDoc}
+ *
+ * @return {@inheritDoc}
*/
@Override
@SuppressWarnings("unchecked")
@@ -343,6 +345,7 @@ public class MeasurementRange<E extends
* the value of the other range to the unit of measurement of this range
before to perform
* the operation.
*
+ * @return {@inheritDoc}
* @throws IllegalArgumentException is the given range is an instance of
* {@code MeasurementRange} using incommensurable unit of
measurement.
*/
@@ -357,6 +360,7 @@ public class MeasurementRange<E extends
* the value of the other range to the unit of measurement of this range
before to perform
* the operation.
*
+ * @return {@inheritDoc}
* @throws IllegalArgumentException is the given range is an instance of
* {@code MeasurementRange} using incommensurable unit of
measurement.
*/
@@ -371,6 +375,7 @@ public class MeasurementRange<E extends
* the value of the other range to the unit of measurement of this range
before to perform
* the operation.
*
+ * @return {@inheritDoc}
* @throws IllegalArgumentException is the given range is an instance of
* {@code MeasurementRange} using incommensurable unit of
measurement.
*/
@@ -385,6 +390,7 @@ public class MeasurementRange<E extends
* the value of the other range to the unit of measurement of this range
before to perform
* the operation.
*
+ * @return {@inheritDoc}
* @throws IllegalArgumentException is the given range is an instance of
* {@code MeasurementRange} using incommensurable unit of
measurement.
*/
@@ -399,6 +405,7 @@ public class MeasurementRange<E extends
* the value of the other range to the unit of measurement of this range
before to perform
* the operation.
*
+ * @return {@inheritDoc}
* @throws IllegalArgumentException is the given range is an instance of
* {@code MeasurementRange} using incommensurable unit of
measurement.
*/
@@ -409,15 +416,21 @@ public class MeasurementRange<E extends
/**
* Compares this range with the specified object for equality.
+ *
+ * @return {@inheritDoc}
*/
@Override
public boolean equals(final Object object) {
- if (super.equals(object)) {
- if (object instanceof MeasurementRange<?>) {
- return Objects.equals(unit, ((MeasurementRange<?>)
object).unit);
- }
- return true;
- }
- return false;
+ return super.equals(object) && Objects.equals(unit,
((MeasurementRange<?>) object).unit);
+ }
+
+ /**
+ * Returns a hash code value for this measurement range.
+ *
+ * @return {@inheritDoc}
+ */
+ @Override
+ public int hashCode() {
+ return super.hashCode() + Objects.hashCode(unit);
}
}
