/*******************************************************************************
 * Copyright (c) 2001, 2004 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 * IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.wst.validation.core;


import java.util.Locale;

/**
 * <p>
 * This interface represents a locale-independent validation message.
 * </p>
 * <p>
 * Given these three values as input, this interface can be queried for the final message string.
 * (i.e., the message with the parameters already substituted in.) Either the default Locale can be
 * used, or the caller can specify a Locale.
 * </p>
 */
public interface IMessage {
	public static final int OFFSET_UNSET = -1; // see getLength(), getOffset()
	public static final int LINENO_UNSET = 0;

	/**
	 * @return the name of the bundle which this message is contained in.
	 */
	public String getBundleName();

	/**
	 * <p>
	 * To support removal of a subset of validation messages, an IValidator may assign group names
	 * to IMessages. An IMessage subset will be identified by the name of its group. Default (null)
	 * means no group.
	 * </p>
	 * @return the name of the group to which the message belongs.
	 */
	public String getGroupName();

	/**
	 * <p>
	 * Returns the id of the message. Message ids are used as the constants in property bundles
	 * which localize the description of the message in a locale-independent fashion. The id is the
	 * key, in the resource bundle, which identifies the string to be loaded. The id may not be null
	 * or the empty string.
	 * </p>
	 * @return the id of the message
	 */
	public java.lang.String getId();

	/**
	 * @return the length of the problem area, starting from the offset. If unset, value =
	 * IMessage.OFFSET_UNSET.
	 * 
	 * @see #getOffset()
	 */
	public int getLength();

	/**
	 * <p>
	 * If there is a target object associated with this IMessage, and that target object is a file,
	 * then an optional line number may be set. The line number identifies the location of the
	 * problem identified by this message. If no line number has been set, #LINENO_UNSET will be
	 * returned.
	 * </p>
	 * @return line number of the location of the problem.
	 */
	public int getLineNo();

	/**
	 * <p>
	 * Returns the offset of the message. If unset, value = IMessage.OFFSET_UNSET. For example, if
	 * the java compiler were a validator, and it reported that a variable name was unknown, offset
	 * would identify the position of the first character of the unknown variable. (The position is
	 * identified by the number of characters from the start of the file.)
	 * </p>
	 * 
	 * @return offset of the message
	 */
	public int getOffset();

	/**
	 * <p>
	 * Returns the parameters of the message. Message parameters are the values which are
	 * substituted into parameter slots in localized message text ddscriptions.
	 * </p>
	 * 
	 * @return parameters of the message
	 */
	public java.lang.String[] getParams();

	/**
	 * <p>
	 * Returns the severity level of the message. One of SeverityEnum constants.
	 * 
	 * @see SeverityEnum#HIGH_SEVERITY
	 * @see SeverityEnum#NORMAL_SEVERITY
	 * @see SeverityEnum#LOW_SEVERITY
	 * </p>
	 * 
	 * @return the severity level of the message
	 */
	public int getSeverity();

	/**
	 * <p>
	 * Return the object that this IMessage is reporting the problem against, if any. null will be
	 * returned if this is a general message which does not apply to a particular object; for
	 * example, "internal error".
	 * </p>
	 * 
	 * @return the target object for the message
	 */
	public Object getTargetObject();

	/**
	 * @return a text representation of this message formatted in the default Locale, with the
	 * bundle loaded by the default ClassLoader.
	 */
	public java.lang.String getText();

	/**
	 * @param classLoader 
	 * 				The ClassLoader which will be used to load the ResourceBundle.
	 *            
	 * @return a text representation of this message formatted in the default locale, with the
	 * bundle loaded by the specified ClassLoader.
	 */
	public java.lang.String getText(ClassLoader classLoader);

	/**
	 * @param locale
	 *            The locale to translate the message text into.
	 *            
	 * @return a text representation of this message formatted in the specified locale, with the
	 * bundle loaded by the default ClassLoader.
	 */
	public java.lang.String getText(Locale locale);

