/*******************************************************************************
 * 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 java.util.*;
import org.eclipse.core.internal.resources.mapping.ModelProviderManager;
import org.eclipse.core.resources.*;
import org.eclipse.core.runtime.*;

/**
 * Represents the provider of a logical model. The main purpose of this
 * API is to support batch operations on sets of <code>ResourceMapping</code>
 * objects that are part of the same model.
 * 
 * <p>
 * This class may be subclassed by clients.
 * </p>
 * @see org.eclipse.core.resources.mapping.ResourceMapping
 * @since 3.2
 */
public abstract class ModelProvider extends PlatformObject {

	/**
	 * The model provider id of the Resources model.
	 */
	public static final String RESOURCE_MODEL_PROVIDER_ID = "org.eclipse.core.resources.modelProvider"; //$NON-NLS-1$

	private IModelProviderDescriptor descriptor;

	/**
	 * Return the descriptor for the model provider of the given id
	 * or <code>null</code> if the provider has not been registered.
	 * @param id a model provider id.
	 * @return the descriptor for the model provider of the given id
	 * or <code>null</code> if the provider has not been registered
	 */
	public static IModelProviderDescriptor getModelProviderDescriptor(String id) {
		IModelProviderDescriptor[] descs = ModelProviderManager.getDefault().getDescriptors();
		for (int i = 0; i < descs.length; i++) {
			IModelProviderDescriptor descriptor = descs[i];
			if (descriptor.getId().equals(id)) {
				return descriptor;
			}
		}
		return null;
	}

	/**
	 * Return the descriptors for all model providers that are registered.
	 * 
	 * @return the descriptors for all model providers that are registered.
	 */
	public static IModelProviderDescriptor[] getModelProviderDescriptors() {
		return ModelProviderManager.getDefault().getDescriptors();
	}

	/* (non-Javadoc)
	 * @see java.lang.Object#equals(java.lang.Object)
	 */
	public boolean equals(Object obj) {
		if (obj instanceof ModelProvider) {
			ModelProvider other = (ModelProvider) obj;
			return other.getDescriptor().getId().equals(getDescriptor().getId());
		}
		return super.equals(obj);
	}

	/**
	 * Return the descriptor of this model provider. The descriptor
	 * is set during initialization so implements cannot call this method
	 * until after the <code>initialize</code> method is invoked.
	 * @return the descriptor of this model provider
	 */
	public final IModelProviderDescriptor getDescriptor() {
		return descriptor;
	}
	
	/**
	 * 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 final String getId() {
		return descriptor.getId();
	}

	/**
	 * Return the resource mappings that cover the given resource.
	 * By default, an empty array is returned. Subclass may override
	 * this method but should consider overriding either 
	 * {@link #getMappings(IResource[], ResourceMappingContext, IProgressMonitor)}
	 * or {@link #getMappings(ResourceTraversal[], ResourceMappingContext, IProgressMonitor)}
	 * if more context is needed to determine the proper mappings.
	 * 
	 * @param resource the resource
	 * @param context a resource mapping context
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @return the resource mappings that cover the given resource.
	 * @exception CoreException 
	 */
	public ResourceMapping[] getMappings(IResource resource, ResourceMappingContext context, IProgressMonitor monitor) throws CoreException {
		return new ResourceMapping[0];
	}

	/**
	 * Return the set of mappings that cover the given resources.
	 * This method is used to map operations on resources to
	 * operations on resource mappings. By default, this method
	 * calls <code>getMapping(IResource)</code> for each resource.
	 * <p>
	 * Subclasses may override this method.
	 * </p>
	 * 
	 * @param resources the resources
	 * @param context a resource mapping context
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @return the set of mappings that cover the given resources
	 * @exception CoreException 
	 */
	public ResourceMapping[] getMappings(IResource[] resources, ResourceMappingContext context, IProgressMonitor monitor) throws CoreException {
		Set mappings = new HashSet();
		for (int i = 0; i < resources.length; i++) {
			IResource resource = resources[i];
			ResourceMapping[] resourceMappings = getMappings(resource, context, monitor);
			if (resourceMappings.length > 0)
				mappings.addAll(Arrays.asList(resourceMappings));
		}
		return (ResourceMapping[]) mappings.toArray(new ResourceMapping[mappings.size()]);
	}

