IModelProviderDescriptor.java

/*******************************************************************************
 * Copyright (c) 2005, 2009 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.resources.mapping;

import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;

/**
 * A model provider descriptor contains information about a model provider obtained from the plug-in
 * manifest (<code>plugin.xml</code>) file.
 * <p>
 * Model provider descriptors are platform-defined objects that exist independent of whether that
 * model provider's plug-in has been started. In contrast, a model provider's runtime object (
 * <code>ModelProvider</code>) generally runs plug-in-defined code.
 * </p>
 * 
 * @see org.eclipse.core.resources.mapping.ModelProvider
 * @since 3.2
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IModelProviderDescriptor {

	/**
	 * Return the ids of model providers that this model provider extends.
	 * 
	 * @return the ids of model providers that this model provider extends
	 */
	public String[] getExtendedModels();

	/**
	 * Returns the unique identifier of this model provider.
	 * <p>
	 * The model provider identifier is composed of the model provider's plug-in id and the simple
	 * id of the provider extension. For example, if plug-in <code>"com.xyz"</code> defines a
	 * provider extension with id <code>"myModelProvider"</code>, the unique model provider
	 * identifier will be <code>"com.xyz.myModelProvider"</code>.
	 * </p>
	 * 
	 * @return the unique model provider identifier
	 */
	public String getId();

	/**
	 * Returns a displayable label for this model provider. Returns the empty string if no label for
	 * this provider is specified in the plug-in manifest file.
	 * <p>
	 * Note that any translation specified in the plug-in manifest file is automatically applied.
	 * </p>
	 * 
	 * @return a displayable string label for this model provider, possibly the empty string
	 */
	public String getLabel();

	/**
	 * From the provides set of resources, return those that match the enablement rule specified for
	 * the model provider descriptor. The resource mappings for the returned resources can then be
	 * obtained by invoking
	 * {@link ModelProvider#getMappings(IResource[], ResourceMappingContext, IProgressMonitor)}
	 * 
	 * @param resources the resources
	 * @return the resources that match the descriptor's enablement rule
	 */
	public IResource[] getMatchingResources(IResource[] resources) throws CoreException;

	/**
	 * Return the set of traversals that overlap with the resources that this descriptor matches.
	 * 
	 * @param traversals the traversals being tested
	 * @return the subset of these traversals that overlap with the resources that match this
	 *         descriptor
	 * @throws CoreException
	 */
	public ResourceTraversal[] getMatchingTraversals(ResourceTraversal[] traversals) throws CoreException;

	/**
	 * Return the model provider for this descriptor, instantiating it if it is the first time the
	 * method is called.
	 * 
	 * @return the model provider for this descriptor
	 * @exception CoreException if the model provider could not be instantiated for some reason
	 */
	public ModelProvider getModelProvider() throws CoreException;
}