001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2004-2006, Geotools Project Managment Committee (PMC)
005: * (C) 2004, Institut de Recherche pour le Développement
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2.1 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * This package contains documentation from OpenGIS specifications.
018: * OpenGIS consortium's work is fully acknowledged here.
019: */
020: package org.geotools.util;
021:
022: // J2SE dependencies
023: import java.util.Locale;
024:
025: // OpenGIS dependencies
026: import org.opengis.util.InternationalString;
027:
028: // Geotools dependencies
029: import org.geotools.resources.i18n.Errors;
030: import org.geotools.resources.i18n.ErrorKeys;
031:
032: /**
033: * A {@linkplain String string} that has been internationalized into several
034: * {@linkplain Locale locales}. This class is used as a replacement for the
035: * {@link String} type whenever an attribute needs to be internationalization
036: * capable. The default value (as returned by {@link #toString()} and other
037: * {@link CharSequence} methods} is the string in the current {@linkplain
038: * Locale#getDefault system default}.
039: *
040: * <P>The {@linkplain Comparable natural ordering} is defined by the string in
041: * {@linkplain Locale#getDefault default locale}, as returned by {@link #toString()}.
042: * This string also defines the {@linkplain CharSequence character sequence}.</P>
043: *
044: * @since 2.1
045: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/metadata/src/main/java/org/geotools/util/AbstractInternationalString.java $
046: * @version $Id: AbstractInternationalString.java 22443 2006-10-27 20:47:22Z desruisseaux $
047: * @author Martin Desruisseaux
048: */
049: public abstract class AbstractInternationalString implements
050: InternationalString {
051: /**
052: * The string in the {@linkplain Locale#getDefault system default} locale, or {@code null}
053: * if this string has not yet been determined. This is the default string returned by
054: * {@link #toString()} and others methods from the {@link CharSequence} interface.
055: *
056: * <P>This field is not serialized because serialization is often used for data transmission
057: * between a server and a client, and the client may not use the same locale than the server.
058: * We want the locale to be examined again on the client side.</P>
059: *
060: * <P>This field is read and write by {@link SimpleInternationalString}.</P>
061: */
062: transient String defaultValue;
063:
064: /**
065: * Constructs an international string.
066: */
067: public AbstractInternationalString() {
068: }
069:
070: /**
071: * Makes sure an argument is non-null.
072: *
073: * @param name Argument name.
074: * @param object User argument.
075: * @throws IllegalArgumentException if {@code object} is null.
076: */
077: static void ensureNonNull(final String name, final Object object)
078: throws IllegalArgumentException {
079: if (object == null) {
080: throw new IllegalArgumentException(Errors.format(
081: ErrorKeys.NULL_ARGUMENT_$1, name));
082: }
083: }
084:
085: /**
086: * Returns the length of the string in the {@linkplain Locale#getDefault default locale}.
087: * This is the length of the string returned by {@link #toString()}.
088: */
089: public int length() {
090: if (defaultValue == null) {
091: defaultValue = toString();
092: if (defaultValue == null) {
093: return 0;
094: }
095: }
096: return defaultValue.length();
097: }
098:
099: /**
100: * Returns the character of the string in the {@linkplain Locale#getDefault default locale}
101: * at the specified index. This is the character of the string returned by {@link #toString()}.
102: *
103: * @param index The index of the character.
104: * @return The character at the specified index.
105: * @throws IndexOutOfBoundsException if the specified index is out of bounds.
106: */
107: public char charAt(final int index)
108: throws IndexOutOfBoundsException {
109: if (defaultValue == null) {
110: defaultValue = toString();
111: if (defaultValue == null) {
112: throw new IndexOutOfBoundsException(String
113: .valueOf(index));
114: }
115: }
116: return defaultValue.charAt(index);
117: }
118:
119: /**
120: * Returns a subsequence of the string in the {@linkplain Locale#getDefault default locale}.
121: * The subsequence is a {@link String} object starting with the character value at the specified
122: * index and ending with the character value at index {@code end - 1}.
123: *
124: * @param start The start index, inclusive.
125: * @param end The end index, exclusive.
126: * @return The specified subsequence.
127: * @throws IndexOutOfBoundsException if {@code start} or {@code end} is
128: * out of range.
129: */
130: public CharSequence subSequence(final int start, final int end) {
131: if (defaultValue == null) {
132: defaultValue = toString();
133: if (defaultValue == null) {
134: throw new IndexOutOfBoundsException(String
135: .valueOf(start));
136: }
137: }
138: return defaultValue.substring(start, end);
139: }
140:
141: /**
142: * Returns this string in the given locale. If no string is available in the given locale,
143: * then some default locale is used. The default locale is implementation-dependent. It
144: * may or may not be the {@linkplain Locale#getDefault() system default}).
145: *
146: * @param locale The desired locale for the string to be returned, or {@code null}
147: * for a string in the implementation default locale.
148: * @return The string in the given locale if available, or in the default locale otherwise.
149: */
150: public abstract String toString(final Locale locale);
151:
152: /**
153: * Returns this string in the default locale. Invoking this method is equivalent to invoking
154: * <code>{@linkplain #toString(Locale) toString}({@linkplain Locale#getDefault})</code>. All
155: * methods from {@link CharSequence} operate on this string. This string is also used as the
156: * criterion for {@linkplain Comparable natural ordering}.
157: *
158: * @return The string in the default locale.
159: */
160: public String toString() {
161: if (defaultValue == null) {
162: defaultValue = toString(Locale.getDefault());
163: if (defaultValue == null) {
164: return "";
165: }
166: }
167: return defaultValue;
168: }
169:
170: /**
171: * Compare this string with the specified object for order. This method compare
172: * the string in the {@linkplain Locale#getDefault default locale}, as returned
173: * by {@link #toString()}.
174: */
175: public int compareTo(final Object object) {
176: return toString().compareTo(object.toString());
177: }
178: }
|