org.eclipse.core.runtime.content.IContentDescription Maven / Gradle / Ivy
Show all versions of aspectjtools Show documentation
/*******************************************************************************
* 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.
*
* A content description object will always include the content type for the
* examined contents, and may also include information on:
*
*
* - charset;
* - byte order mark;
* - other custom properties provided by third-party plug-ins.
*
*
* Content describers 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 IllegalStateException
to be thrown.
*
*
* Default values for properties can be contributed by plug-ins as part of
* the content type definition markup.
*
*
* This interface is not intended to be implemented by clients.
*
*
* @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 true
if the property is to be described,
* false
otherwise
*/
boolean isRequested(QualifiedName key);
/**
* Returns the charset name to be used when reading the contents
* described by this object.
*
* If a Unicode byte order mark has been found (the
* BYTE_ORDER_MARK
property has been set),
* a corresponding charset name will be returned (e.g. "UTF-8",
* "UTF-16"). Otherwise, the value of the CHARSET
* property will be returned.
*
* @return a charset name, or null
*/
String getCharset();
/**
* Returns the content type detected. Returns null
if the
* content type could not be determined.
*
* @return the corresponding content type, or null
*/
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.
*
* The qualifier part of the property name must be the unique identifier
* of the declaring plug-in (e.g. "com.example.plugin"
).
*
*
* @param key the property key
* @return the property value, or null
, if the property is not
* found
*/
Object getProperty(QualifiedName key);
/**
* Sets the given property to the given value.
*
* The qualifier part of the property name must be the unique identifier
* of the declaring plug-in (e.g. "com.example.plugin"
).
*
*
* This method should not be called by clients other than content
* describers. An attempt to set a property from other contexts will cause
* an IllegalStateException
to be thrown.
*
*
* @param key the qualified name of the property
* @param value the property value, or null
,
* if the property is to be removed
* @throws IllegalStateException if called after this description has been
* filled in
*/
void setProperty(QualifiedName key, Object value);
}