001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.parameter;
033
034 import java.util.Set;
035 import javax.measure.unit.Unit;
036 import org.opengis.util.CodeList;
037 import org.opengis.annotation.UML;
038
039 import static org.opengis.annotation.Obligation.*;
040 import static org.opengis.annotation.Specification.*;
041
042
043 /**
044 * The definition of a parameter used by an operation method. Most parameter values are
045 * numeric, but other types of parameter values are possible.
046 *
047 * @param <T> The type of parameter values.
048 *
049 * @departure rename
050 * GeoAPI uses a name which contains the "<code>Descriptor</code>" word for consistency with other
051 * libraries in Java (e.g. <code>ParameterListDescriptor</code> in Java Advanced Imaging).
052 *
053 * @author Martin Desruisseaux (IRD)
054 * @author Jody Garnett (Refractions Research)
055 * @version 3.0
056 * @since 2.0
057 *
058 * @see ParameterValue
059 * @see ParameterDescriptorGroup
060 */
061 @UML(identifier="CC_OperationParameter", specification=ISO_19111)
062 public interface ParameterDescriptor<T> extends GeneralParameterDescriptor {
063 /**
064 * Creates a new instance of {@linkplain ParameterValue parameter value} initialized with the
065 * {@linkplain #getDefaultValue() default value}. While not a requirement, the
066 * {@linkplain ParameterValue#getDescriptor() parameter value descriptor}
067 * for the created parameter value will typically be {@code this} descriptor instance.
068 *
069 * @departure extension
070 * This method is not part of the ISO specification. It is provided in GeoAPI as a kind of
071 * factory method.
072 */
073 @Override
074 ParameterValue<T> createValue();
075
076 /**
077 * Returns the class that describe the type of the parameter.
078 *
079 * @return The type of parameter values.
080 */
081 @UML(identifier="GC_ParameterInfo.type", obligation=MANDATORY, specification=ISO_19111)
082 Class<T> getValueClass();
083
084 /**
085 * Returns the set of allowed values when these are restricted to some finite set or returns
086 * {@code null} otherwise. The returned set usually contains {@linkplain CodeList code list}
087 * or enumeration elements.
088 *
089 * @return A finite set of valid values (usually from a {@linkplain CodeList code list}),
090 * or {@code null} if it doesn't apply.
091 *
092 * @departure extension
093 * This method is not part of ISO specification. It is provided as a complement of information.
094 */
095 Set<T> getValidValues();
096
097 /**
098 * Returns the default value for the parameter. The return type can be any type
099 * including a {@link Number} or a {@link String}. If there is no default value,
100 * then this method returns {@code null}.
101 *
102 * @return The default value, or {@code null} in none.
103 */
104 @UML(identifier="GC_ParameterInfo.defaultValue", obligation=OPTIONAL, specification=ISO_19111)
105 T getDefaultValue();
106
107 /**
108 * Returns the minimum parameter value.
109 *
110 * If there is no minimum value, or if minimum
111 * value is inappropriate for the {@linkplain #getValueClass() parameter type}, then
112 * this method returns {@code null}.
113 * <p>
114 * When the getValueClass() is an array or Collection getMinimumValue
115 * may be used to constrain the contained elements.
116 * </p>
117 * @return The minimum parameter value (often an instance of {@link Double}), or {@code null}.
118 */
119 @UML(identifier="GC_ParameterInfo.minimumValue", obligation=OPTIONAL, specification=ISO_19111)
120 Comparable<T> getMinimumValue();
121
122 /**
123 * Returns the maximum parameter value.
124 *
125 * If there is no maximum value, or if maximum
126 * value is inappropriate for the {@linkplain #getValueClass() parameter type}, then
127 * this method returns {@code null}.
128 * <p>
129 * When the getValueClass() is an array or Collection getMaximumValue
130 * may be used to constraint the contained elements.
131 *
132 * @return The minimum parameter value (often an instance of {@link Double}), or {@code null}.
133 */
134 @UML(identifier="GC_ParameterInfo.maximumValue", obligation=OPTIONAL, specification=ISO_19111)
135 Comparable<T> getMaximumValue();
136
137 /**
138 * Returns the unit for
139 * {@linkplain #getDefaultValue default},
140 * {@linkplain #getMinimumValue minimum} and
141 * {@linkplain #getMaximumValue maximum} values.
142 * This attribute apply only if the values is of numeric type (usually an instance
143 * of {@link Double}).
144 *
145 * @return The unit for numeric value, or {@code null} if it doesn't apply to the value type.
146 *
147 * @departure extension
148 * This method is not part of ISO specification. It is provided as a complement of information.
149 */
150 Unit<?> getUnit();
151 }