	/**
	 * Return the set of mappings that overlap with the given resource traversals.
	 * This method is used to map operations on resources to
	 * operations on resource mappings. By default, this method
	 * calls {@link #getMappings(IResource[], ResourceMappingContext, IProgressMonitor)}
	 * with the resources extracted from each traversal.
	 * <p>
	 * Subclasses may override this method.
	 * </p>
	 * 
	 * @param traversals the traversals
	 * @param context a resource mapping context
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @return the set of mappings that overlap with the given resource traversals
	 */
	public ResourceMapping[] getMappings(ResourceTraversal[] traversals, ResourceMappingContext context, IProgressMonitor monitor) throws CoreException {
		Set result = new HashSet();
		for (int i = 0; i < traversals.length; i++) {
			ResourceTraversal traversal = traversals[i];
			ResourceMapping[] mappings = getMappings(traversal.getResources(), context, monitor);
			for (int j = 0; j < mappings.length; j++)
				result.add(mappings[j]);
		}
		return (ResourceMapping[]) result.toArray(new ResourceMapping[result.size()]);
	}

	/**
	 * Return a set of traversals that cover the given resource mappings. The
	 * provided mappings must be from this provider or one of the providers this
	 * provider extends.
	 * <p>
	 * The default implementation accumulates the traversals from the given
	 * mappings. Subclasses can override to provide a more optimal
	 * transformation.
	 * </p>
	 * 
	 * @param mappings the mappings being mapped to resources
	 * @param context the context used to determine the set of traversals that
	 *            cover the mappings
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @return a set of traversals that cover the given mappings
	 * @exception CoreException
	 */
	public ResourceTraversal[] getTraversals(ResourceMapping[] mappings, ResourceMappingContext context, IProgressMonitor monitor) throws CoreException {
		try {
			monitor.beginTask("", 100 * mappings.length); //$NON-NLS-1$
			List traversals = new ArrayList();
			for (int i = 0; i < mappings.length; i++) {
				ResourceMapping mapping = mappings[i];
				traversals.addAll(Arrays.asList(mapping.getTraversals(context, new SubProgressMonitor(monitor, 100))));
			}
			return (ResourceTraversal[]) traversals.toArray(new ResourceTraversal[traversals.size()]);
		} finally {
			monitor.done();
		}
	}

	/* (non-Javadoc)
	 * @see java.lang.Object#hashCode()
	 */
	public int hashCode() {
		return getDescriptor().getId().hashCode();
	}

	/**
	 * This method is called by the model provider framework when the model
	 * provider is instantiated. This method should not be called by clients and
	 * cannot be overridden by subclasses. However, it invokes the
	 * <code>initialize</code> method once the descriptor is set so subclasses
	 * can override that method if they need to do additional initialization.
	 * 
	 * @param desc the description of the provider as it appears in the plugin manifest
	 * @noreference This method is not intended to be referenced by clients.
	 */
	public final void init(IModelProviderDescriptor desc) {
		if (descriptor != null)
			// prevent subsequent calls from damaging this instance
			return;
		descriptor = desc;
		initialize();
	}

	/**
	 * Initialization method that is called after the descriptor
	 * of this provider is set. Subclasses may override.
	 */
	protected void initialize() {
		// Do nothing	
	}

	/**
	 * Validate the proposed changes contained in the given delta. 
	 * <p>
	 * This method must return either a {@link ModelStatus}, or a {@link MultiStatus}
	 * whose children are {@link ModelStatus}. The severity of the returned status 
	 * indicates the severity of the possible side-effects of the operation.  Any 
	 * severity other than <code>OK</code> will be shown to the user. The 
	 * message should be a human readable message that will allow the user to 
	 * make a decision on whether to continue with the operation. The model 
	 * provider id should indicate which model is flagging the possible side effects.
	 * <p>
	 * This default implementation accepts all changes and returns a status with
	 * severity <code>OK</code>. Subclasses should override to perform
	 * validation specific to their model.
	 * </p>
	 * 
	 * @param delta a delta tree containing the proposed changes
	 * @param monitor a progress monitor, or <code>null</code> if progress
	 *    reporting is not desired
	 * @return a status indicating any potential side effects
	 * on the model that provided this validator.
	 */
	public IStatus validateChange(IResourceDelta delta, IProgressMonitor monitor) {
		return new ModelStatus(IStatus.OK, ResourcesPlugin.PI_RESOURCES, descriptor.getId(), Status.OK_STATUS.getMessage());
	}
}