1 /******************************************************************************* 2 * Copyright (c) 2004, 2009 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.core.runtime.content; 15 16 import java.util.EventObject; 17 import org.eclipse.core.runtime.CoreException; 18 import org.eclipse.core.runtime.preferences.IScopeContext; 19 20 /** 21 * The content type manager provides facilities for file name and content-based 22 * type lookup and content description. 23 * <p> 24 * This interface is not intended to be implemented by clients. 25 * </p> 26 * 27 * @see org.eclipse.core.runtime.content.IContentTypeMatcher 28 * @since 3.0 29 * @noimplement This interface is not intended to be implemented by clients. 30 */ 31 public interface IContentTypeManager extends IContentTypeMatcher { 32 33 /** 34 * An event object which describes the details of a change to a 35 * content type. 36 * <p> 37 * Types of changes include a change in the file associations or 38 * a change in the encoding setting. 39 * </p> 40 */ 41 public final class ContentTypeChangeEvent extends EventObject { 42 /** 43 * All serializable objects should have a stable serialVersionUID 44 */ 45 private static final long serialVersionUID = 1L; 46 /* 47 * The context for the setting that changed. 48 * 49 * @since 3.1 50 */ 51 private IScopeContext context; 52 53 /** 54 * Constructor for a new content type change event. 55 * 56 * @param source the content type that changed 57 */ ContentTypeChangeEvent(IContentType source)58 public ContentTypeChangeEvent(IContentType source) { 59 super(source); 60 } 61 62 /** 63 * Constructor for a new content type change event. 64 * 65 * @param source the content type that changed 66 * @param context the context where a setting changed, or <code>null</code> 67 * @since 3.1 68 */ ContentTypeChangeEvent(IContentType source, IScopeContext context)69 public ContentTypeChangeEvent(IContentType source, IScopeContext context) { 70 super(source); 71 this.context = context; 72 } 73 74 /** 75 * Return the content type object associated with this change event. 76 * 77 * @return the content type 78 */ getContentType()79 public IContentType getContentType() { 80 return (IContentType) source; 81 } 82 83 /** 84 * Return the preference scope where the setting changed, or 85 * <code>null</code>, if the change happened in the content type manager 86 * default context. 87 * 88 * @return the context where the change happened, or <code>null</code> 89 * @since 3.1 90 */ getContext()91 public IScopeContext getContext() { 92 return context; 93 } 94 } 95 96 /** 97 * A listener to be used to receive content type change events. 98 * <p> 99 * Clients who reference the <code>org.eclipse.core.resources</code> 100 * bundle are encouraged <em>not</em> to use this listener mechanism to 101 * detect encoding changes. The Core Resources bundle will 102 * detect changes to content types and notify clients appropriately 103 * of potential changes to the encoding of files in the workspace 104 * via the resource change mechanism. 105 * </p> 106 * <p> 107 * Clients may implement this interface. 108 * </p> 109 */ 110 public interface IContentTypeChangeListener { 111 112 /** 113 * Notification that a content type has changed in the content type manager. 114 * The given event object contains the content type which changed and must not 115 * be <code>null</code>. 116 * 117 * @param event the content type change event 118 */ contentTypeChanged(ContentTypeChangeEvent event)119 void contentTypeChanged(ContentTypeChangeEvent event); 120 } 121 122 /** 123 * A policy for refining the set of content types that 124 * should be accepted during content type matching operations. 125 * <p> 126 * Clients may implement this interface. 127 * </p> 128 * 129 * @see IContentTypeManager#getMatcher(IContentTypeManager.ISelectionPolicy, IScopeContext) 130 * @since 3.1 131 */ 132 public interface ISelectionPolicy { 133 /** 134 * Returns a subset of the given content types sorted by using a custom criterion. 135 * <p> 136 * The given array of content types has already been sorted using 137 * the platform rules. If this object follows the same rules, further sorting 138 * is not necessary. 139 * </p> 140 * <p> 141 * The type of matching being performed (name, contents or name + contents) 142 * might affect the outcome for this method. For instance, for file name-only 143 * matching, the more general type could have higher priority. For content-based 144 * matching, the more specific content type could be preferred instead. 145 * </p> 146 * 147 * @param candidates an array containing content types matching some query 148 * @param fileName whether it is a file name-based content type matching 149 * @param content whether its a content-based content type matching 150 * @return an array of content types 151 */ select(IContentType[] candidates, boolean fileName, boolean content)152 IContentType[] select(IContentType[] candidates, boolean fileName, boolean content); 153 } 154 155 /** 156 * Content type identifier constant for platform's primary text-based content 157 * type: <code>org.eclipse.core.runtime.text</code>. 158 * <p> 159 * All text-based content types ought to be sub types of the content type 160 * identified by this string. This provides a simple way for detecting whether a 161 * content type is text-based: 162 * </p> 163 * 164 * <pre> 165 * IContentType text = Platform.getContentTypeManager().getContentType(IContentTypeManager.CT_TEXT); 166 * IContentType someType = ...; 167 * boolean isTextBased = someType.isKindOf(text); 168 * </pre> 169 */ 170 String CT_TEXT = "org.eclipse.core.runtime.text"; //$NON-NLS-1$ 171 172 /** 173 * Register the given listener for notification of content type changes. 174 * Calling this method multiple times with the same listener has no effect. The 175 * given listener argument must not be <code>null</code>. 176 * 177 * @param listener the content type change listener to register 178 * @see #removeContentTypeChangeListener(IContentTypeManager.IContentTypeChangeListener) 179 * @see IContentTypeManager.IContentTypeChangeListener 180 */ addContentTypeChangeListener(IContentTypeChangeListener listener)181 void addContentTypeChangeListener(IContentTypeChangeListener listener); 182 183 /** 184 * Returns all content types known by the platform. 185 * <p> 186 * Returns an empty array if there are no content types available. 187 * </p> 188 * 189 * @return all content types known by the platform. 190 */ getAllContentTypes()191 IContentType[] getAllContentTypes(); 192 193 /** 194 * Returns the content type with the given identifier, or <code>null</code> 195 * if no such content type is known by the platform. 196 * 197 * @param contentTypeIdentifier the identifier for the content type 198 * @return the content type, or <code>null</code> 199 */ getContentType(String contentTypeIdentifier)200 IContentType getContentType(String contentTypeIdentifier); 201 202 /** 203 * Returns a newly created content type matcher using the given content type selection policy 204 * and preference scope. If the preference scope is <code>null</code>, the default scope 205 * is used. 206 * 207 * @param customPolicy a selection policy 208 * @param context a user preference context to be used by the matcher, or <code>null</code> 209 * @return a content type matcher that uses the given policy 210 * @since 3.1 211 */ getMatcher(ISelectionPolicy customPolicy, IScopeContext context)212 IContentTypeMatcher getMatcher(ISelectionPolicy customPolicy, IScopeContext context); 213 214 /** 215 * De-register the given listener from receiving notification of content type changes. 216 * Calling this method multiple times with the same listener has no 217 * effect. The given listener argument must not be <code>null</code>. 218 * 219 * @param listener the content type change listener to remove 220 * @see #addContentTypeChangeListener(IContentTypeManager.IContentTypeChangeListener) 221 * @see IContentTypeManager.IContentTypeChangeListener 222 */ removeContentTypeChangeListener(IContentTypeChangeListener listener)223 void removeContentTypeChangeListener(IContentTypeChangeListener listener); 224 225 /** 226 * Adds a new content-type to the registry. The content-type identifier 227 * mustn't be used by any existing content-type. 228 * 229 * @param contentTypeIdentifier 230 * the non-null content-type id 231 * @param name 232 * the non-null user readable name 233 * @param baseType 234 * parent base type. May be null, indicating that there is no 235 * base type. 236 * @return the newly created and registered content-type 237 * @throws CoreException 238 * If the type was not added due to an internal error. 239 * @since 3.6 240 */ addContentType(String contentTypeIdentifier, String name, IContentType baseType)241 IContentType addContentType(String contentTypeIdentifier, String name, IContentType baseType) 242 throws CoreException; 243 244 /** 245 * Removes a content-type from underlying registry. 246 * 247 * The content-type must be a content-type that was previously defined with 248 * the {@link #addContentType(String, String, IContentType)} on the same 249 * IContentTypeManager. Content-types defined via extension point cannot be 250 * removed from the registry. 251 * 252 * @param contentTypeIdentifier 253 * the identifier of the content-type to remove. If no 254 * user-defined content-type exists for this identifier, the 255 * method returns changing nothing and will not throw an 256 * exception. 257 * @throws IllegalArgumentException 258 * if the target content-type was not created by user. 259 * @throws CoreException 260 * if an internal error prevented the content-type from being 261 * removed. 262 * @since 3.6 263 */ removeContentType(String contentTypeIdentifier)264 void removeContentType(String contentTypeIdentifier) throws CoreException; 265 } 266