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.util;
033
034 import java.util.Map; // For javadoc
035 import java.util.Locale;
036
037
038 /**
039 * A {@linkplain String string} that has been internationalized into several {@linkplain Locale locales}.
040 * This interface is used as a replacement for the {@link String} type whenever an attribute needs to be
041 * internationalization capable.
042 *
043 * <P>The {@linkplain Comparable natural ordering} is defined by the {@linkplain String#compareTo
044 * lexicographical ordering of strings} in the default locale, as returned by {@link #toString()}.
045 * This string also defines the {@linkplain CharSequence character sequence} for this object.</P>
046 *
047 * @departure extension
048 * Added this new type in order to distinguish between localizable and non-localizable character
049 * strings. Not all character strings should be localizable; for example <cite>Well Know Text</cite>
050 * or code names should probably be language neutral. Since the ISO/OGC UML does not say which character
051 * strings are localizable and which ones are not, we have done our own guesses in GeoAPI.
052 *
053 * @author Martin Desruisseaux (IRD)
054 * @version 3.0
055 * @since 2.0
056 *
057 * @see javax.xml.registry.infomodel.InternationalString
058 * @see NameFactory#createInternationalString(Map)
059 */
060 public interface InternationalString extends CharSequence, Comparable<InternationalString> {
061 /**
062 * Returns this string in the given locale. If no string is available in the given locale,
063 * then some default locale is used. The default locale is implementation-dependent. It
064 * may or may not be the {@linkplain Locale#getDefault() system default}.
065 *
066 * @param locale The desired locale for the string to be returned, or {@code null}
067 * for a string in the implementation default locale.
068 * @return The string in the given locale if available, or in the default locale otherwise.
069 */
070 String toString(Locale locale);
071
072 /**
073 * Returns this string in the default locale. The default locale is implementation-dependent.
074 * It may or may not be the {@linkplain Locale#getDefault() system default}. If the default
075 * locale is the {@linkplain Locale#getDefault() system default} (a recommended practice),
076 * then invoking this method is equivalent to invoking
077 * <code>{@linkplain #toString(Locale) toString}({@linkplain Locale#getDefault()})</code>.
078 *
079 * <P>All methods from {@link CharSequence} operate on this string. This string is also
080 * used as the criterion for {@linkplain Comparable natural ordering}.</P>
081 *
082 * @return The string in the default locale.
083 */
084 @Override
085 String toString();
086 }