001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.internal.ui.fix;
011:
012: import java.util.Map;
013:
014: import org.eclipse.core.runtime.CoreException;
015: import org.eclipse.core.runtime.IProgressMonitor;
016:
017: import org.eclipse.ltk.core.refactoring.RefactoringStatus;
018:
019: import org.eclipse.jdt.core.ICompilationUnit;
020: import org.eclipse.jdt.core.IJavaProject;
021: import org.eclipse.jdt.core.JavaCore;
022: import org.eclipse.jdt.core.dom.CompilationUnit;
023:
024: import org.eclipse.jdt.internal.corext.fix.IFix;
025:
026: /**
027: * A clean up can solve problems in a compilation unit.
028: * <p>
029: * The clean up is asked for its requirements through a call to
030: * {@link #getRequirements()}. The clean up can i.e. request
031: * an AST and define how to build this AST. It can base its
032: * requirements on the options passed through {@link #setOptions(CleanUpOptions)}.
033: * </p>
034: * <p>
035: * A context containing the information requested by the
036: * requirements are passed to {@link #createFix(CleanUpContext)}.
037: * A fix capable of fixing the problems is returned by this function
038: * if {@link #checkPreConditions(IJavaProject, ICompilationUnit[], IProgressMonitor)}
039: * has returned a non fatal error status.
040: * </p>
041: * <p>
042: * At the end {@link #checkPostConditions(IProgressMonitor)} is called.
043: * </p>
044: * <p>
045: * Clients can implement this interface but should extend {@link AbstractCleanUp}
046: * if possible.
047: *
048: * @since 3.2
049: */
050: public interface ICleanUp {
051:
052: /**
053: * A collection of clean up requirements.
054: * Instances of this class are returned by {@link ICleanUp#getRequirements()}
055: *
056: * @since 3.4
057: */
058: public class CleanUpRequirements {
059:
060: private final boolean fRequiresAST;
061: private final Map fCompilerOptions;
062: private final boolean fRequiresFreshAST;
063:
064: /**
065: * Create a new requirement collection
066: *
067: * @param requiresAST true if an AST is required
068: * @param requiresFreshAST true if a fresh AST is required
069: * @param compilerOptions map of compiler options or <b>null</b> if no requirements
070: */
071: protected CleanUpRequirements(boolean requiresAST,
072: boolean requiresFreshAST, Map compilerOptions) {
073: fRequiresAST = requiresAST;
074: fRequiresFreshAST = requiresFreshAST;
075: fCompilerOptions = compilerOptions;
076: }
077:
078: /**
079: * Does this clean up require an AST? If <code>true</code>
080: * then the clean up context passed to create fix
081: * will have an AST attached.
082: * <p>
083: * <strong>This should return <code>false</code> whenever possible
084: * because creating an AST is expensive.</strong>
085: * </p>
086: *
087: * @return true if createFix will need an AST
088: */
089: public boolean requiresAST() {
090: return fRequiresAST;
091: }
092:
093: /**
094: * If true a fresh AST, containing all the changes from previous clean ups,
095: * will be created and passed in the context.
096: * <p>
097: * Has no effect if {@link #requiresAST()} returns <code>false</code>.
098: * </p>
099: *
100: * @return true if the caller needs an up to date AST
101: */
102: public boolean requiresFreshAST() {
103: return fRequiresFreshAST;
104: }
105:
106: /**
107: * Required compiler options.
108: * <p>
109: * Has no effect if {@link #requiresAST()} returns <code>false</code>.
110: * </p>
111: *
112: * @return The options as map or <b>null</b>
113: * @see JavaCore
114: */
115: public Map getCompilerOptions() {
116: return fCompilerOptions;
117: }
118:
119: }
120:
121: /**
122: * A context containing all information required by a clean up
123: * to create a fix
124: *
125: * @since 3.4
126: */
127: public class CleanUpContext {
128:
129: private final ICompilationUnit fUnit;
130: private final CompilationUnit fAst;
131:
132: public CleanUpContext(ICompilationUnit unit, CompilationUnit ast) {
133: fUnit = unit;
134: fAst = ast;
135: }
136:
137: /**
138: * @return the compilation unit to fix
139: */
140: public ICompilationUnit getCompilationUnit() {
141: return fUnit;
142: }
143:
144: /**
145: * An AST build from the compilation unit to fix.
146: * Is <b>null</b> if CleanUpRequirements#requiresAST()
147: * returned <code>false</code>.
148: * The AST is guaranteed to contain changes made by previous
149: * clean ups only if CleanUpRequirements#requiresFreshAST()
150: * returned <code>true</code>.
151: *
152: * @return an AST or <b>null</b> if none requested.
153: */
154: public CompilationUnit getAST() {
155: return fAst;
156: }
157: }
158:
159: /**
160: * @param options the options to use
161: */
162: public void setOptions(CleanUpOptions options);
163:
164: /**
165: * @return the options passed to {@link #setOptions(CleanUpOptions)}
166: */
167: public CleanUpOptions getOptions();
168:
169: /**
170: * Human readable description for each operation this clean up will execute.
171: *
172: * @return descriptions or <b>null</b>
173: */
174: public String[] getDescriptions();
175:
176: /**
177: * A code snippet which complies to the current settings.
178: *
179: * @return A code snippet
180: */
181: public abstract String getPreview();
182:
183: /**
184: * @return the requirements for used for {@link #createFix(CleanUpContext)} to work
185: */
186: public CleanUpRequirements getRequirements();
187:
188: /**
189: * After call to checkPreConditions clients will start creating fixes for
190: * <code>compilationUnits</code> in <code>project</code> unless the
191: * result of checkPreConditions contains a fatal error
192: *
193: * @param project
194: * The project to clean up
195: * @param compilationUnits
196: * The compilation Units to clean up, all member of project
197: * @param monitor
198: * the monitor to show progress
199: * @return the result of the precondition check, not null
200: * @throws CoreException if an unexpected error occurred
201: */
202: public abstract RefactoringStatus checkPreConditions(
203: IJavaProject project, ICompilationUnit[] compilationUnits,
204: IProgressMonitor monitor) throws CoreException;
205:
206: /**
207: * Create an <code>IFix</code> which fixes all problems in
208: * <code>context</code> or <b>null</b> if nothing to fix.
209: *
210: * @param context
211: * a context containing all information requested by {@link #getRequirements()}
212: * @return the fix for the problems or <b>null</b> if nothing to fix
213: * @throws CoreException if an unexpected error occurred
214: */
215: public abstract IFix createFix(CleanUpContext context)
216: throws CoreException;
217:
218: /**
219: * Called when done cleaning up.
220: *
221: * @param monitor
222: * the monitor to show progress
223: * @return the result of the postcondition check, not null
224: * @throws CoreException if an unexpected error occurred
225: */
226: public abstract RefactoringStatus checkPostConditions(
227: IProgressMonitor monitor) throws CoreException;
228:
229: }
|