| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> |
| <head> |
| <meta name="copyright" content= |
| "Copyright (c) IBM Corporation and others 2009, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." /> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <meta http-equiv="Content-Style-Type" content="text/css" /> |
| <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" /> |
| <title>Contributing a simple clean up and a simple save action using the |
| org.eclipse.jdt.ui.cleanUps extension point</title> |
| |
| </head> |
| <body> |
| <h2>Contributing a clean up and a save action using the <b>clean up</b> extension point</h2> |
| |
| <p>The <a href= |
| "../reference/extension-points/org_eclipse_jdt_ui_cleanUps.html"><b>org.eclipse.jdt.ui.cleanUps</b></a> |
| extension point enables you to contribute your own Java code clean ups and Java editor save |
| actions. Clean ups help in resolving problems in a compilation unit or establishing a code style. A |
| save action is a special clean up that perform the requested modifications on save |
| automatically.</p> |
| <h3>Using the extension point</h3> |
| <p>To create a new extension for the <a href= |
| "../reference/extension-points/org_eclipse_jdt_ui_cleanUps.html"><b>org.eclipse.jdt.ui.cleanUps</b></a> |
| extension point you need to first provide the required extensions in the plugin.xml. There are 3 |
| extensions that need to be declared as shown below with the example of a clean up which updates the |
| copyrights for a file on save:</p> |
| <pre> |
| <extension |
| point="org.eclipse.jdt.ui.cleanUps"> |
| <cleanUp |
| id="org.eclipse.jdt.copyrightsaveaction.copyright_clean_up" |
| class="org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightUpdaterCleanUp"> |
| </cleanUp> |
| |
| <cleanUpOptionsInitializer |
| class="org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightOnSaveOptionsInitializer" |
| cleanUpKind="saveAction"> |
| </cleanUpOptionsInitializer> |
| |
| <cleanUpConfigurationUI |
| class="org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightTabPage" |
| name="%cleanUpConfigurationUI.name" |
| cleanUpKind="saveAction"> |
| </cleanUpConfigurationUI> |
| </extension> |
| </pre> |
| |
| <p>For a description of the individual attributes, please refer to the extension point |
| documentation.</p> |
| <h3>Contributing a clean up</h3> |
| <p>To contribute a clean up, you need to first create the class that implements the <a href= |
| "../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUp.html"><b>ICleanUp</b></a> Interface. Lets |
| create the <code>CopyrightUpdaterCleanUp</code> class for our example clean up and implement the |
| inherited methods:</p> |
| <pre class="color1"> |
| public class CopyrightUpdaterCleanUp implements ICleanUp { |
| |
| private CleanUpOptions fOptions; |
| private RefactoringStatus fStatus; |
| |
| public CopyrightUpdaterCleanUp() { |
| } |
| } |
| </pre> |
| |
| The <code>CleanUpRequirements</code> contain various requirements for the clean up such as an AST |
| or a fresh AST containing changes from other clean ups, compiler options and changed regions, which |
| are used by the <code>CleanUpContext</code> to create the fix. It has to be returned from the |
| method getRequirements(): |
| <pre class="color1"> |
| public CleanUpRequirements getRequirements() { |
| boolean changedRegionsRequired= false; |
| Map compilerOptions= null; |
| boolean isUpdateCopyrights= fOptions.isEnabled("cleanup.update_copyrights");//$NON-NLS-1$ |
| return new CleanUpRequirements(isUpdateCopyrights, isUpdateCopyrights, changedRegionsRequired, compilerOptions); |
| } |
| </pre> |
| A human readable description should be returned for each step of the clean up that is enabled in |
| the current options: |
| <pre class="color1"> |
| public String[] getStepDescriptions() { |
| if (fOptions.isEnabled("cleanup.update_copyrights"))//$NON-NLS-1$ |
| return new String[] {"Update Copyrights"};//$NON-NLS-1$ |
| |
| return null; |
| } |
| </pre> |
| The CleanUpOptions for the supported options keys will be set using setOptions(...): |
| |
| <pre class="color1"> |
| public void setOptions(CleanUpOptions options) { |
| Assert.isLegal(options != null); |
| Assert.isTrue(fOptions == null); |
| fOptions= options; |
| } |
| </pre> |
| The clean up pre-conditions and post-conditions are being checked in checkPreConditions(...) and |
| checkPostConditions(...): |
| <pre class="color1"> |
| public RefactoringStatus checkPreConditions(IJavaProject project, ICompilationUnit[] compilationUnits, IProgressMonitor monitor) throws CoreException { |
| if (fOptions.isEnabled("cleanup.update_copyrights")) { //$NON-NLS-1$ |
| fStatus= new RefactoringStatus(); |
| } |
| return new RefactoringStatus(); |
| } |
| </pre> |
| <pre class="color1"> |
| public RefactoringStatus checkPostConditions(IProgressMonitor monitor) throws CoreException { |
| try { |
| if (fStatus == null || fStatus.isOK()) { |
| return new RefactoringStatus(); |
| } else { |
| return fStatus; |
| } |
| } finally { |
| fStatus= null; |
| } |
| } |
| </pre> |
| Finally, a <a href= |
| "../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUpFix.html"><b>ICleanUpFix</b></a> is to be |
| created which fixes all the problems for the given context using createFix(...) |
| |
| <pre class="color1"> |
| public ICleanUpFix createFix(CleanUpContext context) throws CoreException { |
| CompilationUnit compilationUnit= context.getAST(); |
| if (compilationUnit == null) |
| return null; |
| |
| return CopyrightsFix.createCleanUp(compilationUnit, fOptions.isEnabled("cleanup.update_copyrights"));//$NON-NLS-1$ |
| } |
| </pre> |
| <h3>Contributing a clean up options provider</h3> |
| <p>To create the UI for the clean up, an options provider tab page has to be created by |
| implementing the <a href= |
| "../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUpConfigurationUI.html"><b>ICleanUpConfigurationUI</b></a> |
| interface. The page can be created by implementing the createContents(...) method in the |
| <code>CopyrightTabPage</code> class. The preferences page along with the desired groups and options |
| can be created using the method doCreatePreferences(). Optionally, a code snippet of the new clean |
| up with the given options can be shown in the clean up preview tab using the method getPreview(). |
| If the CleanUpOptions get modified in the UI, they need to be set again using the method |
| setOptions(...).</p> |
| <h3>Contributing a clean up options initializer</h3> |
| <p>A clean up options initializer, which returns the default options for each clean up kind can be |
| created by implementing the <a href= |
| "../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUpOptionsInitializer.html"><b>ICleanUpOptionsInitializer</b></a>. |
| The options initializer can either be contributed for a normal code clean up or for a save |
| action.</p> |
| |
| <pre class="color1"> |
| public class CopyrightOnSaveOptionsInitializer implements ICleanUpOptionsInitializer { |
| |
| public CopyrightOnSaveOptionsInitializer() { |
| } |
| </pre> |
| <p>The default options for this initializer can be set in setDefaultOptions(...)</p> |
| <pre class="color1"> |
| public void setDefaultOptions(CleanUpOptions options) { |
| options.setOption("cleanup.update_copyrights", CleanUpOptions.TRUE); |
| } |
| } |
| </pre> |
| <p>The UI code to configure the options for this example can be found here: <a href= |
| "CopyrightTabPage.html"><b>CleanUpTabPage.java</b></a>.</p> |
| </body> |
| </html> |
