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.util;
019
020import java.util.Map;  // For javadoc
021import java.util.Locale;
022import org.opengis.annotation.UML;
023import static org.opengis.annotation.Specification.ISO_19115;
024
025
026/**
027 * A {@linkplain String string} that has been internationalized into several {@linkplain Locale locales}.
028 * This interface is used as a replacement for the {@link String} type whenever an attribute needs to be
029 * internationalization capable.
030 *
031 * <p>The {@linkplain Comparable natural ordering} is defined by the {@linkplain String#compareTo
032 * lexicographical ordering of strings} in the default locale, as returned by {@link #toString()}.
033 * This string also defines the {@linkplain CharSequence character sequence} for this object.</p>
034 *
035 * @departure rename
036 *   This is called {@code PT_FreeText} in ISO 19115 standard, and can be applied to all metadata
037 *   elements who's data type is {@code CharacterString} and domain is “free text”.
038 *   GeoAPI uses the {@code InternationalString} name for historical reasons and for consistency
039 *   with similar object in Internationalization Service for J2EE.
040 *
041 * @author  Martin Desruisseaux (IRD)
042 * @version 3.0
043 * @since   2.0
044 *
045 * @see NameFactory#createInternationalString(Map)
046 */
047@UML(identifier="PT_FreeText", specification=ISO_19115)
048public interface InternationalString extends CharSequence, Comparable<InternationalString> {
049    /**
050     * Returns this string in the given locale. If no string is available in the given locale,
051     * then some fallback locale is used. The fallback locale is implementation-dependent, and
052     * is not necessarily the same as the default locale used by the {@link #toString()} method.
053     *
054     * <p>If the application is running on a server, the {@code locale} argument should be
055     * determined from the HTTP request headers instead of the platform default locale.</p>
056     *
057     * @param  locale  the desired locale for the string to be returned.
058     * @return the string in the given locale if available, or in an
059     *         implementation-dependent fallback locale otherwise.
060     *
061     * @see Locale#getDefault()
062     * @see Locale#ROOT
063     */
064    String toString(Locale locale);
065
066    /**
067     * Returns this string in the default locale. The default locale is implementation-dependent.
068     * It may be the {@linkplain Locale#getDefault() system default}, the {@linkplain Locale#ROOT
069     * root locale} or any other locale at implementation choice.
070     *
071     * <p>All methods from {@link CharSequence} operate on this string.
072     * This string is also used as the criterion for {@linkplain Comparable natural ordering}.</p>
073     *
074     * @return the string in the default locale.
075     */
076    @Override
077    String toString();
078}