001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2024 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing;
019
020import java.util.Locale;
021
022import org.opengis.metadata.Identifier;
023import org.opengis.metadata.extent.Extent;
024import org.opengis.metadata.citation.Citation;
025import org.opengis.util.Factory;
026import org.opengis.util.InternationalString;
027import org.opengis.util.GenericName;
028
029
030/**
031 * Base interface for all factories of identified objects.
032 * Factories build up complex objects from simpler objects or values.
033 * This factory allows applications to make
034 * {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate systems},
035 * {@linkplain org.opengis.referencing.datum.Datum datum} or
036 * {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference systems}
037 * that cannot be created by an {@linkplain AuthorityFactory authority factory}.
038 * This factory is very flexible, whereas the authority factory is easier to use.
039 *
040 * <h2>Object properties</h2>
041 * Most factory methods expect a {@code Map<String,?>} argument.
042 * The table below lists the keys that {@code ObjectFactory} implementations shall accept,
043 * together with the type of values associated to those keys. The <q>Alternative types</q> column
044 * gives examples of types that factory implementations may accept as well for convenience.
045 * A value for the {@code "name"} key is mandatory, while all other properties are optional.
046 * Factory methods shall ignore unknown properties.
047 *
048 * <table class="ogc">
049 *   <caption>Keys for standard properties</caption>
050 *   <tr>
051 *     <th>Key</th>
052 *     <th>Value type</th>
053 *     <th>Alternative types</th>
054 *     <th>Value returned by</th>
055 *   </tr><tr>
056 *     <td>{@value org.opengis.referencing.IdentifiedObject#NAME_KEY}</td>
057 *     <td>{@link Identifier}</td>
058 *     <td>{@link String} (see alternatives below)</td>
059 *     <td>{@link IdentifiedObject#getName()}</td>
060 *   </tr><tr>
061 *     <td>{@value org.opengis.referencing.IdentifiedObject#ALIAS_KEY}</td>
062 *     <td><code>{@linkplain GenericName}[]</code></td>
063 *     <td>{@link GenericName}, {@link String} or <code>{@linkplain String}[]</code></td>
064 *     <td>{@link IdentifiedObject#getAlias()}</td>
065 *   </tr><tr>
066 *     <td>{@value org.opengis.referencing.IdentifiedObject#IDENTIFIERS_KEY}</td>
067 *     <td><code>{@linkplain Identifier}[]</code></td>
068 *     <td>{@link Identifier}</td>
069 *     <td>{@link IdentifiedObject#getIdentifiers()}</td>
070 *   </tr><tr>
071 *     <td>{@value org.opengis.referencing.IdentifiedObject#DOMAINS_KEY}</td>
072 *     <td><code>{@linkplain ObjectDomain}[]</code></td>
073 *     <td>{@link ObjectDomain} (see alternatives below)</td>
074 *     <td>{@link IdentifiedObject#getDomains()}</td>
075 *   </tr><tr>
076 *     <td>{@value org.opengis.referencing.IdentifiedObject#REMARKS_KEY}</td>
077 *     <td>{@link InternationalString}</td>
078 *     <td>{@link String} (see localization below)</td>
079 *     <td>{@link IdentifiedObject#getRemarks()}</td>
080 *   </tr>
081 * </table>
082 *
083 * <div class="note"><b>Note:</b>
084 * multi-values are arrays instead of collections in order to allow implementations to check the element
085 * type by Java reflection. Such reflection cannot be performed on collections because of type erasure.</div>
086 *
087 * <p>Implementations may allow alternative ways to define the {@code "name"} and {@code "domains"} properties
088 * for user convenience:</p>
089 * <table class="ogc">
090 *   <caption>Convenience keys (non-standard)</caption>
091 *   <tr>
092 *     <th>Key</th>
093 *     <th>Value type</th>
094 *     <th>Alternative types</th>
095 *     <th>Value returned by</th>
096 *   </tr><tr>
097 *     <td>{@value org.opengis.metadata.Identifier#AUTHORITY_KEY}</td>
098 *     <td>{@link Citation}</td>
099 *     <td>{@link String}</td>
100 *     <td>{@link Identifier#getAuthority()}</td>
101 *   </tr><tr>
102 *     <td>{@value org.opengis.metadata.Identifier#CODESPACE_KEY}</td>
103 *     <td>{@link String}</td>
104 *     <td></td>
105 *     <td>{@link Identifier#getCodeSpace()}</td>
106 *   </tr><tr>
107 *     <td>{@value org.opengis.metadata.Identifier#VERSION_KEY}</td>
108 *     <td>{@link String}</td>
109 *     <td></td>
110 *     <td>{@link Identifier#getVersion()}</td>
111 *   </tr><tr>
112 *     <td>{@value org.opengis.referencing.ObjectDomain#SCOPE_KEY}</td>
113 *     <td>{@link InternationalString}</td>
114 *     <td>{@link String} (see localization below)</td>
115 *     <td>{@link ObjectDomain#getScope()}</td>
116 *   </tr><tr>
117 *     <td>{@value org.opengis.referencing.ObjectDomain#DOMAIN_OF_VALIDITY_KEY}</td>
118 *     <td>{@link Extent}</td>
119 *     <td></td>
120 *     <td>{@link ObjectDomain#getDomainOfValidity()}</td>
121 *   </tr>
122 * </table>
123 *
124 * <h2>Localization</h2>
125 * Localizable attributes like {@code "remarks"} can be specified either as a single {@code InternationalString},
126 * or as one or many {@code String}s associated to keys suffixed by a language and country code.
127 * For example, the {@code "remarks_fr"} key stands for remarks in {@linkplain Locale#FRENCH French} and the
128 * {@code "remarks_fr_CA"} key stands for remarks in {@linkplain Locale#CANADA_FRENCH French Canadian}.
129 *
130 * @departure harmonization
131 *   This interface is not part of any OGC specification. It is added for uniformity,
132 *   in order to provide a common base class for all referencing factories producing
133 *   {@code IdentifiedObject} instances.
134 *
135 * @author  Martin Desruisseaux (IRD)
136 * @version 3.0
137 * @since   2.0
138 */
139public interface ObjectFactory extends Factory {
140}