Attachment #144205 for bug #277303

Lines 23-28 Link Here

(-)topics_Guide.xml (+1 lines)
23	<topic label="Java wizard pages" href="guide/jdt_api_wizards.htm" />	23	<topic label="Java wizard pages" href="guide/jdt_api_wizards.htm" />
24	<topic label="Customizing Java editors" href="guide/jdt_api_editors.htm" />	24	<topic label="Customizing Java editors" href="guide/jdt_api_editors.htm" />
25	<topic label="Writing Jar files" href="guide/jdt_api_write_jar_file.htm" />	25	<topic label="Writing Jar files" href="guide/jdt_api_write_jar_file.htm" />
		26	<topic label="Contributing a clean up and a save action" href="guide/jdt_api_contributing_a_cleanup.htm" />
26	</topic>	27	</topic>
27	<topic label="JDT Debug" href="guide/jdt_int_debug.htm">	28	<topic label="JDT Debug" href="guide/jdt_int_debug.htm">
28	<topic label="Running Java code" href="guide/jdt_api_run.htm" />	29	<topic label="Running Java code" href="guide/jdt_api_run.htm" />




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html lang="en">
<head>
<meta name="copyright" content="Copyright (c) IBM Corporation and others 2009. 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=ISO-8859-1">
<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>
<link rel="stylesheet" type="text/css" href="../book.css">
</head>
<body>
<h2> Contributing a clean up and a save action using the <b>org.eclipse.jdt.ui.cleanUps</b> extension point</h2>
<p>The <a href="../reference/api/org/eclipse/jdt/ui/cleanup/package-summary.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.
The clean ups help in resolving the problems for a compilation unit. A save action is a special clean up which also resolves problems by doing the selected actions on save automatically.
</p>
<h3> Using the extension point</h3>
<p>To create a new extension for the <a href="../reference/api/org/eclipse/jdt/ui/cleanup/package-summary.html"><strong>org.eclipse.jdt.ui.cleanUps</strong></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>
<p>
<pre class="CleanUp"><span class="code SchemaTag">
   &lt;extension
         point=</span><span class="code SchemaCstring">&quot;org.eclipse.jdt.ui.cleanUps&quot;</span><span class="code SchemaTag">&gt;
      &lt;cleanUp
            id=</span><span class="code SchemaCstring">&quot;org.eclipse.jdt.copyrightsaveaction.copyright_clean_up&quot;</span><span class="code SchemaTag">
            class=</span><span class="code SchemaCstring">&quot;org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightUpdaterCleanUp&quot;</span><span class="code SchemaTag">&gt;
      &lt;/cleanUp&gt;
      
      &lt;cleanUpOptionsInitializer
            class=</span><span class="code SchemaCstring">&quot;org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightOnSaveOptionsInitializer&quot;</span><span class="code SchemaTag">
            cleanUpKind=</span><span class="code SchemaCstring">&quot;saveAction&quot;</span><span class="code SchemaTag">&gt;
      &lt;/cleanUpOptionsInitializer&gt;
      
      &lt;cleanUpConfigurationUI
            class=</span><span class="code SchemaCstring">&quot;org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightTabPage&quot;</span><span class="code SchemaTag">
            name=</span><span class="code SchemaCstring">&quot;%cleanUpConfigurationUI.name&quot;</span><span class="code SchemaTag">
            cleanUpKind=</span><span class="code SchemaCstring">&quot;saveAction&quot;</span><span class="code SchemaTag">&gt;
      &lt;/cleanUpConfigurationUI&gt;
   &lt;/extension&gt;
</span></pre>

For a description of the attributes list please refer to the extension point document.
</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><font color="#4444cc">	public class CopyrightUpdaterCleanUp implements ICleanUp {
	
		private CleanUpOptions fOptions;
		private RefactoringStatus fStatus;

		public CopyrightUpdaterCleanUp() {
		
		}</font></pre>

<p>The CleanUpRequirements 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 can be obtained using the method getRequirements() 
<pre><font color="#4444cc">		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);	    
		}</font></pre>

A human readable description can be set for each step of the clean up using getStepDescriptions()
<pre><font color="#4444cc">		public String[] getStepDescriptions() {
			if (fOptions.isEnabled("cleanup.update_copyrights"))//$NON-NLS-1$
				return new String[] {"Update Copyrights"};//$NON-NLS-1$

			return null;
		}</font></pre>

The CleanUpOptions for the given options keys need to be set using the setOptions(...)
<pre><font color="#4444cc">		public void setOptions(CleanUpOptions options) {
			Assert.isLegal(options != null);
			Assert.isTrue(fOptions == null);
			fOptions= options;		
		}</font></pre>

The clean up pre-conditions and post-conditions should be checked for an OK status using checkPreConditions(...) and checkPostConditions(...)
<pre><font color="#4444cc">		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();
		}</font></pre>

