/*******************************************************************************
 * Copyright (c) 2000, 2004 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package net.sourceforge.phpeclipse.phpeditor;

import net.sourceforge.phpdt.core.ICompilationUnit;

import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.jface.text.IDocument;
import org.eclipse.jface.text.ILineTracker;
import org.eclipse.jface.text.source.IAnnotationModelListener;
import org.eclipse.ui.texteditor.IDocumentProvider;
import org.eclipse.ui.texteditor.IDocumentProviderExtension2;
import org.eclipse.ui.texteditor.IDocumentProviderExtension3;

/**
 * @since 3.0
 */
public interface ICompilationUnitDocumentProvider extends IDocumentProvider, IDocumentProviderExtension2, IDocumentProviderExtension3 {
		
	/**
	 * Shuts down this provider.
	 */
	void shutdown();
	
	/**
	 * Returns the working copy for the given element.
	 * 
	 * @param element the element
	 * @return the working copy for the given element
	 */
	ICompilationUnit getWorkingCopy(Object element);
	
	/**
	 * Saves the content of the given document to the given element. This method has
	 * only an effect if it is called when directly or indirectly inside <code>saveDocument</code>.
	 * 
	 * @param monitor the progress monitor
	 * @param element the element to which to save
	 * @param document the document to save
	 * @param overwrite <code>true</code> if the save should be enforced
	 */
	void saveDocumentContent(IProgressMonitor monitor, Object element, IDocument document, boolean overwrite) throws CoreException;
	
	/**
	 * Creates a line tracker for the given element. It is of the same kind as the one that would be
	 * used for a newly created document for the given element.
	 * 
	 * @param element the element
	 * @return a line tracker for the given element
	 */
	ILineTracker createLineTracker(Object element);
	
	/**
	 * Sets the document provider's save policy.
	 * 
	 * @param savePolicy the save policy
	 */
	void setSavePolicy(ISavePolicy savePolicy);
	
	/**
	 * Adds a listener that reports changes from all compilation unit annotation models.
	 * 
	 * @param listener the listener
	 */
	void addGlobalAnnotationModelListener(IAnnotationModelListener listener);

	/**
	 * Removes the listener.
	 * 
	 * @param listener the listener
	 */	
	void removeGlobalAnnotationModelListener(IAnnotationModelListener listener);
}