org.eclipse.jdt.ui/ui/org/eclipse/jdt/internal/ui/fix/ICleanUp.java

/*******************************************************************************
 * Copyright (c) 2000, 2007 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.jdt.internal.ui.fix;

import java.util.Map;

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

import org.eclipse.ltk.core.refactoring.RefactoringStatus;

import org.eclipse.jdt.core.ICompilationUnit;
import org.eclipse.jdt.core.IJavaProject;
import org.eclipse.jdt.core.dom.CompilationUnit;

import org.eclipse.jdt.internal.corext.fix.IFix;

import org.eclipse.jdt.ui.text.java.IProblemLocation;

/**
 * A clean up can solve several different problems in a given
 * <code>CompilationUnit</code>. The <code>CompilationUnit</code> is
 * compiled by using the compiler options returned by
 * <code>getRequiredOptions</code>.
 * 
 * @since 3.2
 */
public interface ICleanUp {
	
	/**
	 * Does this clean up require an AST for the given <code>unit</code>. If
	 * true is returned an AST for unit is created by the clean up
	 * infrastructure and {@link #createFix(CompilationUnit)} is executed,
	 * otherwise {@link #createFix(ICompilationUnit)} is executed. The source
	 * from which the AST is created may be differ from the source of
	 * <code>unit</code>.
	 * <p>
	 * Implementors should return false whenever possible because creating an
	 * AST is expensive.
	 * 
	 * @param unit
	 *            the unit to create an ast for
	 * @return true if {@link #createFix(CompilationUnit)} must be executed,
	 *         false if {@link #createFix(ICompilationUnit)} must be executed
	 */
	public abstract boolean requireAST(ICompilationUnit unit) throws CoreException;
	
	/**
	 * Create an <code>IFix</code> which fixes all problems in
	 * <code>unit</code> or <code>null</code> if nothing to fix.
	 * <p>
	 * This is called iff {@link #requireAST(ICompilationUnit)} returns
	 * <code>false</code>.
	 * 
	 * @param unit
	 *            the ICompilationUnit to fix, not null
	 * @return the fix for the problems or <code>null</code> if nothing to fix
	 */
	public abstract IFix createFix(ICompilationUnit unit) throws CoreException;
	
	/**
	 * Create an <code>IFix</code> which fixes all problems in
	 * <code>compilationUnit</code> or <code>null</code> if nothing to fix.
	 * <p>
	 * This is called iff {@link #requireAST(ICompilationUnit)} returns
	 * <code>true</code>.
	 * 
	 * @param compilationUnit
	 *            The compilation unit to fix, may be null
	 * @return The fix or null if no fixes possible
	 * @throws CoreException
	 */
	public abstract IFix createFix(CompilationUnit compilationUnit) throws CoreException;
	
	/**
	 * Create a <code>IFix</code> which fixes all <code>problems</code> in
	 * <code>CompilationUnit</code>
	 * 
	 * @param compilationUnit
	 *            The compilation unit to fix, may be null
	 * @param problems
	 *            The locations of the problems to fix
	 * @return The fix or null if no fixes possible
	 * @throws CoreException
	 */
	public abstract IFix createFix(CompilationUnit compilationUnit, IProblemLocation[] problems) throws CoreException;
	
	/**
	 * Required compiler options to allow <code>createFix</code> to work
	 * correct.
	 * 
	 * @return The options as map or null
	 */
	public abstract Map getRequiredOptions();
	
	/**
	 * If true a fresh AST, containing all the changes from previous clean ups,
	 * will be created and passed to createFix.
	 * 
	 * @param compilationUnit
	 *            The current available AST
	 * @return true if the caller needs an up to date AST
	 */
	public abstract boolean needsFreshAST(CompilationUnit compilationUnit);
	
	/**
	 * Description for each operation this clean up will execute
	 * 
	 * @return descriptions or null
	 */
	public String[] getDescriptions();
	
	public void initialize(Map settings) throws CoreException;
	
	/**
	 * After call to checkPreConditions clients will start creating fixes for
	 * <code>compilationUnits</code> int <code>project</code> unless the
	 * result of checkPreConditions contains a fatal error
	 * 
	 * @param project
	 *            The project to clean up
	 * @param compilationUnits
	 *            The compilation Units to clean up, all member of project
	 * @param monitor
	 *            the monitor to show progress
	 * @return the result of the precondition check, not null
	 */
	public abstract RefactoringStatus checkPreConditions(IJavaProject project, ICompilationUnit[] compilationUnits, IProgressMonitor monitor) throws CoreException;
	
	/**
	 * Called when done cleaning up.
	 * 
	 * @param monitor
	 *            the monitor to show progress
	 * @return the result of the postcondition check, not null
	 */
	public abstract RefactoringStatus checkPostConditions(IProgressMonitor monitor) throws CoreException;
	
	/**
	 * True if <code>problem</code> in <code>CompilationUnit</code> can be
	 * fixed by this CleanUp. If true
	 * <code>createFix(compilationUnit, new IProblemLocation[] {problem})</code>
	 * does not return null.
	 * 
	 * @param compilationUnit
	 *            The compilation unit to fix not null
	 * @param problem
	 *            The location of the problem to fix
	 * @return True if problem can be fixed
	 * @throws CoreException
	 */
	public boolean canFix(CompilationUnit compilationUnit, IProblemLocation problem) throws CoreException;
	
	/**
	 * Maximal number of problems this clean up will fix in compilation unit.
	 * There may be less then the returned number but never more.
	 * 
	 * @param compilationUnit
	 *            The compilation unit to fix, not null
	 * @return The maximal number of fixes or -1 if unknown.
	 */
	public abstract int maximalNumberOfFixes(CompilationUnit compilationUnit);
	
	/**
	 * A code snippet which complies to the current settings.
	 * 
	 * @return A code snippet, not null.
	 */
	public abstract String getPreview();
	
}