/*
 * 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 2008 Sun Microsystems, Inc.
 */

package com.sun.opends.sdk.util;



import java.util.Formattable;
import java.util.Formatter;
import java.util.IllegalFormatException;
import java.util.Locale;



/**
 * Renders sensitive textural strings. In most cases message are
 * intended to render textural strings in a locale-sensitive manner
 * although this class defines convenience methods for creating
 * uninternationalized <code>Message</code> objects that render the same
 * text regardless of the requested locale. This class implements
 * <code>CharSequence</code> 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 MessageDescriptor
 */
public final class Message implements CharSequence, Formattable,
    Comparable<Message>
{

  /** Represents an empty message string. */
  public static final Message EMPTY = Message.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 final boolean isAIXPost5 = isAIXPost5();



  /**
   * Creates an uninternationalized message that will render itself the
   * same way regardless of the locale requested in
   * <code>toString(Locale)</code>. The message will have a category of
   * <code>Category.USER_DEFINED</code> and a severity of
   * <code>Severity.INFORMATION</code> Note that the types for
   * <code>args</code> must be consistent with any argument specifiers
   * appearing in <code>formatString</code> according to the rules of
   * 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
   * locale sensitive. If so you should instead create a formal message.
   *
   * @param formatString
   *          of the message or the message itself if not arguments are
   *          necessary
   * @param args
   *          any arguments for the format string
   * @return a message object that will render the same in all locales;
   *         null if <code>formatString</code> is null
   */
  static public Message raw(CharSequence formatString, Object... args)
  {
    Message message = null;
    if (formatString != null)
    {
      message = new MessageDescriptor.Raw(formatString).get(args);
    }
    return message;
  }



  /**
   * Creates an uninternationalized message from the string
   * representation of an object. Note that the types for
   * <code>args</code> must be consistent with any argument specifiers
   * appearing in <code>formatString</code> according to the rules of
   * java.util.Formatter. A mismatch in type information will cause this
   * message to render without argument substitution.
   *
   * @param object
   *          from which the message will be created
   * @param arguments
   *          for message
   * @return a message object that will render the same in all locales;
   *         null if <code>object</code> is null
   */
  static public Message fromObject(Object object, Object... arguments)
  {
    Message message = null;
    if (object != null)
    {
      CharSequence cs = object.toString();
      message = raw(cs, arguments);
    }
    return message;
  }



  /**
   * Returns the string representation of the message in the default
   * locale.
   *
   * @param message
   *          to stringify
   * @return String representation of of <code>message</code> of null if
   *         <code>message</code> is null
   */
  static public String toString(Message message)
  {
    return message != null ? message.toString() : null;
  }



  /** Descriptor of this message. */
  private final MessageDescriptor descriptor;

  /** Values used to replace argument specifiers in the format string. */
  private final Object[] args;



  /**
   * Gets the string representation of this message.
   *
   * @return String representation of this message
   */
  public String toString()
  {
    return toString(Locale.getDefault());
  }



  /**
   * Gets the string representation of this message appropriate for
   * <code>locale</code>.
   *
   * @param locale
   *          for which the string representation will be returned
   * @return String representation of this message
   */
  public String toString(Locale locale)
  {
    String s;
    String fmt = descriptor.getFormatString(locale);
    if (descriptor.requiresFormatter())
    {
      try
      {
        // TODO: remove this code once the JDK issue referenced in 3077
        // is
        // closed.
        if (isAIXPost5)
        {
          // Java 6 in AIX Formatter does not handle properly
          // Formattable
          // arguments; this code is a workaround for the problem.
          boolean changeType = false;
          for (Object o : args)
          {
            if (o instanceof Formattable)
            {
              changeType = true;
              break;
            }
          }
          if (changeType)
          {
            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 (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;
  }



  /**
   * Gets the descriptor that holds descriptive information about this
   * message.
   *
   * @return MessageDescriptor information
   */
  public MessageDescriptor getDescriptor()
  {
    return this.descriptor;
  }



  /**
   * Returns the length of this message as rendered using the default
   * locale.
   *
   * @return the number of <code>char</code>s in this message
   */
  public int length()
  {
    return length(Locale.getDefault());
  }



  /**
   * Returns the byte representation of this messages in the default
   * locale.
   *
   * @return bytes for this message
   */
  public byte[] getBytes()
  {
    return toString().getBytes();
  }



  /**
   * Returns the <code>char</code> value at the specified index of this
   * message rendered using the default locale.
   *
   * @param index
   *          the index of the <code>char</code> value to be returned
   * @return the specified <code>char</code> value
   * @throws IndexOutOfBoundsException
   *           if the <tt>index</tt> argument is negative or not less
   *           than <tt>length()</tt>
   */
  public char charAt(int index) throws IndexOutOfBoundsException
  {
    return charAt(Locale.getDefault(), index);
  }



  /**
   * Returns a new <code>CharSequence</code> that is a subsequence of
   * this message rendered using the default locale. The subsequence
   * starts with the <code>char</code> value at the specified index and
   * ends with the <code>char</code> value at index <tt>end - 1</tt>.
   * The length (in <code>char</code>s) of the returned sequence is
   * <tt>end - start</tt>, so if <tt>start == end</tt> 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 <tt>start</tt> or <tt>end</tt> are negative, if
   *           <tt>end</tt> is greater than <tt>length()</tt>, or if
   *           <tt>start</tt> is greater than <tt>end</tt>
   */
  public CharSequence subSequence(int start, int end)
      throws IndexOutOfBoundsException
  {
    return subSequence(Locale.getDefault(), start, end);
  }



  /**
   * Returns the length of this message as rendered using a specific
   * locale.
   *
   * @param locale
   *          for which the rendering of this message will be used in
   *          determining the length
   * @return the number of <code>char</code>s in this message
   */
  public int length(Locale locale)
  {
    return toString(locale).length();
  }



  /**
   * Returns the <code>char</code> value at the specified index of this
   * message rendered using a specific.
   *
   * @param locale
   *          for which the rendering of this message will be used in
   *          determining the character
   * @param index
   *          the index of the <code>char</code> value to be returned
   * @return the specified <code>char</code> value
   * @throws IndexOutOfBoundsException
   *           if the <tt>index</tt> argument is negative or not less
   *           than <tt>length()</tt>
   */
  public char charAt(Locale locale, int index)
      throws IndexOutOfBoundsException
  {
    return toString(locale).charAt(index);
  }



  /**
   * Returns a new <code>CharSequence</code> that is a subsequence of
   * this message rendered using a specific locale. The subsequence
   * starts with the <code>char</code> value at the specified index and
   * ends with the <code>char</code> value at index <tt>end - 1</tt>.
   * The length (in <code>char</code>s) of the returned sequence is
   * <tt>end - start</tt>, so if <tt>start == end</tt> then an empty
   * sequence is returned.
   *
   * @param locale
   *          for which the rendering of this message will be used in
   *          determining the character
   * @param start
   *          the start index, inclusive
   * @param end
   *          the end index, exclusive
   * @return the specified subsequence
   * @throws IndexOutOfBoundsException
   *           if <tt>start</tt> or <tt>end</tt> are negative, if
   *           <tt>end</tt> is greater than <tt>length()</tt>, or if
   *           <tt>start</tt> is greater than <tt>end</tt>
   */
  public CharSequence subSequence(Locale locale, int start, int end)
      throws IndexOutOfBoundsException
  {
    return toString(locale).subSequence(start, end);
  }



  /**
   * Formats the object using the provided {@link Formatter formatter}.
   *
   * @param formatter
   *          The {@link Formatter 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 <tt>width</tt> then the output will be padded by <tt>'&nbsp;&nbsp;'</tt>
   *          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 <tt>width</tt>
   *          is <tt>-1</tt> 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 <tt>precision</tt>
   *          characters even if the <tt>width</tt> is greater than the
   *          <tt>precision</tt>. If <tt>precision</tt> is <tt>-1</tt>
   *          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 precission for now.
    // see javadoc for Formattable
    Locale l = formatter.locale();
    formatter.format(l, descriptor.getFormatString(l), args);
  }



  /**
   * Creates a parameterized instance. See the class header for
   * instructions on how to create messages outside this package.
   *
   * @param descriptor
   *          for this message
   * @param args
   *          arguments for replacing specifiers in the message's format
   *          string
   */
  Message(MessageDescriptor descriptor, Object... args)
  {
    this.descriptor = descriptor;
    this.args = args;
  }



  /**
   * Compares this object with the specified object for order. Returns a
   * negative integer, zero, or a positive integer as this object is
   * less than, equal to, or greater than the specified object.
   *
   * @param o
   *          the object 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(Message o)
  {
    return toString().compareTo(o.toString());
  }



  /**
   * Indicates whether some other message is "equal to" this one.
   * Messages are considered equal if their string representation in the
   * default locale are equal.
   *
   * @param o
   *          the reference object with which to compare.
   * @return <code>true</code> if this object is the same as the obj
   *         argument; <code>false</code> otherwise.
   * @see #hashCode()
   * @see java.util.Hashtable
   */
  public boolean equals(Object o)
  {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;

    Message message = (Message) o;

    return toString().equals(message.toString());
  }



  /**
   * Returns a hash code value for the object.
   *
   * @return a hash code value for this object.
   * @see java.lang.Object#equals(java.lang.Object)
   * @see java.util.Hashtable
   */
  public int hashCode()
  {
    int result;
    result = 31 * toString().hashCode();
    return result;
  }



  // TODO: remove this code once the JDK issue referenced in 3077 is
  // closed.
  /**
   * Returns whether we are running post 1.5 on AIX or not.
   *
   * @return <CODE>true</CODE> if we are running post 1.5 on AIX and
   *         <CODE>false</CODE> otherwise.
   */
  private boolean isAIXPost5()
  {
    boolean isJDK15 = false;
    try
    {
      String javaRelease = System.getProperty("java.version");
      isJDK15 = javaRelease.startsWith("1.5");
    }
    catch (Throwable t)
    {
      System.err.println("Cannot get the java version: " + t);
    }
    boolean isAIX = "aix".equalsIgnoreCase(System
        .getProperty("os.name"));
    return !isJDK15 && isAIX;
  }

}