<pre><font color="#4444cc">		public RefactoringStatus checkPostConditions(IProgressMonitor monitor) throws CoreException {
			try {
				if (fStatus == null || fStatus.isOK()) {
					return new RefactoringStatus();
				} else {
					return fStatus;
				}
			} finally {
				fStatus= null;
			}
		}</font></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><font color="#4444cc">		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$
		}</font></pre> 
</p>

<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 
<pre><font color="#4444cc">	public class CopyrightTabPage implements ICleanUpConfigurationUI {
		private PixelConverter fPixelConverter;
		private CleanUpOptions fOptions;

		public CopyrightTabPage() {
			super();
		}

		public Composite createContents(Composite parent) {
			final int numColumns= 4;

			if (fPixelConverter == null) {
				fPixelConverter= new PixelConverter(parent);
			}

			final SashForm sashForm = new SashForm(parent, SWT.HORIZONTAL);
			sashForm.setFont(parent.getFont());

			Composite scrollContainer = new Composite(sashForm, SWT.NONE);

			GridData gridData = new GridData(SWT.FILL, SWT.FILL, true, true);
			scrollContainer.setLayoutData(gridData);

			GridLayout layout= new GridLayout(2, false);
			layout.marginHeight= 0;
			layout.marginWidth= 0;
			layout.horizontalSpacing= 0;
			layout.verticalSpacing= 0;
			scrollContainer.setLayout(layout);

			ScrolledComposite scroll= new ScrolledComposite(scrollContainer, SWT.V_SCROLL | SWT.H_SCROLL);
			scroll.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
			scroll.setExpandHorizontal(true);
			scroll.setExpandVertical(true);

			final Composite settingsContainer= new Composite(scroll, SWT.NONE);
			settingsContainer.setFont(sashForm.getFont());

			scroll.setContent(settingsContainer);

			settingsContainer.setLayout(new PageLayout(scroll, 400, 400));
			settingsContainer.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));

			Composite settingsPane= new Composite(settingsContainer, SWT.NONE);
			settingsPane.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));

			layout= new GridLayout(numColumns, false);
			layout.verticalSpacing= (int)(1.5 * fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_SPACING));
			layout.horizontalSpacing= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_SPACING);
			layout.marginHeight= fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_MARGIN);
			layout.marginWidth= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_MARGIN);
			settingsPane.setLayout(layout);
			doCreatePreferences(settingsPane);

			settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));

			scroll.addControlListener(new ControlListener() {

				public void controlMoved(ControlEvent e) {
				}

				public void controlResized(ControlEvent e) {
					settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));
				}
			});

			Label sashHandle = new Label(scrollContainer, SWT.SEPARATOR | SWT.VERTICAL);
			gridData= new GridData(SWT.RIGHT, SWT.FILL, false, true);
			sashHandle.setLayoutData(gridData);	

			return sashForm;		
		}

		protected void doCreatePreferences(Composite composite) {
			Group group= new Group(composite, SWT.NONE);
			group.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false));
			group.setLayout(new GridLayout(1, false));
			group.setText("Copyright Update"); //$NON-NLS-1$

			final Button updateCheckbox= new Button(group, SWT.CHECK);
			updateCheckbox.setLayoutData(new GridData(SWT.BEGINNING, SWT.CENTER, false, false));
			updateCheckbox.setText("Update the Copyrights"); //$NON-NLS-1$
			updateCheckbox.setSelection(fOptions.isEnabled("cleanup.update_copyrights")); //$NON-NLS-1$
			updateCheckbox.addSelectionListener(new SelectionAdapter() {
				/* 
				 * @see org.eclipse.swt.events.SelectionAdapter#widgetSelected(org.eclipse.swt.events.SelectionEvent)
			 	*/
				public void widgetSelected(SelectionEvent e) {
					fOptions.setOption("cleanup.update_copyrights", updateCheckbox.getSelection() ? CleanUpOptions.TRUE : CleanUpOptions.FALSE); //$NON-NLS-1$
				}
			});		
		}</font></pre>
Optionally a code snippet of the new clean up with the given options can be shown in the clean up preview tab using getPreview()    
<pre><font color="#4444cc">		public String getPreview() {
			StringBuffer buf= new StringBuffer();

			if (fOptions.isEnabled("cleanup.update_copyrights")) {//$NON-NLS-1$
				buf.append("/* Copyright (c) 2007, 2009 IBM Corporation and others.*/"); //$NON-NLS-1$
			} else {
				buf.append("/* Copyright (c) 2007, 2008 IBM Corporation and others.*/"); //$NON-NLS-1$
			}

			return buf.toString();
		}</font></pre>
If the CleanUpOptions get modified in the UI, they need to be set again using setOptions(...)
<pre><font color="#4444cc">		public void setOptions(CleanUpOptions options) {
			fOptions= options;
		} 
	}</font></pre>

