001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2013 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.List;
035 import org.opengis.metadata.Identifier;
036 import org.opengis.annotation.UML;
037
038 import static org.opengis.annotation.Obligation.*;
039 import static org.opengis.annotation.Specification.*;
040
041
042 /**
043 * A group of related parameter values. The same group can be repeated more than once in an
044 * {@linkplain org.opengis.referencing.operation.CoordinateOperation coordinate operation}
045 * or higher level {@code ParameterValueGroup}, if those instances contain different values
046 * of one or more {@link ParameterValue}s which suitably distinguish among those groups.
047 *
048 * @author Martin Desruisseaux (IRD)
049 * @author Jody Garnett (Refractions Research)
050 * @version 3.0
051 * @since 1.0
052 *
053 * @see ParameterDescriptorGroup
054 * @see ParameterValue
055 *
056 * @navassoc - - - GeneralParameterValue
057 */
058 @UML(identifier="CC_ParameterValueGroup", specification=ISO_19111)
059 public interface ParameterValueGroup extends GeneralParameterValue {
060 /**
061 * The abstract definition of this group of parameters.
062 *
063 * @departure rename
064 * The ISO name was "<code>group</code>". GeoAPI uses "<code>descriptor</code>" instead in
065 * order to override the <code>getDescriptor()</code> generic method provided in the parent
066 * interface. In addition the "descriptor" name makes more apparent that this method returns
067 * an abstract definition of parameters - not their actual values - and is consistent with
068 * usage in other Java libraries like the <cite>Java Advanced Imaging</cite> library.
069 */
070 @Override
071 @UML(identifier="group", obligation=MANDATORY, specification=ISO_19111)
072 ParameterDescriptorGroup getDescriptor();
073
074 /**
075 * Returns the values in this group. The returned list may or may not be unmodifiable;
076 * this is implementation-dependent. However, if some aspects of this list are modifiable,
077 * then any modification shall be reflected back into this {@code ParameterValueGroup}.
078 * More specifically:
079 *
080 * <ul>
081 * <li>If the list supports the {@link List#add(Object) add} operation, then it should
082 * ensure that the added {@linkplain GeneralParameterValue general parameter value} is
083 * valid and can be added to this group.
084 * An {@link InvalidParameterCardinalityException} (or any other appropriate exception)
085 * shall be thrown if it is not the case.</li>
086 * <li>The list may also supports the {@link List#remove(Object) remove} operation as a
087 * way to remove parameter created by the {@link #parameter(String)} method.</li>
088 * </ul>
089 *
090 * @return The values in this group.
091 */
092 @UML(identifier="parameterValue", obligation=MANDATORY, specification=ISO_19111)
093 List<GeneralParameterValue> values();
094
095 /**
096 * Returns the value in this group for the specified {@linkplain Identifier#getCode
097 * identifier code}. If no {@linkplain ParameterValue parameter value} is found but
098 * a {@linkplain ParameterDescriptor parameter descriptor} is found (which may occurs
099 * if the parameter is optional, i.e. <code>{@linkplain ParameterDescriptor#getMinimumOccurs()
100 * minimumOccurs} == 0</code>), then a {@linkplain ParameterValue parameter value} is
101 * automatically created and initialized to its {@linkplain ParameterDescriptor#getDefaultValue()
102 * default value} (if any).
103 *
104 * <p>This convenience method provides a way to get and set parameter values by name. For
105 * example the following idiom fetches a floating point value for the
106 * {@code "false_easting"} parameter:</p>
107 *
108 * <blockquote><code>
109 * double value = <b>parameter</b>("false_easting").{@linkplain ParameterValue#doubleValue() doubleValue}();
110 * </code></blockquote>
111 *
112 * The following idiom sets a floating point value for the {@code "false_easting"} parameter:
113 *
114 * <blockquote><code>
115 * <b>parameter</b>("false_easting").{@linkplain ParameterValue#setValue(double) setValue}(500000.0);
116 * </code></blockquote>
117 *
118 * This method does not search recursively in subgroups. This is because more than one
119 * subgroup may exist for the same {@linkplain ParameterDescriptorGroup descriptor}.
120 * The user must {@linkplain #groups(String) query all subgroups} and select explicitly the
121 * appropriate one to use.
122 *
123 * @param name The case insensitive {@linkplain Identifier#getCode identifier code} of the
124 * parameter to search for.
125 * @return The parameter value for the given identifier code.
126 * @throws ParameterNotFoundException if there is no parameter value for the given identifier code.
127 *
128 * @departure easeOfUse
129 * This method is not part of the ISO specification. It has been added in an attempt to make
130 * this interface easier to use.
131 */
132 ParameterValue<?> parameter(String name) throws ParameterNotFoundException;
133
134 /**
135 * Returns all subgroups with the specified name. This method do not create new groups.
136 * If the requested group is optional (i.e.
137 * <code>{@linkplain ParameterDescriptor#getMinimumOccurs() minimumOccurs} == 0</code>)
138 * and no value were defined previously, then this method returns an empty set.
139 *
140 * @param name The case insensitive {@linkplain Identifier#getCode identifier code} of the
141 * parameter group to search for.
142 * @return The set of all parameter group for the given identifier code.
143 * @throws ParameterNotFoundException if no {@linkplain ParameterDescriptorGroup descriptor}
144 * was found for the given name.
145 *
146 * @departure easeOfUse
147 * This method is not part of the ISO specification. It has been added in an attempt to make
148 * this interface easier to use.
149 */
150 List<ParameterValueGroup> groups(String name) throws ParameterNotFoundException;
151
152 /**
153 * Creates a new group of the specified name. The specified name must be the
154 * {@linkplain Identifier#getCode() identifier code} of a {@linkplain ParameterDescriptorGroup
155 * descriptor group}.
156 *
157 * <p>There is no {@code removeGroup(String)} method. To remove a group, users shall inspect the
158 * {@link #values()} list, decide which occurrences to remove if there is many of them for the
159 * same name, and whether to iterate recursively into sub-groups or not.</p>
160 *
161 * @param name The case insensitive {@linkplain Identifier#getCode() identifier code} of the
162 * parameter group to create.
163 * @return A newly created parameter group for the given identifier code.
164 * @throws ParameterNotFoundException if no {@linkplain ParameterDescriptorGroup descriptor}
165 * was found for the given name.
166 * @throws InvalidParameterCardinalityException If this parameter group already contains the
167 * {@linkplain ParameterDescriptorGroup#getMaximumOccurs maximum number of occurences}
168 * of subgroups of the given name.
169 * @throws IllegalStateException If the group can not be added for an other raison.
170 *
171 * @departure easeOfUse
172 * This method is not part of the ISO specification. It has been added in an attempt to make
173 * this interface easier to use.
174 */
175 ParameterValueGroup addGroup(String name) throws ParameterNotFoundException, IllegalStateException;
176
177 /**
178 * Returns a copy of this group of parameter values.
179 * Included parameter values and subgroups are cloned recursively.
180 *
181 * @return A copy of this group of parameter values.
182 */
183 @Override
184 ParameterValueGroup clone();
185 }