001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2005-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.util;
033
034 import java.util.Map;
035 import java.util.Locale;
036
037
038 /**
039 * Factory for {@linkplain GenericName generic names} and
040 * {@linkplain InternationalString international strings}.
041 *
042 * {@note Despite the "<code>create</code>" name, implementations may return cached instances.}
043 *
044 * @departure extension
045 * Added in order to provide constructors for <code>GenericName</code> and related interfaces.
046 *
047 * @author Jesse Crossley (SYS Technologies)
048 * @author Martin Desruisseaux (Geomatys)
049 * @version 3.1
050 * @since 2.0
051 */
052 public interface NameFactory extends Factory {
053 /**
054 * Creates an international string from a set of strings in different locales.
055 *
056 * @param strings
057 * String value for each locale key.
058 * @return The international string.
059 */
060 InternationalString createInternationalString(Map<Locale,String> strings);
061
062 /**
063 * Creates a namespace having the given name and separators. The {@code properties} argument
064 * is optional: if non-null, the given properties may be given to the namespace to be created.
065 * The properties can include for example the separator character to be used between the
066 * {@linkplain GenericName#getParsedNames() parsed names}.
067 * <p>
068 * Implementations are encouraged to recognize at least the properties listed in the following
069 * table. Additional implementation-specific properties can be added. Unknown properties shall
070 * be ignored.
071 * <p>
072 * <table border="1" cellspacing="0" cellpadding="2">
073 * <tr bgcolor="#CCCCFF" class="TableHeadingColor">
074 * <th nowrap>Property name</th>
075 * <th nowrap>Purpose</th>
076 * </tr>
077 * <tr>
078 * <td valign="top" nowrap> {@code "separator"} </td>
079 * <td>The separator to insert between {@linkplain GenericName#getParsedNames() parsed names}
080 * in that namespace. For HTTP namespace, it is {@code "."}. For URN namespace,
081 * it is typically {@code ":"}.</td>
082 * </tr>
083 * <tr>
084 * <td valign="top" nowrap> {@code "separator.head"} </td>
085 * <td>The separator to insert between the namespace and the
086 * {@linkplain GenericName#head() head}. For HTTP namespace, it is {@code "://"}.
087 * For URN namespace, it is typically {@code ":"}. If this entry is omitted, then
088 * the default shall be the same value than the {@code "separator"} entry.</td>
089 * </tr>
090 * </table>
091 *
092 * @param name
093 * The name of the namespace to be returned. This argument can be created using
094 * <code>{@linkplain #createGenericName createGenericName}(null, parsedNames)</code>.
095 * @param properties
096 * An optional map of properties to be assigned to the namespace, or {@code null} if none.
097 * @return A namespace having the given name and separators.
098 *
099 * @since 2.3
100 */
101 NameSpace createNameSpace(GenericName name, Map<String,?> properties);
102
103 /**
104 * Creates a type name from the given character sequence. The character sequence shall
105 * complies to the same restriction than {@link #createLocalName createLocalName}.
106 *
107 * @param scope
108 * The {@linkplain GenericName#scope() scope} of the type name to be created,
109 * or {@code null} for a global namespace.
110 * @param name
111 * The type name as a string or an international string.
112 * @return The type name for the given character sequence.
113 *
114 * @since 2.3
115 */
116 TypeName createTypeName(NameSpace scope, CharSequence name);
117
118 /**
119 * Creates a member name from the given character sequence and attribute type.
120 *
121 * @param scope The {@linkplain GenericName#scope() scope} of the member
122 * name to be created, or {@code null} for a global namespace.
123 * @param name The member name as a string or an international string.
124 * @param attributeType The type of the data associated with the record member.
125 * @return The member name for the given character sequence.
126 *
127 * @since 3.1
128 */
129 MemberName createMemberName(NameSpace scope, CharSequence name, TypeName attributeType);
130
131 /**
132 * Creates a local name from the given character sequence. The character sequence can be either
133 * a {@link String} or an {@link InternationalString} instance. In the later case, implementations
134 * can use an arbitrary {@linkplain Locale locale} (typically {@link Locale#ENGLISH ENGLISH},
135 * but not necessarily) for the unlocalized string to be returned by {@link LocalName#toString()}.
136 *
137 * @param scope
138 * The {@linkplain GenericName#scope() scope} of the local name to be created,
139 * or {@code null} for a global namespace.
140 * @param name
141 * The local name as a string or an international string.
142 * @return The local name for the given character sequence.
143 *
144 * @since 2.2
145 */
146 LocalName createLocalName(NameSpace scope, CharSequence name);
147
148 /**
149 * Creates a local or scoped name from an array of parsed names. The array elements can be either
150 * {@link String} or {@link InternationalString} instances. In the later case, implementations
151 * can use an arbitrary {@linkplain Locale locale} (typically {@link Locale#ENGLISH ENGLISH},
152 * but not necessarily) for the unlocalized string to be returned by {@link GenericName#toString()}.
153 * <p>
154 * If the length of the {@code parsedNames} array is 1, then this method returns an instance
155 * of {@link LocalName}. If the length is 2 or more, then this method returns an instance of
156 * {@link ScopedName}.
157 *
158 * @param scope
159 * The {@linkplain GenericName#scope() scope} of the generic name to be created,
160 * or {@code null} for a global namespace.
161 * @param parsedNames
162 * The local names as an array of strings or international strings.
163 * This array must contains at least one element.
164 * @return The generic name for the given parsed names.
165 *
166 * @since 2.2
167 */
168 GenericName createGenericName(NameSpace scope, CharSequence... parsedNames);
169
170 /**
171 * Constructs a generic name from a qualified name. This method splits the given name around a
172 * separator inferred from the given scope, or an implementation-dependent default separator if
173 * the given scope is null.
174 * <p>
175 * For example if the {@code scope} argument is the namespace {@code "urn:ogc:def"}
176 * with {@code ":"} as the separator, and if the {@code name} argument is the string
177 * {@code "crs:epsg:4326"}, then the result is a {@linkplain ScopedName scoped name}
178 * having a {@linkplain GenericName#depth depth} of 3, which is the length of the list
179 * of {@linkplain GenericName#getParsedNames parsed names} ({@code "crs"}, {@code "epsg"},
180 * {@code "4326"}).
181 *
182 * @param scope
183 * The {@linkplain GenericName#scope() scope} of the generic name to
184 * be created, or {@code null} for a global namespace.
185 * @param name
186 * The qualified name, as a sequence of names separated by a scope-dependent separator.
187 * @return A name parsed from the given string.
188 *
189 * @since 2.2
190 */
191 GenericName parseGenericName(NameSpace scope, CharSequence name);
192 }