<p> To see the full UI code please refer to the link <a href="../reference/misc/CopyrightTabPage.html"><b>CleanUpTabPage</b></a>
<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 for a normal code clean up or for a save action.
<pre><font color="#4444cc">	public class CopyrightOnSaveOptionsInitializer implements ICleanUpOptionsInitializer {

		public CopyrightOnSaveOptionsInitializer() {		
		}</font></pre>

The Default options for this initializer can be set using setDefaultoptions(...)
<pre><font color="#4444cc">		public void setDefaultOptions(CleanUpOptions options) {
			options.setOption("cleanup.update_copyrights", CleanUpOptions.TRUE);
		}
	}</font></pre>
</body>
</html>




<pre><font color="#4444cc">package org.eclipse.jdt.ui.internal.copyrightupdater;

import org.eclipse.swt.SWT;
import org.eclipse.swt.custom.SashForm;
import org.eclipse.swt.custom.ScrolledComposite;
import org.eclipse.swt.events.ControlEvent;
import org.eclipse.swt.events.ControlListener;
import org.eclipse.swt.events.SelectionAdapter;
import org.eclipse.swt.events.SelectionEvent;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.graphics.Rectangle;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Group;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Layout;

import org.eclipse.jface.dialogs.IDialogConstants;
import org.eclipse.jface.layout.PixelConverter;

import org.eclipse.jdt.ui.cleanup.CleanUpOptions;
import org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI;

public class CopyrightTabPage implements ICleanUpConfigurationUI {

	private PixelConverter fPixelConverter;
	private CleanUpOptions fOptions;

	public CopyrightTabPage() {
		super();
	}

