/*******************************************************************************
 * Copyright (c) 2004, 2005 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.runtime.content;

import org.eclipse.core.internal.content.IContentConstants;
import org.eclipse.core.runtime.QualifiedName;

/**
 * A content description object contains information about the nature of
 * arbitrary data.
 * <p>
 * A content description object will always include the content type for the
 * examined contents, and may also include information on:
 * <ol>
 * <li>charset;</li>
 * <li>byte order mark;</li>
 * <li>other custom properties provided by third-party plug-ins.</li>
 * </ol>
 * </p>
 * <p>
 * <cite>Content describers</cite> provided by plug-ins will fill in most of the
 * properties in a content description object, except for the content type,
 * what is done by the platform. After a content
 * description is filled in by a content interpreter, it is marked as immutable
 * by the platform, so calling any of the mutator methods defined in this
 * interface will cause an <code>IllegalStateException</code> to be thrown.
 * </p>
 * <p>
 * Default values for properties can be contributed by plug-ins as part of
 * the content type definition markup.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 *
 * @see IContentDescriber
 * @since 3.0
 */
public interface IContentDescription {
	/**
	 * Key for the "charset" property.
	 */
	QualifiedName CHARSET = new QualifiedName(IContentConstants.RUNTIME_NAME, "charset"); //$NON-NLS-1$
	/**
	 * Key for the "byte order mark" property. This property is only meaningful
	 * when describing byte streams.
	 */
	QualifiedName BYTE_ORDER_MARK = new QualifiedName(IContentConstants.RUNTIME_NAME, "bom"); //$NON-NLS-1$
	/**
	 * Options constant meaning that all properties should be described.
	 */
	QualifiedName[] ALL = null;
	/**
	 * Constant that identifies the Byte-Order-Mark for contents encoded with
	 * the UTF-8 character encoding scheme.
	 */
	byte[] BOM_UTF_8 = {(byte) 0xEF, (byte) 0xBB, (byte) 0xBF};
	/**
	 * Constant that identifies the Byte-Order-Mark for contents encoded with
	 * the UTF-16 Big Endian character encoding scheme.
	 */
	byte[] BOM_UTF_16BE = {(byte) 0xFE, (byte) 0xFF};
	/**
	 * Constant that identifies the Byte-Order-Mark for contents encoded with
	 * the UTF-16 Little Endian character encoding scheme.
	 */
	byte[] BOM_UTF_16LE = {(byte) 0xFF, (byte) 0xFE};

	/**
	 * Returns whether the given property is requested to be described. This
	 * method is intended to allow content describers to determine  which
	 * properties should be described.
	 *
	 * @param key a key for the property to be verified
	 * @return <code>true</code> if the property is to be described,
	 * <code>false</code> otherwise
	 */
	boolean isRequested(QualifiedName key);

	/**
	 * Returns the charset name to be used when reading the contents
	 * described by this object.
	 * <p>
	 * If a Unicode byte order mark has been found (the
	 * <code>BYTE_ORDER_MARK</code> property has been set),
	 * a corresponding charset name will be returned (e.g. "UTF-8",
	 * "UTF-16"). Otherwise, the value of the <code>CHARSET</code>
	 * property will be returned.
	 * </p>
	 * @return a charset name, or <code>null</code>
	 */
	String getCharset();

	/**
	 * Returns the content type detected. Returns <code>null</code> if the
	 * content type could not be determined.
	 *
	 * @return the corresponding content type, or <code>null</code>
	 */
	IContentType getContentType();

	/**
	 * Returns the value of custom property set by the content describer,
	 * or the default value for the property, if one has been defined.
	 * <p>
	 * The qualifier part of the property name must be the unique identifier
	 * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
	 * </p>
	 *
	 * @param key the property key
	 * @return the property value, or <code>null</code>, if the property is not
	 * found
	 */
	Object getProperty(QualifiedName key);

	/**
	 * Sets the given property to the given value.
	 * <p>
	 * The qualifier part of the property name must be the unique identifier
	 * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
	 * </p>
	 * <p>
	 * This method should not be called by clients other than content
	 * describers. An attempt to set a property from other contexts will cause
	 * an <code>IllegalStateException</code> to be thrown.
	 * </p>
	 *
	 * @param key the qualified name of the property
	 * @param value the property value, or <code>null</code>,
	 * if the property is to be removed
	 * @throws IllegalStateException if called after this description has been
	 * filled in
	 */
	void setProperty(QualifiedName key, Object value);
}