/*
 * 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.MESSAGE_FACTORY = new LocalizableMessageDescriptor.MessageFactory()
    {

      public LocalizableMessage newMessage(LocalizableMessageDescriptor descriptor,
          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(CharSequence formatString, Object... args)
  {
    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(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(LocalizableMessageDescriptor descriptor, 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(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(Locale locale, 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(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}.
   */
  public boolean equals(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(Formatter formatter, int flags, int width,
      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.
   */
  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(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(int start, 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(Locale locale, int start, 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.
   */
  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(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;
  }

}