	/* (non-Javadoc)
	 * @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#createContents(org.eclipse.swt.widgets.Composite)
	 */
	public Composite createContents(Composite parent) {
		final int numColumns= 4;

		if (fPixelConverter == null) {
			fPixelConverter= new PixelConverter(parent);
		}

		final SashForm sashForm = new SashForm(parent, SWT.HORIZONTAL);
		sashForm.setFont(parent.getFont());

		Composite scrollContainer = new Composite(sashForm, SWT.NONE);

		GridData gridData = new GridData(SWT.FILL, SWT.FILL, true, true);
		scrollContainer.setLayoutData(gridData);

		GridLayout layout= new GridLayout(2, false);
		layout.marginHeight= 0;
		layout.marginWidth= 0;
		layout.horizontalSpacing= 0;
		layout.verticalSpacing= 0;
		scrollContainer.setLayout(layout);

		ScrolledComposite scroll= new ScrolledComposite(scrollContainer, SWT.V_SCROLL | SWT.H_SCROLL);
		scroll.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
		scroll.setExpandHorizontal(true);
		scroll.setExpandVertical(true);

		final Composite settingsContainer= new Composite(scroll, SWT.NONE);
		settingsContainer.setFont(sashForm.getFont());

		scroll.setContent(settingsContainer);

		settingsContainer.setLayout(new PageLayout(scroll, 400, 400));
		settingsContainer.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));

		Composite settingsPane= new Composite(settingsContainer, SWT.NONE);
		settingsPane.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));

		layout= new GridLayout(numColumns, false);
		layout.verticalSpacing= (int)(1.5 * fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_SPACING));
		layout.horizontalSpacing= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_SPACING);
		layout.marginHeight= fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_MARGIN);
		layout.marginWidth= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_MARGIN);
		settingsPane.setLayout(layout);
		doCreatePreferences(settingsPane);

		settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));

		scroll.addControlListener(new ControlListener() {

			public void controlMoved(ControlEvent e) {
			}

			public void controlResized(ControlEvent e) {
				settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));
			}
		});

		Label sashHandle = new Label(scrollContainer, SWT.SEPARATOR | SWT.VERTICAL);
		gridData= new GridData(SWT.RIGHT, SWT.FILL, false, true);
		sashHandle.setLayoutData(gridData);	

		return sashForm;		
	}
	
	
	
	/**
	 * Creates the preferences for the tab page. 
	 * 
	 * @param composite Composite to create in  
	 */
	protected void doCreatePreferences(Composite composite) {
		Group group= new Group(composite, SWT.NONE);
		group.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false));
		group.setLayout(new GridLayout(1, false));
		group.setText("Copyright Update"); //$NON-NLS-1$

		final Button updateCheckbox= new Button(group, SWT.CHECK);
		updateCheckbox.setLayoutData(new GridData(SWT.BEGINNING, SWT.CENTER, false, false));
		updateCheckbox.setText("Update the Copyrights"); //$NON-NLS-1$
		updateCheckbox.setSelection(fOptions.isEnabled("cleanup.update_copyrights")); //$NON-NLS-1$
		updateCheckbox.addSelectionListener(new SelectionAdapter() {
			/* 
			 * @see org.eclipse.swt.events.SelectionAdapter#widgetSelected(org.eclipse.swt.events.SelectionEvent)
			 */
			public void widgetSelected(SelectionEvent e) {
				fOptions.setOption("cleanup.update_copyrights", updateCheckbox.getSelection() ? CleanUpOptions.TRUE : CleanUpOptions.FALSE); //$NON-NLS-1$
			}
		});		
	}

	/* (non-Javadoc)
	 * @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#getCleanUpCount()
	 */
	public int getCleanUpCount() {		
		return 1;
	}

	/* (non-Javadoc)
	 * @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#getPreview()
	 */
	public String getPreview() {		
		StringBuffer buf= new StringBuffer();

		if (fOptions.isEnabled("cleanup.update_copyrights")) {//$NON-NLS-1$
			buf.append("/* Copyright (c) 2007, 2009 IBM Corporation and others.*/"); //$NON-NLS-1$
		} else {
			buf.append("/* Copyright (c) 2007, 2008 IBM Corporation and others.*/"); //$NON-NLS-1$
		}

		return buf.toString();

	}

	/* (non-Javadoc)
	 * @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#getSelectedCleanUpCount()
	 */
	public int getSelectedCleanUpCount() {		
		return fOptions.isEnabled("cleanup.update_copyrights") ? 1 : 0; //$NON-NLS-1$
	}

	/* (non-Javadoc)
	 * @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#setOptions(org.eclipse.jdt.ui.cleanup.CleanUpOptions)
	 */
	public void setOptions(CleanUpOptions options) {
		fOptions= options;

	}
	
	/**
	 * Layout used for the settings part. Makes sure to show scrollbars
	 * if necessary. The settings part needs to be layouted on resize.
	 */
	private static class PageLayout extends Layout {

		private final ScrolledComposite fContainer;
		private final int fMinimalWidth;
		private final int fMinimalHight;

		private PageLayout(ScrolledComposite container, int minimalWidth, int minimalHight) {
			fContainer= container;
			fMinimalWidth= minimalWidth;
			fMinimalHight= minimalHight;
		}

		public Point computeSize(Composite composite, int wHint, int hHint, boolean force) {
			if (wHint != SWT.DEFAULT && hHint != SWT.DEFAULT) {
				return new Point(wHint, hHint);
			}

			int x = fMinimalWidth;
			int y = fMinimalHight;
			Control[] children = composite.getChildren();
			for (int i = 0; i < children.length; i++) {
				Point size = children[i].computeSize(SWT.DEFAULT, SWT.DEFAULT, force);
				x = Math.max(x, size.x);
				y = Math.max(y, size.y);
			}

			Rectangle area= fContainer.getClientArea();
			if (area.width > x) {
				fContainer.setExpandHorizontal(true);
			} else {
				fContainer.setExpandHorizontal(false);
			}

			if (area.height > y) {
				fContainer.setExpandVertical(true);
			} else {
				fContainer.setExpandVertical(false);
			}

			if (wHint != SWT.DEFAULT) {
				x = wHint;
			}
			if (hHint != SWT.DEFAULT) {
				y = hHint;
			}

			return new Point(x, y);
		}

		/* (non-Javadoc)
		 * @see org.eclipse.swt.widgets.Layout#layout(org.eclipse.swt.widgets.Composite, boolean)
		 */
		public void layout(Composite composite, boolean force) {
			Rectangle rect = composite.getClientArea();
			Control[] children = composite.getChildren();
			for (int i = 0; i < children.length; i++) {
				children[i].setSize(rect.width, rect.height);
			}
		}
	}
}</font></pre>

Return to bug 277303

Added Link Here

