/*
 * 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-2010 Sun Microsystems, Inc.
 *      Portions copyright 2011 ForgeRock AS
 */

package org.opends.messages;

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

/**
 * 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 org.opends.messages.MessageDescriptor
 */
@org.opends.server.types.PublicAPI(
    stability=org.opends.server.types.StabilityLevel.UNCOMMITTED,
    mayInstantiate=true,
    mayExtend=false,
    mayInvoke=true)
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 isAIX = isAIX();

  /**
   * 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) {
    return raw(Category.USER_DEFINED, Severity.INFORMATION, formatString, args);
  }

  /**
   * Creates an uninternationalized message that will render itself
   * the same way regardless of the locale requested in
   * <code>toString(Locale)</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 category of this message
   * @param severity of this 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(Category category, Severity severity,
                            CharSequence formatString, Object... args) {
    Message message = null;
    if (formatString != null) {
      if (args == null || args.length == 0)
      {
        MessageDescriptor.Raw md = new MessageDescriptor.Raw(
            "%s", category, severity);
        message = md.get(formatString);
      }
      else
      {
        MessageDescriptor.Raw md = new MessageDescriptor.Raw(
            formatString, category, severity);
        message = md.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 args 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... args) {
    return (object != null) ? raw(object.toString(), args) : null;
  }

  /**
   * 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
   */
  @Override
  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 (isAIX)
        {
          // 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
   */
  @Override
  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
   */
  @Override
  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 on AIX or not.
   * @return <CODE>true</CODE> if we are running on AIX and
   * <CODE>false</CODE> otherwise.
   */
  private boolean isAIX()
  {
    return "aix".equalsIgnoreCase(System.getProperty("os.name"));
  }

}