	/**
	 * @param locale
	 *            The locale to translate the message text into.
	 * @param classLoader
	 *            The ClassLoader which will be used to load the ResourceBundle.
	 *            
	 * @return a text representation of this message formatted in the specified locale, with the
	 * bundle loaded by the specified ClassLoader.
	 */
	public java.lang.String getText(Locale locale, ClassLoader classLoader);

	/**
	 * Set the name of the bundle which this message is contained in.
	 * 
	 * @param bundleName 
	 * 			Name of the bundle which contains the message.
	 */
	public void setBundleName(String bundleName);

	/**
	 * <p>
	 * To support removal of a subset of validation messages, an IValidator may assign group names
	 * to IMessages. An IMessage subset will be identified by the name of its group. Default (null)
	 * means no group.
	 * </p>
	 * 
	 * @param name
	 * 			Name of the group.
	 */
	public void setGroupName(String name);

	/**
	 * <p>
	 * Set the id of the message. Message ids are used as the constants in property bundles which
	 * localize the description of the message in a locale-independent fashion. The id is the key,
	 * in the resource bundle, which identifies the string to be loaded. The id may not be null or
	 * the empty string.
	 * </p>
	 * 
	 * @param newId
	 *            Id of the message.
	 */
	public void setId(java.lang.String newId);

	/**
	 * <p>
	 * Sets the length of the problem, starting from the offset. If unset, value =
	 * IMessage.OFFSET_UNSET.
	 * 
	 * @see #setOffset(int)
	 * </p>
	 * 
	 * @param length 
	 *			sets the length 		
	 */
	public void setLength(int length);

	/**
	 * <p>
	 * If there is a target object associated with this IMessage, and that target object is a file,
	 * then an optional line number may be set. The line number identifies the location of the
	 * problem identified by this message. To indicate no line number, use #LINENO_UNSET.
	 * </p>
	 * @param lineNumber 
	 *			sets the line no. 	
	 */
	public void setLineNo(int lineNumber);

	/**
	 * <p>
	 * Sets the offset of the message. If unset, value = IMessage.OFFSET_UNSET. For example, if the
	 * java compiler were a validator, and it reported that a variable name was unknown, offset
	 * would identify the position of the first character of the unknown variable. (The position is
	 * identified by the number of characters from the start of the file.)
	 * </p>
	 * @param offset 
	 *			sets the offset of the message.
	 */
	public void setOffset(int offset);

	/**
	 * <p>
	 * Sets the parameters of the message. Message parameters are the values which are substituted
	 * into parameter slots in localized message text descriptions.
	 * </p>
	 * <p>
	 * For example, if getId() returns "MY_ID", then the ResourceBundle identified by
	 * getBundleName() is searched for the message named "MY_ID", and if found,
	 * </p>
	 * 
	 * @see java.text.MessageFormat#format(String, Object[]) is invoked on the message, with
	 *      <code>newParams</code> passed in as the Object[].
	 * @param newParams
	 *            parameters of the message.
	 */
	public void setParams(java.lang.String[] newParams);

	/**
	 * Sets the severity level of the message. One of SeverityEnum constants.
	 * 
	 * @see SeverityEnum#HIGH_SEVERITY
	 * @see SeverityEnum#NORMAL_SEVERITY
	 * @see SeverityEnum#LOW_SEVERITY
	 * 
	 * @param newSeverity
	 *            severity level of the message
	 */
	public void setSeverity(int newSeverity);

	/**
	 * <p>
	 * Associate this IMessage with the object that has the problem. A null value is permitted. If a
	 * message is applicable to one object, then this value should be set. Otherwise, the default
	 * value (null) should be kept. Given this target object, it should be possible to calculate the
	 * exact location of the problem.
	 * </p>
	 * 
	 * @param obj
	 *         The object that has the problem.
	 */
	public void setTargetObject(Object obj);
}