(-)guide/jdt_api_contributing_a_cleanup.htm (+238 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
2	<html lang="en">
3	<head>
4	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2009. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
5	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6	<meta http-equiv="Content-Style-Type" content="text/css">
7	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
8	<title>Contributing a simple clean up and a simple save action using the org.eclipse.jdt.ui.cleanUps extension point</title>
9	<link rel="stylesheet" type="text/css" href="../book.css">
10	</head>
11	<body>
12	<h2> Contributing a clean up and a save action using the <b>org.eclipse.jdt.ui.cleanUps</b> extension point</h2>
13	<p>The <a href="../reference/api/org/eclipse/jdt/ui/cleanup/package-summary.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.
14	The clean ups help in resolving the problems for a compilation unit. A save action is a special clean up which also resolves problems by doing the selected actions on save automatically.
15	</p>
16	<h3> Using the extension point</h3>
17	<p>To create a new extension for the <a href="../reference/api/org/eclipse/jdt/ui/cleanup/package-summary.html"><strong>org.eclipse.jdt.ui.cleanUps</strong></a> extension point
18	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
19	which updates the copyrights for a file on save: </p>
20	<p>
21	<pre class="CleanUp"><span class="code SchemaTag">
22	<extension
23	point=</span><span class="code SchemaCstring">"org.eclipse.jdt.ui.cleanUps"</span><span class="code SchemaTag">>
24	<cleanUp
25	id=</span><span class="code SchemaCstring">"org.eclipse.jdt.copyrightsaveaction.copyright_clean_up"</span><span class="code SchemaTag">
26	class=</span><span class="code SchemaCstring">"org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightUpdaterCleanUp"</span><span class="code SchemaTag">>
27	</cleanUp>
28
29	<cleanUpOptionsInitializer
30	class=</span><span class="code SchemaCstring">"org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightOnSaveOptionsInitializer"</span><span class="code SchemaTag">
31	cleanUpKind=</span><span class="code SchemaCstring">"saveAction"</span><span class="code SchemaTag">>
32	</cleanUpOptionsInitializer>
33
34	<cleanUpConfigurationUI
35	class=</span><span class="code SchemaCstring">"org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightTabPage"</span><span class="code SchemaTag">
36	name=</span><span class="code SchemaCstring">"%cleanUpConfigurationUI.name"</span><span class="code SchemaTag">
37	cleanUpKind=</span><span class="code SchemaCstring">"saveAction"</span><span class="code SchemaTag">>
38	</cleanUpConfigurationUI>
39	</extension>
40	</span></pre>
41
42	For a description of the attributes list please refer to the extension point document.
43	</p>
44	<h3>Contributing a clean up</h3>
45	<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.
46	Lets create the <code>CopyrightUpdaterCleanUp</code> class for our example clean up and implement the inherited methods :</p>
47	<pre><font color="#4444cc"> public class CopyrightUpdaterCleanUp implements ICleanUp {
48
49	private CleanUpOptions fOptions;
50	private RefactoringStatus fStatus;
51
52	public CopyrightUpdaterCleanUp() {
53
54	}</font></pre>
55
56	<p>The CleanUpRequirements 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
57	regions, which are used by the <code>CleanUpContext</code> to create the fix. It can be obtained using the method getRequirements()
58	<pre><font color="#4444cc"> public CleanUpRequirements getRequirements() {
59	boolean changedRegionsRequired= false;
60	Map compilerOptions= null;
61	boolean isUpdateCopyrights= fOptions.isEnabled("cleanup.update_copyrights");//$NON-NLS-1$
62	return new CleanUpRequirements(isUpdateCopyrights, isUpdateCopyrights, changedRegionsRequired, compilerOptions);
63	}</font></pre>
64
65	A human readable description can be set for each step of the clean up using getStepDescriptions()
66	<pre><font color="#4444cc"> public String[] getStepDescriptions() {
67	if (fOptions.isEnabled("cleanup.update_copyrights"))//$NON-NLS-1$
68	return new String[] {"Update Copyrights"};//$NON-NLS-1$
69
70	return null;
71	}</font></pre>
72
73	The CleanUpOptions for the given options keys need to be set using the setOptions(...)
74	<pre><font color="#4444cc"> public void setOptions(CleanUpOptions options) {
75	Assert.isLegal(options != null);
76	Assert.isTrue(fOptions == null);
77	fOptions= options;
78	}</font></pre>
79
80	The clean up pre-conditions and post-conditions should be checked for an OK status using checkPreConditions(...) and checkPostConditions(...)
81	<pre><font color="#4444cc"> public RefactoringStatus checkPreConditions(IJavaProject project, ICompilationUnit[] compilationUnits, IProgressMonitor monitor) throws CoreException {
82	if (fOptions.isEnabled("cleanup.update_copyrights")) { //$NON-NLS-1$
83	fStatus= new RefactoringStatus();
84	}
85	return new RefactoringStatus();
86	}</font></pre>
87
88	<pre><font color="#4444cc"> public RefactoringStatus checkPostConditions(IProgressMonitor monitor) throws CoreException {
89	try {
90	if (fStatus == null \|\| fStatus.isOK()) {
91	return new RefactoringStatus();
92	} else {
93	return fStatus;
94	}
95	} finally {
96	fStatus= null;
97	}
98	}</font></pre>
99
100	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(...)
101	<pre><font color="#4444cc"> public ICleanUpFix createFix(CleanUpContext context) throws CoreException {
102	CompilationUnit compilationUnit= context.getAST();
103	if (compilationUnit == null)
104	return null;
105
106	return CopyrightsFix.createCleanUp(compilationUnit, fOptions.isEnabled("cleanup.update_copyrights"));//$NON-NLS-1$
107	}</font></pre>
108	</p>
109
110	<h3>Contributing a clean up options provider</h3>
111	<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.
112	The page can be created by implementing the createContents(...) method in the <code>CopyrightTabPage</code> class
113	<pre><font color="#4444cc"> public class CopyrightTabPage implements ICleanUpConfigurationUI {
114	private PixelConverter fPixelConverter;
115	private CleanUpOptions fOptions;
116
117	public CopyrightTabPage() {
118	super();
119	}
120
121	public Composite createContents(Composite parent) {
122	final int numColumns= 4;
123
124	if (fPixelConverter == null) {
125	fPixelConverter= new PixelConverter(parent);
126	}
127
128	final SashForm sashForm = new SashForm(parent, SWT.HORIZONTAL);
129	sashForm.setFont(parent.getFont());
130
131	Composite scrollContainer = new Composite(sashForm, SWT.NONE);
132
133	GridData gridData = new GridData(SWT.FILL, SWT.FILL, true, true);
134	scrollContainer.setLayoutData(gridData);
135
136	GridLayout layout= new GridLayout(2, false);
137	layout.marginHeight= 0;
138	layout.marginWidth= 0;
139	layout.horizontalSpacing= 0;
140	layout.verticalSpacing= 0;
141	scrollContainer.setLayout(layout);
142
143	ScrolledComposite scroll= new ScrolledComposite(scrollContainer, SWT.V_SCROLL \| SWT.H_SCROLL);
144	scroll.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
145	scroll.setExpandHorizontal(true);
146	scroll.setExpandVertical(true);
147
148	final Composite settingsContainer= new Composite(scroll, SWT.NONE);
149	settingsContainer.setFont(sashForm.getFont());
150
151	scroll.setContent(settingsContainer);
152
153	settingsContainer.setLayout(new PageLayout(scroll, 400, 400));
154	settingsContainer.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
155
156	Composite settingsPane= new Composite(settingsContainer, SWT.NONE);
157	settingsPane.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
158
159	layout= new GridLayout(numColumns, false);
160	layout.verticalSpacing= (int)(1.5 * fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_SPACING));
161	layout.horizontalSpacing= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_SPACING);
162	layout.marginHeight= fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_MARGIN);
163	layout.marginWidth= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_MARGIN);
164	settingsPane.setLayout(layout);
165	doCreatePreferences(settingsPane);
166
167	settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));
168
169	scroll.addControlListener(new ControlListener() {
170
171	public void controlMoved(ControlEvent e) {
172	}
173
174	public void controlResized(ControlEvent e) {
175	settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));
176	}
177	});
178
179	Label sashHandle = new Label(scrollContainer, SWT.SEPARATOR \| SWT.VERTICAL);
180	gridData= new GridData(SWT.RIGHT, SWT.FILL, false, true);
181	sashHandle.setLayoutData(gridData);
182
183	return sashForm;
184	}
185
186	protected void doCreatePreferences(Composite composite) {
187	Group group= new Group(composite, SWT.NONE);
188	group.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false));
189	group.setLayout(new GridLayout(1, false));
190	group.setText("Copyright Update"); //$NON-NLS-1$
191
192	final Button updateCheckbox= new Button(group, SWT.CHECK);
193	updateCheckbox.setLayoutData(new GridData(SWT.BEGINNING, SWT.CENTER, false, false));
194	updateCheckbox.setText("Update the Copyrights"); //$NON-NLS-1$
195	updateCheckbox.setSelection(fOptions.isEnabled("cleanup.update_copyrights")); //$NON-NLS-1$
196	updateCheckbox.addSelectionListener(new SelectionAdapter() {
197	/*
198	* @see org.eclipse.swt.events.SelectionAdapter#widgetSelected(org.eclipse.swt.events.SelectionEvent)
199	*/
200	public void widgetSelected(SelectionEvent e) {
201	fOptions.setOption("cleanup.update_copyrights", updateCheckbox.getSelection() ? CleanUpOptions.TRUE : CleanUpOptions.FALSE); //$NON-NLS-1$
202	}
203	});
204	}</font></pre>
205	Optionally a code snippet of the new clean up with the given options can be shown in the clean up preview tab using getPreview()
206	<pre><font color="#4444cc"> public String getPreview() {
207	StringBuffer buf= new StringBuffer();
208
209	if (fOptions.isEnabled("cleanup.update_copyrights")) {//$NON-NLS-1$
210	buf.append("/* Copyright (c) 2007, 2009 IBM Corporation and others.*/"); //$NON-NLS-1$
211	} else {
212	buf.append("/* Copyright (c) 2007, 2008 IBM Corporation and others.*/"); //$NON-NLS-1$
213	}
214
215	return buf.toString();
216	}</font></pre>
217	If the CleanUpOptions get modified in the UI, they need to be set again using setOptions(...)
218	<pre><font color="#4444cc"> public void setOptions(CleanUpOptions options) {
219	fOptions= options;
220	}
221	}</font></pre>
222
223	<p> To see the full UI code please refer to the link <a href="../reference/misc/CopyrightTabPage.html"><b>CleanUpTabPage</b></a>
224	<h3> Contributing a clean up options initializer</h3>
225	<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>.
226	The options initializer can either be for a normal code clean up or for a save action.
227	<pre><font color="#4444cc"> public class CopyrightOnSaveOptionsInitializer implements ICleanUpOptionsInitializer {
228
229	public CopyrightOnSaveOptionsInitializer() {
230	}</font></pre>
231
232	The Default options for this initializer can be set using setDefaultoptions(...)
233	<pre><font color="#4444cc"> public void setDefaultOptions(CleanUpOptions options) {
234	options.setOption("cleanup.update_copyrights", CleanUpOptions.TRUE);
235	}
236	}</font></pre>
237	</body>
238	</html>

