KickJava   Java API By Example, From Geeks To Geeks.

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


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.util.EventObject JavaDoc;
14 import org.eclipse.core.runtime.preferences.IScopeContext;
15
16 /**
17  * The content type manager provides facilities for file name and content-based
18  * type lookup and content description.
19  * <p>
20  * This interface is not intended to be implemented by clients.
21  * </p>
22  *
23  * @see org.eclipse.core.runtime.content.IContentTypeMatcher
24  * @see org.eclipse.core.runtime.Platform#getContentTypeManager()
25  * @since 3.0
26  */
27 public interface IContentTypeManager extends IContentTypeMatcher {
28
29     /**
30      * An event object which describes the details of a change to a
31      * content type.
32      * <p>
33      * Types of changes include a change in the file associations or
34      * a change in the encoding setting.
35      * </p>
36      */
37     public final class ContentTypeChangeEvent extends EventObject JavaDoc {
38         /**
39          * All serializable objects should have a stable serialVersionUID
40          */
41         private static final long serialVersionUID = 1L;
42         /*
43          * The context for the setting that changed.
44          *
45          * @since 3.1
46          */
47         private IScopeContext context;
48
49         /**
50          * Constructor for a new content type change event.
51          *
52          * @param source the content type that changed
53          */
54         public ContentTypeChangeEvent(IContentType source) {
55             super(source);
56         }
57
58         /**
59          * Constructor for a new content type change event.
60          *
61          * @param source the content type that changed
62          * @param context the context where a setting changed, or <code>null</code>
63          * @since 3.1
64          */
65         public ContentTypeChangeEvent(IContentType source, IScopeContext context) {
66             super(source);
67             this.context = context;
68         }
69
70         /**
71          * Return the content type object associated with this change event.
72          *
73          * @return the content type
74          */
75         public IContentType getContentType() {
76             return (IContentType) source;
77         }
78
79         /**
80          * Return the preference scope where the setting changed, or
81          * <code>null</code>, if the change happened in the content type manager
82          * default context.
83          *
84          * @return the context where the change happened, or <code>null</code>
85          * @since 3.1
86          */
87         public IScopeContext getContext() {
88             return context;
89         }
90     }
91
92     /**
93      * A listener to be used to receive content type change events.
94      * <p>
95      * Clients who reference the <code>org.eclipse.core.resources</code>
96      * bundle are encouraged <em>not</em> to use this listener mechanism to
97      * detect encoding changes. The Core Resources bundle will
98      * detect changes to content types and notify clients appropriately
99      * of potential changes to the encoding of files in the workspace
100      * via the resource change mechanism.
101      * </p>
102      * <p>
103      * Clients may implement this interface.
104      * </p>
105      */
106     public interface IContentTypeChangeListener {
107
108         /**
109          * Notification that a content type has changed in the content type manager.
110          * The given event object contains the content type which changed and must not
111          * be <code>null</code>.
112          *
113          * @param event the content type change event
114          */
115         public void contentTypeChanged(ContentTypeChangeEvent event);
116     }
117
118     /**
119      * A policy for refining the set of content types that
120      * should be accepted during content type matching operations.
121      * <p>
122      * Clients may implement this interface.
123      * </p>
124      *
125      * @see IContentTypeManager#getMatcher(IContentTypeManager.ISelectionPolicy, IScopeContext)
126      * @since 3.1
127      */
128     public interface ISelectionPolicy {
129         /**
130          * Returns a subset of the given content types sorted by using a custom criterion.
131          * <p>
132          * The given array of content types has already been sorted using
133          * the platform rules. If this object follows the same rules, further sorting
134          * is not necessary.
135          * </p>
136          * <p>
137          * The type of matching being performed (name, contents or name + contents)
138          * might affect the outcome for this method. For instance, for file name-only
139          * matching, the more general type could have higher priority. For content-based
140          * matching, the more specific content type could be preferred instead.
141          * </p>
142          *
143          * @param candidates an array containing content types matching some query
144          * @param fileName whether it is a file name-based content type matching
145          * @param content whether its a content-based content type matching
146          * @return an array of content types
147          */
148         IContentType[] select(IContentType[] candidates, boolean fileName, boolean content);
149     }
150
151     /**
152      * Content type identifier constant for platform's primary
153      * text-based content type: <code>org.eclipse.core.runtime.text</code>.
154      * <p>
155      * All text-based content types ought to be sub types of the content type
156      * identified by this string. This provides a simple way for detecting
157      * whether a content type is text-based:
158      * <pre>
159      * IContentType text = Platform.getContentTypeManager().getContentType(IContentTypeManager.CT_TEXT);
160      * IContentType someType = ...;
161      * boolean isTextBased = someType.isKindOf(text);
162      * </pre>
163      * </p>
164      */
165     public final static String JavaDoc CT_TEXT = "org.eclipse.core.runtime.text"; //$NON-NLS-1$
166
167     /**
168      * Register the given listener for notification of content type changes.
169      * Calling this method multiple times with the same listener has no effect. The
170      * given listener argument must not be <code>null</code>.
171      *
172      * @param listener the content type change listener to register
173      * @see #removeContentTypeChangeListener(IContentTypeManager.IContentTypeChangeListener)
174      * @see IContentTypeManager.IContentTypeChangeListener
175      */
176     public void addContentTypeChangeListener(IContentTypeChangeListener listener);
177
178     /**
179      * Returns all content types known by the platform.
180      * <p>
181      * Returns an empty array if there are no content types available.
182      * </p>
183      *
184      * @return all content types known by the platform.
185      */
186     public IContentType[] getAllContentTypes();
187
188     /**
189      * Returns the content type with the given identifier, or <code>null</code>
190      * if no such content type is known by the platform.
191      *
192      * @param contentTypeIdentifier the identifier for the content type
193      * @return the content type, or <code>null</code>
194      */
195     public IContentType getContentType(String JavaDoc contentTypeIdentifier);
196
197     /**
198      * Returns a newly created content type matcher using the given content type selection policy
199      * and preference scope. If the preference scope is <code>null</code>, the default scope
200      * is used.
201      *
202      * @param customPolicy a selection policy
203      * @param context a user preference context to be used by the matcher, or <code>null</code>
204      * @return a content type matcher that uses the given policy
205      * @since 3.1
206      */
207     public IContentTypeMatcher getMatcher(ISelectionPolicy customPolicy, IScopeContext context);
208
209     /**
210      * De-register the given listener from receiving notification of content type changes.
211      * Calling this method multiple times with the same listener has no
212      * effect. The given listener argument must not be <code>null</code>.
213      *
214      * @param listener the content type change listener to remove
215      * @see #addContentTypeChangeListener(IContentTypeManager.IContentTypeChangeListener)
216      * @see IContentTypeManager.IContentTypeChangeListener
217      */
218     public void removeContentTypeChangeListener(IContentTypeChangeListener listener);
219 }
220
Popular Tags