KickJava   Java API By Example, From Geeks To Geeks.

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


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 java.io.IOException JavaDoc;
14 import java.io.InputStream JavaDoc;
15 import org.eclipse.core.runtime.QualifiedName;
16
17 /**
18  * Content describers know how to retrieve metadata from
19  * contents.
20  * <p>
21  * Note: It is expected that content describer implementations be declared in a package
22  * that is exempt from plug-in activation (using the Eclipse-AutoStart bundle
23  * manifest header). Since all describers are instantiated when the content type
24  * framework is initialized, failure in complying with this requirement causes
25  * premature activation, which must be avoided. Future implementations of the
26  * framework might refuse to instantiate describers if doing so would trigger
27  * activation of the corresponding plug-in.
28  * </p>
29  * <p>
30  * Describers for text-based content types should implement
31  * <code>ITextContentDescriber</code> instead.
32  * </p>
33  * <p>
34  * Clients may implement this interface.
35  * </p>
36
37  * @see IContentDescription
38  * @since 3.0
39  */
40 public interface IContentDescriber {
41     /**
42      * Description result constant, indicating that it was not possible
43      * to determine whether the contents were valid for
44      * the intended content type.
45      *
46      * @see #describe
47      */
48     public final static int INDETERMINATE = 1;
49     /**
50      * Description result constant, indicating the contents are invalid for
51      * the intended content type.
52      *
53      * @see #describe
54      */
55     public final static int INVALID = 0;
56     /**
57      * Description result constant, indicating the contents are valid for
58      * the intended content type.
59      *
60      * @see #describe
61      */
62     public final static int VALID = 2;
63
64     /**
65      * Tries to fill a description for the given contents. Returns
66      * an <code>int</code> indicating whether the given stream of
67      * bytes represents a valid sample for its corresponding content type.
68      * If no content description is provided, this method should perform
69      * content type validation.
70      * <p>
71      * The input stream must be kept open, and any IOExceptions while
72      * reading the stream should flow to the caller.
73      * </p>
74      *
75      * @param contents the contents to be examined
76      * @param description a description to be filled in, or <code>null</code> if
77      * only content type validation is to be performed
78      * @return one of the following:<ul>
79      * <li><code>VALID</code></li>,
80      * <li><code>INVALID</code></li>,
81      * <li><code>INDETERMINATE</code></li>
82      * </ul>
83      * @throws IOException if an I/O error occurs
84      * @see IContentDescription
85      * @see #VALID
86      * @see #INVALID
87      * @see #INDETERMINATE
88      */
89     public int describe(InputStream JavaDoc contents, IContentDescription description) throws IOException JavaDoc;
90
91     /**
92      * Returns the properties supported by this describer.
93      *
94      * @return the supported properties
95      * @see #describe
96      */
97     public QualifiedName[] getSupportedOptions();
98 }
99
Popular Tags