Added Link Here

(-)reference/misc/CopyrightTabPage.html (+233 lines)
1	<pre><font color="#4444cc">package org.eclipse.jdt.ui.internal.copyrightupdater;
2
3	import org.eclipse.swt.SWT;
4	import org.eclipse.swt.custom.SashForm;
5	import org.eclipse.swt.custom.ScrolledComposite;
6	import org.eclipse.swt.events.ControlEvent;
7	import org.eclipse.swt.events.ControlListener;
8	import org.eclipse.swt.events.SelectionAdapter;
9	import org.eclipse.swt.events.SelectionEvent;
10	import org.eclipse.swt.graphics.Point;
11	import org.eclipse.swt.graphics.Rectangle;
12	import org.eclipse.swt.layout.GridData;
13	import org.eclipse.swt.layout.GridLayout;
14	import org.eclipse.swt.widgets.Button;
15	import org.eclipse.swt.widgets.Composite;
16	import org.eclipse.swt.widgets.Control;
17	import org.eclipse.swt.widgets.Group;
18	import org.eclipse.swt.widgets.Label;
19	import org.eclipse.swt.widgets.Layout;
20
21	import org.eclipse.jface.dialogs.IDialogConstants;
22	import org.eclipse.jface.layout.PixelConverter;
23
24	import org.eclipse.jdt.ui.cleanup.CleanUpOptions;
25	import org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI;
26
27	public class CopyrightTabPage implements ICleanUpConfigurationUI {
28
29	private PixelConverter fPixelConverter;
30	private CleanUpOptions fOptions;
31
32	public CopyrightTabPage() {
33	super();
34	}
35
36	/* (non-Javadoc)
37	* @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#createContents(org.eclipse.swt.widgets.Composite)
38	*/
39	public Composite createContents(Composite parent) {
40	final int numColumns= 4;
41
42	if (fPixelConverter == null) {
43	fPixelConverter= new PixelConverter(parent);
44	}
45
46	final SashForm sashForm = new SashForm(parent, SWT.HORIZONTAL);
47	sashForm.setFont(parent.getFont());
48
49	Composite scrollContainer = new Composite(sashForm, SWT.NONE);
50
51	GridData gridData = new GridData(SWT.FILL, SWT.FILL, true, true);
52	scrollContainer.setLayoutData(gridData);
53
54	GridLayout layout= new GridLayout(2, false);
55	layout.marginHeight= 0;
56	layout.marginWidth= 0;
57	layout.horizontalSpacing= 0;
58	layout.verticalSpacing= 0;
59	scrollContainer.setLayout(layout);
60
61	ScrolledComposite scroll= new ScrolledComposite(scrollContainer, SWT.V_SCROLL \| SWT.H_SCROLL);
62	scroll.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
63	scroll.setExpandHorizontal(true);
64	scroll.setExpandVertical(true);
65
66	final Composite settingsContainer= new Composite(scroll, SWT.NONE);
67	settingsContainer.setFont(sashForm.getFont());
68
69	scroll.setContent(settingsContainer);
70
71	settingsContainer.setLayout(new PageLayout(scroll, 400, 400));
72	settingsContainer.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
73
74	Composite settingsPane= new Composite(settingsContainer, SWT.NONE);
75	settingsPane.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
76
77	layout= new GridLayout(numColumns, false);
78	layout.verticalSpacing= (int)(1.5 * fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_SPACING));
79	layout.horizontalSpacing= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_SPACING);
80	layout.marginHeight= fPixelConverter.convertVerticalDLUsToPixels(IDialogConstants.VERTICAL_MARGIN);
81	layout.marginWidth= fPixelConverter.convertHorizontalDLUsToPixels(IDialogConstants.HORIZONTAL_MARGIN);
82	settingsPane.setLayout(layout);
83	doCreatePreferences(settingsPane);
84
85	settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));
86
87	scroll.addControlListener(new ControlListener() {
88
89	public void controlMoved(ControlEvent e) {
90	}
91
92	public void controlResized(ControlEvent e) {
93	settingsContainer.setSize(settingsContainer.computeSize(SWT.DEFAULT, SWT.DEFAULT));
94	}
95	});
96
97	Label sashHandle = new Label(scrollContainer, SWT.SEPARATOR \| SWT.VERTICAL);
98	gridData= new GridData(SWT.RIGHT, SWT.FILL, false, true);
99	sashHandle.setLayoutData(gridData);
100
101	return sashForm;
102	}
103
104
105
106	/**
107	* Creates the preferences for the tab page.
108	*
109	* @param composite Composite to create in
110	*/
111	protected void doCreatePreferences(Composite composite) {
112	Group group= new Group(composite, SWT.NONE);
113	group.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false));
114	group.setLayout(new GridLayout(1, false));
115	group.setText("Copyright Update"); //$NON-NLS-1$
116
117	final Button updateCheckbox= new Button(group, SWT.CHECK);
118	updateCheckbox.setLayoutData(new GridData(SWT.BEGINNING, SWT.CENTER, false, false));
119	updateCheckbox.setText("Update the Copyrights"); //$NON-NLS-1$
120	updateCheckbox.setSelection(fOptions.isEnabled("cleanup.update_copyrights")); //$NON-NLS-1$
121	updateCheckbox.addSelectionListener(new SelectionAdapter() {
122	/*
123	* @see org.eclipse.swt.events.SelectionAdapter#widgetSelected(org.eclipse.swt.events.SelectionEvent)
124	*/
125	public void widgetSelected(SelectionEvent e) {
126	fOptions.setOption("cleanup.update_copyrights", updateCheckbox.getSelection() ? CleanUpOptions.TRUE : CleanUpOptions.FALSE); //$NON-NLS-1$
127	}
128	});
129	}
130
131	/* (non-Javadoc)
132	* @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#getCleanUpCount()
133	*/
134	public int getCleanUpCount() {
135	return 1;
136	}
137
138	/* (non-Javadoc)
139	* @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#getPreview()
140	*/
141	public String getPreview() {
142	StringBuffer buf= new StringBuffer();
143
144	if (fOptions.isEnabled("cleanup.update_copyrights")) {//$NON-NLS-1$
145	buf.append("/* Copyright (c) 2007, 2009 IBM Corporation and others.*/"); //$NON-NLS-1$
146	} else {
147	buf.append("/* Copyright (c) 2007, 2008 IBM Corporation and others.*/"); //$NON-NLS-1$
148	}
149
150	return buf.toString();
151
152	}
153
154	/* (non-Javadoc)
155	* @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#getSelectedCleanUpCount()
156	*/
157	public int getSelectedCleanUpCount() {
158	return fOptions.isEnabled("cleanup.update_copyrights") ? 1 : 0; //$NON-NLS-1$
159	}
160
161	/* (non-Javadoc)
162	* @see org.eclipse.jdt.ui.cleanup.ICleanUpConfigurationUI#setOptions(org.eclipse.jdt.ui.cleanup.CleanUpOptions)
163	*/
164	public void setOptions(CleanUpOptions options) {
165	fOptions= options;
166
167	}
168
169	/**
170	* Layout used for the settings part. Makes sure to show scrollbars
171	* if necessary. The settings part needs to be layouted on resize.
172	*/
173	private static class PageLayout extends Layout {
174
175	private final ScrolledComposite fContainer;
176	private final int fMinimalWidth;
177	private final int fMinimalHight;
178
179	private PageLayout(ScrolledComposite container, int minimalWidth, int minimalHight) {
180	fContainer= container;
181	fMinimalWidth= minimalWidth;
182	fMinimalHight= minimalHight;
183	}
184
185	public Point computeSize(Composite composite, int wHint, int hHint, boolean force) {
186	if (wHint != SWT.DEFAULT && hHint != SWT.DEFAULT) {
187	return new Point(wHint, hHint);
188	}
189
190	int x = fMinimalWidth;
191	int y = fMinimalHight;
192	Control[] children = composite.getChildren();
193	for (int i = 0; i < children.length; i++) {
194	Point size = children[i].computeSize(SWT.DEFAULT, SWT.DEFAULT, force);
195	x = Math.max(x, size.x);
196	y = Math.max(y, size.y);
197	}
198
199	Rectangle area= fContainer.getClientArea();
200	if (area.width > x) {
201	fContainer.setExpandHorizontal(true);
202	} else {
203	fContainer.setExpandHorizontal(false);
204	}
205
206	if (area.height > y) {
207	fContainer.setExpandVertical(true);
208	} else {
209	fContainer.setExpandVertical(false);
210	}
211
212	if (wHint != SWT.DEFAULT) {
213	x = wHint;
214	}
215	if (hHint != SWT.DEFAULT) {
216	y = hHint;
217	}
218
219	return new Point(x, y);
220	}
221
222	/* (non-Javadoc)
223	* @see org.eclipse.swt.widgets.Layout#layout(org.eclipse.swt.widgets.Composite, boolean)
224	*/
225	public void layout(Composite composite, boolean force) {
226	Rectangle rect = composite.getClientArea();
227	Control[] children = composite.getChildren();
228	for (int i = 0; i < children.length; i++) {
229	children[i].setSize(rect.width, rect.height);
230	}
231	}
232	}
233	}</font></pre>