KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*******************************************************************************
2  * Copyright (c) 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.*;
14 import org.eclipse.core.runtime.QualifiedName;
15 import org.eclipse.core.runtime.preferences.IScopeContext;
16
17 /**
18  * An object that performs content type matching queries.
19  * <p>
20  * This interface is not intended to be implemented by clients.
21  * </p>
22  *
23  * @see IContentTypeManager#getMatcher(IContentTypeManager.ISelectionPolicy, IScopeContext)
24  * @since 3.1
25  */
26 public interface IContentTypeMatcher {
27     /**
28      * Returns the preferred content type for the given contents and file name.
29      * <p>
30      * Returns <code>null</code> if no associated content types are
31      * found.
32      * </p>
33      * <p>
34      * If a file name is not provided, the entire content type registry will be
35      * queried. For performance reasons, it is highly recommended
36      * to provide a file name if available.
37      * </p>
38      * <p>
39      * Any IOExceptions that may occur while reading the given input stream
40      * will flow to the caller. The input stream will not be closed by this
41      * operation.
42      * </p>
43      *
44      * @param contents an input stream
45      * @param fileName the file name associated to the contents, or <code>null</code>
46      * @return the preferred content type associated to the given file name, or <code>null</code>
47      * @throws IOException if an error occurs while reading the contents
48      */
49     public IContentType findContentTypeFor(InputStream contents, String JavaDoc fileName) throws IOException;
50
51     /**
52      * Returns the preferred content type for the given file name. If multiple content types
53      * are associated with the given file name, the one considered the most appropriated will
54      * be returned. If there are no content types associated, <code>null</code> is returned.
55      *
56      * @param fileName the name of the file
57      * @return the preferred content type associated to the given file name, or <code>null</code>
58      */
59     public IContentType findContentTypeFor(String JavaDoc fileName);
60
61     /**
62      * Returns the content types associated to the given contents and file name.
63      * <p>
64      * Returns an empty array if no associated content types are found.
65      * </p>
66      * <p>
67      * If a file name is not provided, the entire content type registry will be
68      * queried. For performance reasons, it is highly recommended
69      * to provide a file name if available.
70      * </p>
71      * <p>
72      * Any IOExceptions that may occur while reading the given input stream
73      * will flow to the caller. The input stream will not be closed by this
74      * operation.
75      * </p>
76      *
77      * @param contents an input stream
78      * @param fileName the file name associated to the contents, or <code>null</code>
79      * @return all content types associated to the given contents and file name
80      * @throws IOException if an error occurs while reading the contents
81      */
82     public IContentType[] findContentTypesFor(InputStream contents, String JavaDoc fileName) throws IOException;
83
84     /**
85      * Returns all content types known by the platform that are associated to the given file name.
86      * <p>
87      * Returns an empty array if there are no content types associated.
88      * </p>
89      *
90      * @param fileName the name of the file
91      * @return all content types associated to the given file spec
92      */
93     public IContentType[] findContentTypesFor(String JavaDoc fileName);
94
95     /**
96      * Tries to obtain a description for the given contents and file name.
97      * <p>
98      * Any IOExceptions that may occur while reading the given input stream
99      * will flow to the caller. The input stream will not be closed by this
100      * operation.
101      * </p>
102      * <p>
103      * If a file name is not provided, the entire content type registry will be
104      * queried. For performance reasons, it is highly recommended
105      * to provide a file name if available.
106      * </p>
107      *
108      * @param contents the contents to be interpreted
109      * @param fileName the file name associated to the contents, or <code>null</code>
110      * @param options an array of keys for all properties that should be
111      * described, or <code>IContentDescription.ALL</code>, for all of them
112      * @return a content description if one could be obtained, or <code>null</code>
113      * @throws IOException if an error occurs while reading the contents
114      * @see IContentDescription
115      */
116     public IContentDescription getDescriptionFor(InputStream contents, String JavaDoc fileName, QualifiedName[] options) throws IOException;
117
118     /**
119      * Tries to obtain a description for the given contents and file name.
120      * <p>
121      * Any IOExceptions that may occur while reading the given input stream
122      * will flow to the caller. The reader will not be closed by this
123      * operation.
124      * </p>
125      * <p>
126      * If a file name is not provided, the entire content type registry will be
127      * queried. For performance reasons, it is highly recommended
128      * to provide a file name if available.
129      * </p>
130      *
131      * @param contents the contents to be interpreted
132      * @param fileName the file name associated to the contents, or <code>null</code>
133      * @param options an array of keys for all properties that should be
134      * described, or <code>IContentDescription.ALL</code>, for all of them
135      * @return a content description if one could be obtained, or <code>null</code>
136      * @throws IOException if an error occurs while reading the contents
137      * @see IContentDescription
138      */
139     public IContentDescription getDescriptionFor(Reader contents, String JavaDoc fileName, QualifiedName[] options) throws IOException;
140 }
Popular Tags