/*
|
* CDDL HEADER START
|
*
|
* The contents of this file are subject to the terms of the
|
* Common Development and Distribution License, Version 1.0 only
|
* (the "License"). You may not use this file except in compliance
|
* with the License.
|
*
|
* You can obtain a copy of the license at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE
|
* or https://OpenDS.dev.java.net/OpenDS.LICENSE.
|
* See the License for the specific language governing permissions
|
* and limitations under the License.
|
*
|
* When distributing Covered Code, include this CDDL HEADER in each
|
* file and include the License file at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
|
* add the following below this CDDL HEADER, with the fields enclosed
|
* by brackets "[]" replaced with your own identifying information:
|
* Portions Copyright [yyyy] [name of copyright owner]
|
*
|
* CDDL HEADER END
|
*
|
*
|
* Copyright 2009 Sun Microsystems, Inc.
|
*/
|
|
package org.opends.sdk;
|
|
|
|
import java.util.Formattable;
|
import java.util.Formatter;
|
import java.util.IllegalFormatException;
|
import java.util.Locale;
|
|
import com.sun.opends.sdk.util.LocalizableMessageDescriptor;
|
import com.sun.opends.sdk.util.Validator;
|
|
|
|
/**
|
* A localizable message whose {@code String} representation can be retrieved in
|
* one or more locales. A message is localized each time it is converted to a
|
* {@code String} using one of its {@link #toString} methods.
|
* <p>
|
* Localizable messages are particularly useful in situations where a message a
|
* destined for multiple recipients, potentially in different locales. For
|
* example, a server application may record a message in its log file using its
|
* default locale, but also send the same message to the client using the
|
* client's locale (if known).
|
* <p>
|
* In most cases messages are intended for use in a locale-sensitive manner
|
* although this class defines convenience methods for creating
|
* uninternationalized messages whose {@code String} representation is always
|
* the same regardless of the requested locale.
|
* <p>
|
* This class implements {@code CharSequence} so that messages can be supplied
|
* as arguments to other messages. This way messages can be composed of
|
* fragments of other messages if necessary.
|
*
|
* @see LocalizableMessageBuilder
|
*/
|
public final class LocalizableMessage implements CharSequence, Formattable,
|
Comparable<LocalizableMessage>
|
{
|
static
|
{
|
LocalizableMessageDescriptor.messageFactory = new LocalizableMessageDescriptor.MessageFactory()
|
{
|
|
public LocalizableMessage newMessage(
|
final LocalizableMessageDescriptor descriptor, final Object... args)
|
{
|
return new LocalizableMessage(descriptor, args);
|
}
|
};
|
}
|
|
/**
|
* Represents an empty message string.
|
*/
|
public static final LocalizableMessage EMPTY = LocalizableMessage.raw("");
|
|
// Variable used to workaround a bug in AIX Java 1.6
|
// TODO: remove this code once the JDK issue referenced in 3077 is
|
// closed.
|
private static final boolean IS_AIX_POST5 = isAIXPost5();
|
|
|
|
/**
|
* Creates an uninternationalized message whose {@code String} representation
|
* is always the same regardless of the requested locale.
|
* <p>
|
* Note that the types for {@code args} must be consistent with any argument
|
* specifiers appearing in {@code formatString} according to the rules of
|
* {@link java.util.Formatter}. A mismatch in type information will cause this
|
* message to render without argument substitution. Before using this method
|
* you should be sure that the message you are creating is not locale
|
* sensitive. If it is locale sensitive consider defining an appropriate
|
* {@link LocalizableMessageDescriptor}.
|
*
|
* @param formatString
|
* The raw message format string.
|
* @param args
|
* The raw message parameters.
|
* @return An uninternationalized messages whose {@code String} representation
|
* is always the same regardless of the requested locale.
|
* @throws NullPointerException
|
* If {@code formatString} was {@code null}.
|
*/
|
public static LocalizableMessage raw(final CharSequence formatString,
|
final Object... args) throws NullPointerException
|
{
|
Validator.ensureNotNull(formatString);
|
return new LocalizableMessageDescriptor.Raw(formatString).get(args);
|
}
|
|
|
|
/**
|
* Creates a new message whose content is the {@code String} representation of
|
* the provided {@code Object}.
|
*
|
* @param object
|
* The object to be converted to a message, may be {@code null}.
|
* @return The new message.
|
*/
|
public static LocalizableMessage valueOf(final Object object)
|
{
|
if (object instanceof LocalizableMessage)
|
{
|
return (LocalizableMessage) object;
|
}
|
else if (object instanceof LocalizableMessageBuilder)
|
{
|
return ((LocalizableMessageBuilder) object).toMessage();
|
}
|
else
|
{
|
return new LocalizableMessageDescriptor.Raw(String.valueOf(object)).get();
|
}
|
}
|
|
|
|
/**
|
* Returns whether we are running post 1.5 on AIX or not.
|
*
|
* @return {@code true} if we are running post 1.5 on AIX and {@code false}
|
* otherwise.
|
*/
|
private static boolean isAIXPost5()
|
{
|
// TODO: remove this code once the JDK issue referenced in 3077 is
|
// closed.
|
boolean isJDK15 = false;
|
try
|
{
|
final String javaRelease = System.getProperty("java.version");
|
isJDK15 = javaRelease.startsWith("1.5");
|
}
|
catch (final Throwable t)
|
{
|
System.err.println("Cannot get the java version: " + t);
|
}
|
final boolean isAIX = "aix".equalsIgnoreCase(System.getProperty("os.name"));
|
return !isJDK15 && isAIX;
|
}
|
|
|
|
// Descriptor of this message.
|
private final LocalizableMessageDescriptor descriptor;
|
|
// Values used to replace argument specifiers in the format string.
|
private final Object[] args;
|
|
|
|
/**
|
* Creates a new parameterized message instance. See the class header for
|
* instructions on how to create messages outside of this package.
|
*
|
* @param descriptor
|
* The message descriptor.
|
* @param args
|
* The message parameters.
|
*/
|
private LocalizableMessage(final LocalizableMessageDescriptor descriptor,
|
final Object... args)
|
{
|
this.descriptor = descriptor;
|
this.args = args;
|
}
|
|
|
|
/**
|
* Returns the {@code char} value at the specified index of the {@code String}
|
* representation of this message in the default locale.
|
*
|
* @param index
|
* The index of the {@code char} value to be returned.
|
* @return The specified {@code char} value.
|
* @throws IndexOutOfBoundsException
|
* If the {@code index} argument is negative or not less than
|
* {@code length()}.
|
*/
|
public char charAt(final int index) throws IndexOutOfBoundsException
|
{
|
return charAt(Locale.getDefault(), index);
|
}
|
|
|
|
/**
|
* Returns the {@code char} value at the specified index of the {@code String}
|
* representation of this message in the specified locale.
|
*
|
* @param locale
|
* The locale.
|
* @param index
|
* The index of the {@code char} value to be returned.
|
* @return The specified {@code char} value.
|
* @throws IndexOutOfBoundsException
|
* If the {@code index} argument is negative or not less than
|
* {@code length()}.
|
* @throws NullPointerException
|
* If {@code locale} was {@code null}.
|
*/
|
public char charAt(final Locale locale, final int index)
|
throws IndexOutOfBoundsException, NullPointerException
|
{
|
return toString(locale).charAt(index);
|
}
|
|
|
|
/**
|
* Compares this message with the specified message for order in the default
|
* locale. Returns a negative integer, zero, or a positive integer as this
|
* object is less than, equal to, or greater than the specified object.
|
*
|
* @param message
|
* The message to be compared.
|
* @return A negative integer, zero, or a positive integer as this object is
|
* less than, equal to, or greater than the specified object.
|
*/
|
public int compareTo(final LocalizableMessage message)
|
{
|
return toString().compareTo(message.toString());
|
}
|
|
|
|
/**
|
* Returns {@code true} if the provided object is a message whose {@code
|
* String} representation is equal to the {@code String} representation of
|
* this message in the default locale.
|
*
|
* @param o
|
* The object to be compared for equality with this message.
|
* @return {@code true} if this message is the equal to {@code o}, otherwise
|
* {@code false}.
|
*/
|
@Override
|
public boolean equals(final Object o)
|
{
|
if (this == o)
|
{
|
return true;
|
}
|
else if (o instanceof LocalizableMessage)
|
{
|
final LocalizableMessage message = (LocalizableMessage) o;
|
return toString().equals(message.toString());
|
}
|
else
|
{
|
return false;
|
}
|
}
|
|
|
|
/**
|
* Formats this message using the provided {@link Formatter}.
|
*
|
* @param formatter
|
* The {@link Formatter}.
|
* @param flags
|
* The flags modify the output format. The value is interpreted as a
|
* bitmask. Any combination of the following flags may be set:
|
* {@link java.util.FormattableFlags#LEFT_JUSTIFY},
|
* {@link java.util.FormattableFlags#UPPERCASE}, and
|
* {@link java.util.FormattableFlags#ALTERNATE}. If no flags are set,
|
* the default formatting of the implementing class will apply.
|
* @param width
|
* The minimum number of characters to be written to the output. If
|
* the length of the converted value is less than the {@code width}
|
* then the output will be padded by white space until the total
|
* number of characters equals width. The padding is at the beginning
|
* by default. If the {@link java.util.FormattableFlags#LEFT_JUSTIFY}
|
* flag is set then the padding will be at the end. If {@code width}
|
* is {@code -1} then there is no minimum.
|
* @param precision
|
* The maximum number of characters to be written to the output. The
|
* precision is applied before the width, thus the output will be
|
* truncated to {@code precision} characters even if the {@code
|
* width} is greater than the {@code precision}. If {@code precision}
|
* is {@code -1} then there is no explicit limit on the number of
|
* characters.
|
* @throws IllegalFormatException
|
* If any of the parameters are invalid. For specification of all
|
* possible formatting errors, see the <a
|
* href="../util/Formatter.html#detail">Details</a> section of the
|
* formatter class specification.
|
*/
|
public void formatTo(final Formatter formatter, final int flags,
|
final int width, final int precision) throws IllegalFormatException
|
{
|
// Ignores flags, width and precision for now.
|
// see javadoc for Formattable
|
final Locale l = formatter.locale();
|
formatter.format(l, descriptor.getFormatString(l), args);
|
}
|
|
|
|
/**
|
* Returns the hash code value for this message calculated using the hash code
|
* of the {@code String} representation of this message in the default locale.
|
*
|
* @return The hash code value for this message.
|
*/
|
@Override
|
public int hashCode()
|
{
|
return toString().hashCode();
|
}
|
|
|
|
/**
|
* Returns the length of the {@code String} representation of this message in
|
* the default locale.
|
*
|
* @return The length of the {@code String} representation of this message in
|
* the default locale.
|
*/
|
public int length()
|
{
|
return length(Locale.getDefault());
|
}
|
|
|
|
/**
|
* Returns the length of the {@code String} representation of this message in
|
* the specified locale.
|
*
|
* @param locale
|
* The locale.
|
* @return The length of the {@code String} representation of this message in
|
* the specified locale.
|
* @throws NullPointerException
|
* If {@code locale} was {@code null}.
|
*/
|
public int length(final Locale locale) throws NullPointerException
|
{
|
return toString(locale).length();
|
}
|
|
|
|
/**
|
* Returns a new {@code CharSequence} which is a subsequence of the {@code
|
* String} representation of this message in the default locale. The
|
* subsequence starts with the {@code char} value at the specified index and
|
* ends with the {@code char} value at index {@code end - 1} . The length (in
|
* {@code char}s) of the returned sequence is {@code end - start}, so if
|
* {@code start == end} then an empty sequence is returned.
|
*
|
* @param start
|
* The start index, inclusive.
|
* @param end
|
* The end index, exclusive.
|
* @return The specified subsequence.
|
* @throws IndexOutOfBoundsException
|
* If {@code start} or {@code end} are negative, if {@code end} is
|
* greater than {@code length()}, or if {@code start} is greater
|
* than {@code end}.
|
*/
|
public CharSequence subSequence(final int start, final int end)
|
throws IndexOutOfBoundsException
|
{
|
return subSequence(Locale.getDefault(), start, end);
|
}
|
|
|
|
/**
|
* Returns a new {@code CharSequence} which is a subsequence of the {@code
|
* String} representation of this message in the specified locale. The
|
* subsequence starts with the {@code char} value at the specified index and
|
* ends with the {@code char} value at index {@code end - 1} . The length (in
|
* {@code char}s) of the returned sequence is {@code end - start}, so if
|
* {@code start == end} then an empty sequence is returned.
|
*
|
* @param locale
|
* The locale.
|
* @param start
|
* The start index, inclusive.
|
* @param end
|
* The end index, exclusive.
|
* @return The specified subsequence.
|
* @throws IndexOutOfBoundsException
|
* If {@code start} or {@code end} are negative, if {@code end} is
|
* greater than {@code length()}, or if {@code start} is greater
|
* than {@code end}.
|
* @throws NullPointerException
|
* If {@code locale} was {@code null}.
|
*/
|
public CharSequence subSequence(final Locale locale, final int start,
|
final int end) throws IndexOutOfBoundsException, NullPointerException
|
{
|
return toString(locale).subSequence(start, end);
|
}
|
|
|
|
/**
|
* Returns the {@code String} representation of this message in the default
|
* locale.
|
*
|
* @return The {@code String} representation of this message.
|
*/
|
@Override
|
public String toString()
|
{
|
return toString(Locale.getDefault());
|
}
|
|
|
|
/**
|
* Returns the {@code String} representation of this message in the specified
|
* locale.
|
*
|
* @param locale
|
* The locale.
|
* @return The {@code String} representation of this message.
|
* @throws NullPointerException
|
* If {@code locale} was {@code null}.
|
*/
|
public String toString(final Locale locale) throws NullPointerException
|
{
|
String s;
|
final String fmt = descriptor.getFormatString(locale);
|
if (descriptor.requiresFormatter())
|
{
|
try
|
{
|
// TODO: remove this code once the JDK issue referenced in 3077
|
// is closed.
|
if (IS_AIX_POST5)
|
{
|
// Java 6 in AIX Formatter does not handle properly
|
// Formattable arguments; this code is a workaround for the
|
// problem.
|
boolean changeType = false;
|
for (final Object o : args)
|
{
|
if (o instanceof Formattable)
|
{
|
changeType = true;
|
break;
|
}
|
}
|
if (changeType)
|
{
|
final Object[] newArgs = new Object[args.length];
|
for (int i = 0; i < args.length; i++)
|
{
|
if (args[i] instanceof Formattable)
|
{
|
newArgs[i] = args[i].toString();
|
}
|
else
|
{
|
newArgs[i] = args[i];
|
}
|
}
|
s = new Formatter(locale).format(locale, fmt, newArgs).toString();
|
}
|
else
|
{
|
s = new Formatter(locale).format(locale, fmt, args).toString();
|
}
|
}
|
else
|
{
|
s = new Formatter(locale).format(locale, fmt, args).toString();
|
}
|
}
|
catch (final IllegalFormatException e)
|
{
|
// This should not happend with any of our internal messages.
|
// However, this may happen for raw messages that have a
|
// mismatch between argument specifier type and argument type.
|
s = fmt;
|
}
|
}
|
else
|
{
|
s = fmt;
|
}
|
if (s == null)
|
{
|
s = "";
|
}
|
return s;
|
}
|
|
}
|
