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.referencing;
033
034 import java.util.Map;
035 import java.util.Locale;
036 import java.util.Properties;
037 import java.util.Collections;
038
039 import org.opengis.metadata.Identifier;
040 import org.opengis.metadata.citation.Citation;
041 import org.opengis.util.Factory;
042 import org.opengis.util.InternationalString;
043 import org.opengis.util.GenericName;
044
045
046 /**
047 * Base interface for all factories of {@linkplain IdentifiedObject identified objects}. Factories
048 * build up complex objects from simpler objects or values. This factory allows applications to make
049 * {@linkplain org.opengis.referencing.cs.CoordinateSystem coordinate systems},
050 * {@linkplain org.opengis.referencing.datum.Datum datum} or
051 * {@linkplain org.opengis.referencing.crs.CoordinateReferenceSystem coordinate reference systems}
052 * that cannot be created by an {@linkplain AuthorityFactory authority factory}. This factory is
053 * very flexible, whereas the authority factory is easier to use.
054 * <p>
055 * <b>Object properties</b><br>
056 * Most factory methods expect a {@link Map} argument. The map can be a {@link Properties} instance.
057 * The map shall contains at least a {@code "name"} property. In the common case where the name is
058 * the only property, the map may be constructed with
059 *
060 * <code>Collections.{@linkplain Collections#singletonMap singletonMap}("name", <var>theName</var>)</code>
061 *
062 * where <var>theName</var> is an arbitrary name as free text.
063 * <p>
064 * Implementations are encouraged to recognize at least the properties listed in the following
065 * table. Additional implementation-specific properties can be added. Unknown properties shall
066 * be ignored.
067 * <p>
068 * <table border="1" cellspacing="0" cellpadding="2">
069 * <tr bgcolor="#CCCCFF" class="TableHeadingColor">
070 * <th nowrap>Property name</th>
071 * <th nowrap>Value type</th>
072 * <th nowrap>Value given to</th>
073 * </tr>
074 * <tr>
075 * <td nowrap> {@value org.opengis.referencing.IdentifiedObject#NAME_KEY} </td>
076 * <td nowrap> {@link org.opengis.referencing.ReferenceIdentifier} or {@link String} </td>
077 * <td nowrap> {@link IdentifiedObject#getName()}</td>
078 * </tr>
079 * <tr>
080 * <td nowrap> {@value org.opengis.referencing.IdentifiedObject#ALIAS_KEY} </td>
081 * <td nowrap> {@link String}, <code>{@linkplain String}[]</code>,
082 * {@link GenericName} or <code>{@linkplain GenericName}[]</code> </td>
083 * <td nowrap> {@link IdentifiedObject#getAlias()}</td>
084 * </tr>
085 * <tr>
086 * <td nowrap> {@value org.opengis.metadata.Identifier#AUTHORITY_KEY} </td>
087 * <td nowrap> {@link String} or {@link Citation} </td>
088 * <td nowrap> {@link Identifier#getAuthority()} on the {@linkplain IdentifiedObject#getName name}</td>
089 * </tr>
090 * <tr>
091 * <td nowrap> {@value org.opengis.referencing.ReferenceIdentifier#CODESPACE_KEY} </td>
092 * <td nowrap> {@link String} </td>
093 * <td nowrap> {@link ReferenceIdentifier#getCodeSpace()} on the {@linkplain IdentifiedObject#getName name}</td>
094 * </tr>
095 * <tr>
096 * <td nowrap> {@value org.opengis.referencing.ReferenceIdentifier#VERSION_KEY} </td>
097 * <td nowrap> {@link String} </td>
098 * <td nowrap> {@link ReferenceIdentifier#getVersion()} on the {@linkplain IdentifiedObject#getName name}</td>
099 * </tr>
100 * <tr>
101 * <td nowrap> {@value org.opengis.referencing.IdentifiedObject#IDENTIFIERS_KEY} </td>
102 * <td nowrap> {@link Identifier} or <code>{@linkplain Identifier}[]</code> </td>
103 * <td nowrap> {@link IdentifiedObject#getIdentifiers()}</td>
104 * </tr>
105 * <tr>
106 * <td nowrap> {@value org.opengis.referencing.IdentifiedObject#REMARKS_KEY} </td>
107 * <td nowrap> {@link String} or {@link InternationalString} </td>
108 * <td nowrap> {@link IdentifiedObject#getRemarks()}</td>
109 * </tr>
110 * </table>
111 * <p>
112 * The {@code "name"} property is mandatory. All others are optional. All localizable attributes
113 * like {@code "remarks"} can have a language and country code suffix. For example the
114 * {@code "remarks_fr"} property stands for remarks in {@linkplain Locale#FRENCH French} and the
115 * {@code "remarks_fr_CA"} property stands for remarks in {@linkplain Locale#CANADA_FRENCH French Canadian}.
116 *
117 * @departure harmonization
118 * This interface is not part of any OGC specification. It is added for uniformity,
119 * in order to provide a common base class for all referencing factories producing
120 * <code>IdentifiedObject</code> instances.
121 *
122 * @author Martin Desruisseaux (IRD)
123 * @version 3.0
124 * @since 2.0
125 */
126 public interface ObjectFactory extends Factory {
127 }