KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > runtime > content > IContentDescription


1 /*******************************************************************************
2  * Copyright (c) 2004, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.core.runtime.content;
12
13 import org.eclipse.core.internal.content.IContentConstants;
14 import org.eclipse.core.runtime.QualifiedName;
15
16 /**
17  * A content description object contains information about the nature of
18  * arbitrary data.
19  * <p>
20  * A content description object will always include the content type for the
21  * examined contents, and may also include information on:
22  * <ol>
23  * <li>charset;</li>
24  * <li>byte order mark;</li>
25  * <li>other custom properties provided by third-party plug-ins.</li>
26  * </ol>
27  * </p>
28  * <p>
29  * <cite>Content describers</cite> provided by plug-ins will fill in most of the
30  * properties in a content description object, except for the content type,
31  * what is done by the platform. After a content
32  * description is filled in by a content interpreter, it is marked as immutable
33  * by the platform, so calling any of the mutator methods defined in this
34  * interface will cause an <code>IllegalStateException</code> to be thrown.
35  * </p>
36  * <p>
37  * Default values for properties can be contributed by plug-ins as part of
38  * the content type definition markup.
39  * </p>
40  * <p>
41  * This interface is not intended to be implemented by clients.
42  * </p>
43  *
44  * @see IContentDescriber
45  * @since 3.0
46  */
47 public interface IContentDescription {
48     /**
49      * Key for the "charset" property.
50      */
51     public final static QualifiedName CHARSET = new QualifiedName(IContentConstants.RUNTIME_NAME, "charset"); //$NON-NLS-1$
52 /**
53      * Key for the "byte order mark" property. This property is only meaningful
54      * when describing byte streams.
55      */
56     public final static QualifiedName BYTE_ORDER_MARK = new QualifiedName(IContentConstants.RUNTIME_NAME, "bom"); //$NON-NLS-1$
57 /**
58      * Options constant meaning that all properties should be described.
59      */
60     public final static QualifiedName[] ALL = null;
61     /**
62      * Constant that identifies the Byte-Order-Mark for contents encoded with
63      * the UTF-8 character encoding scheme.
64      */
65     public final static byte[] BOM_UTF_8 = {(byte) 0xEF, (byte) 0xBB, (byte) 0xBF};
66     /**
67      * Constant that identifies the Byte-Order-Mark for contents encoded with
68      * the UTF-16 Big Endian character encoding scheme.
69      */
70     public final static byte[] BOM_UTF_16BE = {(byte) 0xFE, (byte) 0xFF};
71     /**
72      * Constant that identifies the Byte-Order-Mark for contents encoded with
73      * the UTF-16 Little Endian character encoding scheme.
74      */
75     public final static byte[] BOM_UTF_16LE = {(byte) 0xFF, (byte) 0xFE};
76
77     /**
78      * Returns whether the given property is requested to be described. This
79      * method is intended to allow content describers to determine which
80      * properties should be described.
81      *
82      * @param key a key for the property to be verified
83      * @return <code>true</code> if the property is to be described,
84      * <code>false</code> otherwise
85      */
86     public boolean isRequested(QualifiedName key);
87
88     /**
89      * Returns the charset name to be used when reading the contents
90      * described by this object.
91      * <p>
92      * If a Unicode byte order mark has been found (the
93      * <code>BYTE_ORDER_MARK</code> property has been set),
94      * a corresponding charset name will be returned (e.g. "UTF-8",
95      * "UTF-16"). Otherwise, the value of the <code>CHARSET</code>
96      * property will be returned.
97      * </p>
98      * @return a charset name, or <code>null</code>
99      */
100     public String JavaDoc getCharset();
101
102     /**
103      * Returns the content type detected. Returns <code>null</code> if the
104      * content type could not be determined.
105      *
106      * @return the corresponding content type, or <code>null</code>
107      */
108     public IContentType getContentType();
109
110     /**
111      * Returns the value of custom property set by the content describer,
112      * or the default value for the property, if one has been defined.
113      * <p>
114      * The qualifier part of the property name must be the unique identifier
115      * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
116      * </p>
117      *
118      * @param key the property key
119      * @return the property value, or <code>null</code>, if the property is not
120      * found
121      */
122     public Object JavaDoc getProperty(QualifiedName key);
123
124     /**
125      * Sets the given property to the given value.
126      * <p>
127      * The qualifier part of the property name must be the unique identifier
128      * of the declaring plug-in (e.g. <code>"com.example.plugin"</code>).
129      * </p>
130      * <p>
131      * This method should not be called by clients other than content
132      * describers. An attempt to set a property from other contexts will cause
133      * an <code>IllegalStateException</code> to be thrown.
134      * </p>
135      *
136      * @param key the qualified name of the property
137      * @param value the property value, or <code>null</code>,
138      * if the property is to be removed
139      * @throws IllegalStateException if called after this description has been
140      * filled in
141      */
142     public void setProperty(QualifiedName key, Object JavaDoc value);
143 }
144
Popular Tags