platform-ui-home/R3_1/undo-redo-proposal/undo-redo support.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.3 - (download) (as text) (annotate)
Mon Dec 20 21:55:06 2004 UTC (4 years, 11 months ago) by sfranklin
Branch: MAIN
Changes since 1.2: +1452 -2000 lines 
proposal revised after OTT meeting

<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns:st1="urn:schemas-microsoft-com:office:smarttags"
xmlns="http://www.w3.org/TR/REC-html40">

<head>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<meta name=ProgId content=Word.Document>
<meta name=Generator content="Microsoft Word 10">
<meta name=Originator content="Microsoft Word 10">
<link rel=File-List href="undo-redo%20support_files/filelist.xml">
<title>Undo/redo support in Eclipse</title>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
 name="date"/>
<!--[if gte mso 9]><xml>
 <o:DocumentProperties>
  <o:Author>IBM_USER</o:Author>
  <o:LastAuthor>IBM_USER</o:LastAuthor>
  <o:Revision>7</o:Revision>
  <o:TotalTime>4518</o:TotalTime>
  <o:LastPrinted>2004-11-08T17:14:00Z</o:LastPrinted>
  <o:Created>2004-12-20T21:30:00Z</o:Created>
  <o:LastSaved>2004-12-20T21:50:00Z</o:LastSaved>
  <o:Pages>1</o:Pages>
  <o:Words>6341</o:Words>
  <o:Characters>36147</o:Characters>
  <o:Company>IBM</o:Company>
  <o:Lines>301</o:Lines>
  <o:Paragraphs>84</o:Paragraphs>
  <o:CharactersWithSpaces>42404</o:CharactersWithSpaces>
  <o:Version>10.6626</o:Version>
 </o:DocumentProperties>
</xml><![endif]--><!--[if gte mso 9]><xml>
 <w:WordDocument>
  <w:Compatibility>
   <w:BreakWrappedTables/>
   <w:SnapToGridInCell/>
   <w:WrapTextWithPunct/>
   <w:UseAsianBreakRules/>
  </w:Compatibility>
  <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
 </w:WordDocument>
</xml><![endif]--><!--[if !mso]><object
 classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object>
<style>
st1\:*{behavior:url(#ieooui) }
</style>
<![endif]-->
<style>
<!--
 /* Font Definitions */
 @font-face
	{font-family:Wingdings;
	panose-1:5 0 0 0 0 0 0 0 0 0;
	mso-font-charset:2;
	mso-generic-font-family:auto;
	mso-font-pitch:variable;
	mso-font-signature:0 268435456 0 0 -2147483648 0;}
 /* Style Definitions */
 p.MsoNormal, li.MsoNormal, div.MsoNormal
	{mso-style-parent:"";
	margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:12.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";}
h1
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:1;
	font-size:16.0pt;
	font-family:Arial;
	mso-font-kerning:16.0pt;}
h2
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:2;
	font-size:14.0pt;
	font-family:Arial;
	font-style:italic;}
h3
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:3;
	font-size:13.0pt;
	font-family:Arial;}
h4
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:4;
	font-size:14.0pt;
	font-family:"Times New Roman";}
h5
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	mso-outline-level:5;
	font-size:13.0pt;
	font-family:"Times New Roman";
	font-style:italic;}
p.MsoFootnoteText, li.MsoFootnoteText, div.MsoFootnoteText
	{mso-style-noshow:yes;
	margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";}
span.MsoFootnoteReference
	{mso-style-noshow:yes;
	vertical-align:super;}
p.MsoBodyText2, li.MsoBodyText2, div.MsoBodyText2
	{margin-top:0in;
	margin-right:0in;
	margin-bottom:6.0pt;
	margin-left:0in;
	line-height:200%;
	mso-pagination:widow-orphan;
	font-size:12.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";}
a:link, span.MsoHyperlink
	{color:#0000EE;
	text-decoration:underline;
	text-underline:single;}
a:visited, span.MsoHyperlinkFollowed
	{color:purple;
	text-decoration:underline;
	text-underline:single;}
code
	{font-family:"Courier New";
	mso-ascii-font-family:"Courier New";
	mso-fareast-font-family:"Times New Roman";
	mso-hansi-font-family:"Courier New";
	mso-bidi-font-family:"Courier New";}
pre
	{margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Courier New";
	mso-fareast-font-family:"Times New Roman";}
@page Section1
	{size:8.5in 11.0in;
	margin:1.0in .75in .5in 1.0in;
	mso-header-margin:.5in;
	mso-footer-margin:.5in;
	mso-paper-source:0;}
div.Section1
	{page:Section1;}
 /* List Definitions */
 @list l0
	{mso-list-id:306130254;
	mso-list-template-ids:-1505884488;}
@list l0:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	mso-ansi-font-size:10.0pt;
	font-family:Symbol;}
@list l1
	{mso-list-id:322004125;
	mso-list-template-ids:933166844;}
@list l2
	{mso-list-id:347761159;
	mso-list-type:hybrid;
	mso-list-template-ids:-1680017606 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l2:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Symbol;}
@list l2:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3
	{mso-list-id:604456885;
	mso-list-type:hybrid;
	mso-list-template-ids:1734899956 67698703 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l3:level1
	{mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level2
	{mso-level-number-format:bullet;
	mso-level-text:o;
	mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:"Courier New";}
@list l3:level3
	{mso-level-number-format:bullet;
	mso-level-text:\F0A7;
	mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Wingdings;}
@list l3:level4
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Symbol;}
@list l3:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4
	{mso-list-id:798038152;
	mso-list-type:hybrid;
	mso-list-template-ids:-2087438622 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l4:level1
	{mso-level-tab-stop:39.0pt;
	mso-level-number-position:left;
	margin-left:39.0pt;
	text-indent:-.25in;}
@list l4:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5
	{mso-list-id:1085106306;
	mso-list-type:hybrid;
	mso-list-template-ids:1015583604 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l5:level1
	{mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6
	{mso-list-id:1478297229;
	mso-list-type:hybrid;
	mso-list-template-ids:-438127954 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l6:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Symbol;}
@list l6:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l6:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7
	{mso-list-id:1644238654;
	mso-list-template-ids:-1891084734;}
@list l8
	{mso-list-id:1723091313;
	mso-list-type:hybrid;
	mso-list-template-ids:-1797201838 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l8:level1
	{mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9
	{mso-list-id:1731031428;
	mso-list-type:hybrid;
	mso-list-template-ids:1886447558 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l9:level1
	{mso-level-tab-stop:39.0pt;
	mso-level-number-position:left;
	margin-left:39.0pt;
	text-indent:-.25in;}
@list l9:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10
	{mso-list-id:1830093817;
	mso-list-template-ids:672403872;}
@list l11
	{mso-list-id:1943487606;
	mso-list-template-ids:1313531012;}
@list l11:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	mso-ansi-font-size:10.0pt;
	font-family:Symbol;}
ol
	{margin-bottom:0in;}
ul
	{margin-bottom:0in;}
-->
</style>
<!--[if gte mso 10]>
<style>
 /* Style Definitions */
 table.MsoNormalTable
	{mso-style-name:"Table Normal";
	mso-tstyle-rowband-size:0;
	mso-tstyle-colband-size:0;
	mso-style-noshow:yes;
	mso-style-parent:"";
	mso-padding-alt:0in 5.4pt 0in 5.4pt;
	mso-para-margin:0in;
	mso-para-margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Times New Roman";}
</style>
<![endif]-->
</head>

<body lang=EN-US link="#0000EE" vlink=purple style='tab-interval:.5in'>

<div class=Section1>

<h1>Generalized Undo Support in Eclipse</h1>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Last
updated:<span style='mso-spacerun:yes'>  </span></span><st1:date Month="12"
Day="17" Year="2004"><span style='font-size:10.0pt;font-family:Arial'>Dec. 17,
 2004</span></st1:date><span style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Status:<span
style='mso-spacerun:yes'>  </span>Proposal <o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>(see also </span><a
href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37716">37716</a>)<span
style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p>

<h2>Problem Description</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In R3.0.1
of the Eclipse SDK, there is no generalized support for undoing user
actions.<span style='mso-spacerun:yes'>  </span>Each plug-in is left to
implement its own strategy for undo, if at all.<span style='mso-spacerun:yes'> 
</span>This approach can cause problems for both Eclipse users and plug-in
developers:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span
style='mso-spacerun:yes'> </span><o:p></o:p></span></p>

<ul style='margin-top:0in' type=disc>
 <li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Undo and redo actions appear in
     different menus, causing user confusion and UI clutter<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Undo and redo implementations
     may have different semantics.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Plug-ins that depend on other
     plug-ins which implement their own undo strategy are forced to choose
     between different implementations and possibly write integration code to
     allow the different frameworks to coexist.<o:p></o:p></span></li>
</ul>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Further,
the meaning of undo can be very different depending on what the user is
doing.<span style='mso-spacerun:yes'>  </span>The most common type of undo is
text undo.<span style='mso-spacerun:yes'>  </span>The user can undo lightweight
edit operations such as inserting, replacing, or deleting text.<span
style='mso-spacerun:yes'>  </span>Other types of undo may involve more complex,
heavyweight operations that affect an underlying model of many elements.<span
style='mso-spacerun:yes'>  </span>For example, the JDT refactoring support
provides undo support for refactoring operations that involve many Java
elements at different levels, such as Java packages, compilation units,
classes, and methods.<o:p></o:p></span></p>

<h2>Operations Framework</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
proposed framework defines an interface for describing work, called an
“operation” (IOperation), that can be executed, undone, and redone.<span
style='mso-spacerun:yes'>  </span>Operations are created, executed, and added
to an operations history (IOperationHistory).<span style='mso-spacerun:yes'> 
</span>Operations which are comprised of distinct steps are represented as
compound operations.<span style='mso-spacerun:yes'>  </span>Compound operations
must be executed, undone, or redone as a unit, and can never be partially
undone.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations
can be assigned one or more contexts (IOperationContext) to which they
apply.<span style='mso-spacerun:yes'>  </span>An operation<span
style='mso-spacerun:yes'>  </span>context describes the context in which the
user is working when an operation is performed, undone, or redone.<span
style='mso-spacerun:yes'>  </span>Contexts can be used by workbench parts to
filter the operations history, so that only those operations that have been
assigned the part’s context are available for undo/redo when that part is
active.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
interface for operation contexts is left very general so that operation
implementers may choose the appropriate representation for their contexts.<span
style='mso-spacerun:yes'>  </span>In some cases, a part-oriented context may be
appropriate. For example, a text editor’s context is related to the editor
itself and its life-cycle is similar to that of the editor.<span
style='mso-spacerun:yes'>  </span>The navigator’s context is closely related to
the workspace model objects, and the context related to the workspace has a
life cycle to similar to that of the workspace itself.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts
can be assigned to operations in multiple ways:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l9 level1 lfo5;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The context can be assigned
initially when the operation is created.<span style='mso-spacerun:yes'> 
</span>For example, text operations are triggered by typing in the editor, and
the editor can assign its context to the operation before adding it to the
history.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l9 level1 lfo5;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>A listener interface on the
operations history allows listeners to detect when an operation is added to the
history.<span style='mso-spacerun:yes'>  </span>Listeners can decide if their
context should be added to the operation.<span style='mso-spacerun:yes'> 
</span><o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:21.0pt'><span style='font-size:10.0pt;
font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>An
operation may have more than one context.<span style='mso-spacerun:yes'> 
</span>For example, an operation may affect many elements in the workspace,
including one that is currently open in an editor.<span
style='mso-spacerun:yes'>  </span>That operation could be assigned two
independent contexts, so that it can be undone from both the editor and the
view manipulating the model.<span style='mso-spacerun:yes'>   </span><o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h2>Levels of Integration and Migration</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Many
plug-ins have already invested heavily in building objects that describe
undoable user commands or operations.<span style='mso-spacerun:yes'>  </span>It
is not expected that all plug-ins will adopt the framework completely, given
the individual schedules and other constraints for each plug-in.<span
style='mso-spacerun:yes'>  </span>However, the integration can be achieved in
phases that will immediately provide value to dependent plug-ins.<span
style='mso-spacerun:yes'>  </span>The following adoption strategy is strongly
encouraged:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<ol style='margin-top:0in' start=1 type=1>
 <li class=MsoNormal style='mso-list:l8 level1 lfo8;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Existing command/undo
     frameworks can implement the IOperation interface on their existing
     command objects, while still maintaining their individual strategies for
     managing undo stacks or histories.<span style='mso-spacerun:yes'> 
     </span>If there is a substantial investment in an existing model-based
     operation or command framework, wrappers could be used to map IOperation
     protocol to the existing protocol.<span style='mso-spacerun:yes'> 
     </span>The commands/operations need not be assigned a context or added to
     a common operation history.<span style='mso-spacerun:yes'>  </span>This
     level of integration allows command hierarchies built in different
     frameworks to be treated the same by plug-ins that depend upon these different
     frameworks.<span style='mso-spacerun:yes'>  </span>Clients of existing
     command frameworks may then use the workbench operation history, assign
     contexts to operations as needed, and even add operations to the history,
     while still using commands built on earlier frameworks.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l8 level1 lfo8;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Existing command/undo
     frameworks may use the listener interfaces provided by the operations
     history to listen for operations that are of interest.<span
     style='mso-spacerun:yes'>  </span>These commands may be wrapped or
     otherwise recorded so that they can be undone from privately maintained
     undo implementations.<span style='mso-spacerun:yes'>  </span>This level of
     integration allows views and editors to appear more tightly integrated
     with the operations framework, since workbench operations of interest can
     be undone or redone from private undo implementations.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l8 level1 lfo8;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Full integration is achieved by
     using the workbench operation history to record the undo and redo history
     as operations occur.<span style='mso-spacerun:yes'>  </span>Once all
     plug-ins share an operation history, clients will be able to use unified
     listeners and handlers to track execution of operations, undo, and redo
     them.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></li>
</ol>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Framework
interfaces will be defined in the org.eclipse.core.operations package.<span
style='mso-spacerun:yes'>  </span>This package will be contained in a plug-in
that has no dependencies on the Eclipse runtime, so that raw JFace users may
make use of it.<span style='mso-spacerun:yes'>  </span>(The exact plug-in
containing the framework package is not defined at this time, as these packages
may be combined with other packages that provide similar headless
infrastructure.)<o:p></o:p></span></p>

<h2>Framework interfaces</h2>

<h3>IOperation</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperation
defines an operation that can be executed, undone, and redone.<span
style='mso-spacerun:yes'>  </span>Operations typically have fully defined parameters.
That is, they are usually created after the user has been queried for any input
needed to define the operation.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations
determine their ability to execute, undo, or redo according to the current
state of the application. They do not make decisions about their validity based
on where they occur in the operation history. That is left to the particular
operation history.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<pre>public void addContext(IOperationContext context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified context to the operation. If the context is already present, do
not add it again. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be added<o:p></o:p></span></p>

<pre><a name="removeContext(org.eclipse.core.operation"></a>public void removeContext(IOperationContext context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified context from the operation. This method has no effect if the
context is not present. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be removed<o:p></o:p></span></p>

<pre><a name="hasContext(org.eclipse.core.operations.I"></a>public boolean <b>hasContext</b>(IOperationContext context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation has the specified context. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context in question <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the context is present, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
it is not.<o:p></o:p></span></p>

<pre><a name="getContexts()"></a>public IOperationContext [] <b>getContexts</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
the array of contexts that have been assigned to the operation. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
array of contexts<o:p></o:p></span></p>

<pre><a name="canExecute()"></a>public boolean <b>canExecute</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation can be executed in its current state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the operation can be executed; </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre><a name="canRedo()"></a>public boolean <b>canRedo</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation can be redone in its current state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the operation can be redone; </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre><a name="canUndo()"></a>public boolean <b>canUndo</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation can be undone in its current state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the operation can be undone; </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre><a name="execute(org.eclipse.core.runtime.IProgre"></a>public org.eclipse.core.runtime.IStatus <b>execute</b>(org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Execute
the operation. This method should only be called the first time that an
operation is executed. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus of the execution. The status severity should be set to </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the
operation was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> if it was not. Any other status is assumed to
represent an incompletion of the execution.<o:p></o:p></span></p>

<pre><a name="redo(org.eclipse.core.runtime.IProgressM"></a>public org.eclipse.core.runtime.IStatus <b>redo</b>(org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo
the operation. This method should only be called after an operation has been
undone. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus of the redo. The status severity should be set to </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the
redo was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> if it was not. Any other status is assumed to
represent an incompletion of the redo.<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>undo</b>(org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo
the operation. This method should only be called after an operation has been
executed. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus of the undo. The status severity should be set to </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the
redo was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> if it was not. Any other status is assumed to
represent an incompletion of the undo.<o:p></o:p></span></p>

<pre>public void <b>dispose</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Dispose
of the operation. This method is used when the operation is no longer kept in
the history. Implementers of this method typically unregister any listeners. <o:p></o:p></span></p>

<pre>public java.lang.String <b>getLabel</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
the label that should be used to show the name of the operation to the user.
This label is typically appended to the &quot;Undo&quot; or &quot;Redo&quot;
menu entry. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
label<o:p></o:p></span></p>

<pre>public java.lang.String <b>getDescription</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
the description that should be used to further describe this operation to the
user. The description is used in history lists when the user requests more
information about an operation. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
description<o:p></o:p></span></p>

<h3>IOperationHistory</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperationHistory
tracks a history of operations that can be undone or redone. Operations are
added to the history once they have been initially executed. Clients may choose
whether to have the operations history perform the initial execution or simply
add the operation to the history. Once operations are added to the history, the
methods canRedo() and canUndo() are used to determine whether there is an
operation available for undo and redo in a given operation context.<span
style='mso-spacerun:yes'>  </span>The context-based protocol implies that there
is only one operation that can be undone or redone at a given time in a given
context. This is typical of a linear undo model, when only the most recently
executed operation is available for undo. When this protocol is used, a linear
model is enforced by the history. It is up to clients to determine how to
maintain a history that is invalid or stale. For example, when the most recent
operation for a context cannot be performed, clients may wish to flush the
history for that context.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional
protocol allows direct undo and redo of a specified operation, regardless of
its position in the history. When a more flexible undo model is supported,
these methods can be implemented to undo and redo directly specified
operations. If an implementer of IOperationHistory does not allow direct undo
and redo, these methods can return a status indicating that it is not allowed.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Listeners
(IOperationHistoryListener) can listen for notifications about changes in the
history (operations added or removed), and for notification before and after
any operation is executed, undone or redone. Notification of operation
execution only occurs when clients direct the history to execute the operation.
If the operation is added after it is executed, there can be no notification of
its execution.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperationApprover
defines an interface for approving an undo or redo before it occurs. This is
useful for injecting policy-decisions into the model - whether direct undo and
redo are supported, or warning the user about certain kinds of operations. It
can also be used when objects have state related to the operation and need to
determine whether an undo or redo will cause any conflicts with their local
state.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<pre>public void <b>add</b>(IOperation operation)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified operation to the history without executing it. The operation
should have already been executed by the time it is added to the history.
Listeners will be notified that the operation was added to the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be added to the history<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>execute</b>(IOperation operation,</pre><pre><span style='mso-spacerun:yes'>                                                </span>org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Execute
the specified operation and add it to the operations history if successful. This
method is used by clients who wish operation history listeners to receive
notifications before and after the execution of the operation. Listeners will
be notified before ( </span><code><span style='font-size:10.0pt'>aboutToExecute</span></code><span
style='font-size:10.0pt'>) and after (</span><code><span style='font-size:10.0pt'>done</span></code><span
style='font-size:10.0pt'> or </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span
style='font-size:10.0pt'>). If the operation successfully executes, an
additional notification that the operation has been added to the history (</span><code><span
style='font-size:10.0pt'>operationAdded</span></code><span style='font-size:
10.0pt'>) will be sent. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be executed and then added to
the history <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus indicating whether the execution succeeded. The severity code in the
returned status describes whether the operation succeeded and whether it was
added to the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the execute operation was
successful and that the operation has been added to the history. Listeners will
receive the </span><code><span style='font-size:10.0pt'>done</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation was not added to
the history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation did not
successfully execute and that it was not added to the history. Any other
severity code is not specifically interpreted by the history, and the operation
will not be added to the history. For all severities other than </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>,
listeners will receive the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>done</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public void <b>remove</b>(IOperation operation)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified operation from the history. Listeners will be notified of the
removal of the operation. This method is used by clients who want to flush a
particular subset of the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be removed from the history<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>redo</b>(IOperationContext&nbsp;context,</pre><pre><span style='mso-spacerun:yes'>                                             </span>org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo
the most recently undone operation in the given context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be redone, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the redo, or
null if no progress monitor is provided. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus indicating whether the redo succeeded. The severity code in the
returned status describes whether the operation succeeded and whether it
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the redo operation was
successful and that the operation has been placed on the undo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>redone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
redo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be redone and that it has been removed from the history. Listeners
will also be notified that the operation was removed. Any other severity code
is not specifically interpreted by the history, and is simply passed back to
the caller. For all severities other than </span><code><span style='font-size:
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive
the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>redone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>redoOperation</b>(IOperation operation,</pre><pre><span style='mso-spacerun:yes'>                                                      </span>org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo
the specified operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be redone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the redo, or
null if no progress monitor is provided <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus indicating whether the redo succeeded. The severity code in the
returned status describes whether the operation succeeded and whether it
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the redo operation was
successful and that the operation has been placed on the undo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>redone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
redo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be redone. The operation will remain at its current location in
the history, and callers must explicitly remove it if desired. Any other
severity code is not interpreted by the history, and is simply passed back to
the caller. For all severities other than </span><code><span style='font-size:
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive
the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>redone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>undo</b>(IOperationContext&nbsp; context,</pre><pre><span style='mso-spacerun:yes'>                                             </span>org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo
the most recently undone operation in the given context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be undone, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the undo, or
null if no progress monitor is provided. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus indicating whether the undo succeeded. The severity code in the
returned status describes whether the operation succeeded and whether it
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the undo operation was
successful and that the operation has been placed on the redo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>undone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
undo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be undone and that it has been removed from the history. Listeners
will be notified that the operation was removed. Any other severity code is not
interpreted by the history, and is simply passed back to the caller. For all
severities other than </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, listeners will receive the </span><code><span
style='font-size:10.0pt'>operationNotOK</span></code><span style='font-size:
10.0pt'> notification instead of the </span><code><span style='font-size:10.0pt'>undone</span></code><span
style='font-size:10.0pt'> notification.<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>undoOperation</b>(IOperation operation,</pre><pre><span style='mso-spacerun:yes'>                                         </span><span style='mso-spacerun:yes'>             </span>org.eclipse.core.runtime.IProgressMonitor&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo
the specified operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be undone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the undo, or
null if no progress monitor is provided <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus indicating whether the undo succeeded. The severity code in the
returned status describes whether the operation succeeded and whether it
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the undo operation was
successful and that the operation has been placed on the redo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>undone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
undo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be undone. The operation will remain at its current location in
the history, and callers must explicitly remove it if desired. Any other
severity code is not interpreted by the history, and is simply passed back to
the caller. For all severities other than </span><code><span style='font-size:
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive
the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>undone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public boolean <b>canRedo</b>(IOperationContext&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
whether there is a redoable operation available in the given context. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be checked, or null for any
context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if there is a redoable operation, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre>public boolean <b>canUndo</b>(IOperationContext&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
whether there is an undoable operation available in the given context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be checked, or null to represent
any context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if there is an undoable operation, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre>public void <b>addOperationApprover</b>(IOperationApprover&nbsp;approver)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified approver to the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>approver</span></code><span
style='font-size:10.0pt'> - - the IOperationApprover that will be consulted
before any operation in the history is undone or redone<o:p></o:p></span></p>

<pre>public void <b>addOperationHistoryListener</b>(IOperationHistoryListener listener)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified listener to the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>listener</span></code><span
style='font-size:10.0pt'> - - the IOperationHistoryListener to receive
notifications about changes in the history or operations that are executed,
undone, or redone<o:p></o:p></span></p>

<pre>public void <b>removeOperationApprover</b>(IOperationApprover&nbsp; approver)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified operation approver from the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>approver</span></code><span
style='font-size:10.0pt'> - - the IOperationApprover to be removed<o:p></o:p></span></p>

<pre>public void <b>removeOperationHistoryListener</b>(IOperationHistoryListener listener)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified listener from the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>listener</span></code><span
style='font-size:10.0pt'> - - The IOperationHistoryListener to be removed<o:p></o:p></span></p>

<pre>public IOperation <b>getRedoOperation</b>(IOperationContext&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the operation that will next be redone in the given context. This method is
used to retrieve the label or description as needed for the &quot;Redo&quot;
menu. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the redo, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
operation to be redone or </span><code><span style='font-size:10.0pt'>null</span></code><span
style='font-size:10.0pt'> if there is no valid operation available.<o:p></o:p></span></p>

<pre>public IOperation [] <b>getRedoHistory</b>(IOperationContext&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the array of operations in the redo history for a given context. The operations
are in the order that they would be redone if successive &quot;Redo&quot;
commands were invoked. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the redo, or null if the entire
history is requested <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
array of operations in the history<o:p></o:p></span></p>

<pre>public IOperation <b>getUndoOperation</b>(IOperationContext&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get the
operation that will next be undone in the given context. This method is used to
retrieve the label or description as needed for the &quot;Undo&quot; menu. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the undo, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the operation
to be undone or </span><code><span style='font-size:10.0pt'>null</span></code><span
style='font-size:10.0pt'> if there is no operation available.<o:p></o:p></span></p>

<pre>public IOperation [] <b>getUndoHistory</b>(IOperationContext&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the array of operations that can be undone in the specified context. The
operations are in the order that they would be undone if successive
&quot;Undo&quot; commands were invoked. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the undo, or null if the entire
history is requested <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
array of operations in the history<o:p></o:p></span></p>

<pre>public void <b>dispose</b>(IOperationContext&nbsp;context,</pre><pre><span style='mso-spacerun:yes'>              </span><span style='mso-spacerun:yes'>      </span>boolean&nbsp;flushUndo,</pre><pre><span style='mso-spacerun:yes'>                    </span>boolean&nbsp;flushRedo)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Dispose
of the specified context in the history. All operations that have only the
given context will be disposed. References to the context in operations that
have more than one context will also be removed. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be disposed, or null if all
contexts are to be disposed <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>flushUndo</span></code><span
style='font-size:10.0pt'> - - </span><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the context should be flushed from the undo
history, </span><code><span style='font-size:10.0pt'>false</span></code><span
style='font-size:10.0pt'> if it should not <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>flushRedo</span></code><span
style='font-size:10.0pt'> - - </span><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the context should be flushed from the redo
history, </span><code><span style='font-size:10.0pt'>false</span></code><span
style='font-size:10.0pt'> if it should not.<o:p></o:p></span></p>

<pre>public int <b>getLimit</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
the specified limit on the undo and redo history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>limit<o:p></o:p></span></p>

<pre>public void <b>setLimit</b>(int&nbsp;limit)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Set
the limit on the undo and redo history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>limit</span></code><span
style='font-size:10.0pt'> - - the maximum number of operations that should be
kept in the history<o:p></o:p></span></p>

<h3>IOperationContext</h3>

<pre>public java.lang.String <b>getLabel</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the label that should be used to describe the context in any views. Contexts may
be shown when filtered operation histories are shown to the user. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
label for the context.<o:p></o:p></span></p>

<pre>public IContextOperationApprover <b>getOperationApprover</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the operation approver that is used to approve undo or redo operations
involving this context. A null context signifies that no special approval is
necessary. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
operation approver for the context.<o:p></o:p></span></p>

<pre>public boolean <b>acceptOperation</b>(IOperation operation)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
a boolean that indicates whether this context should be assigned to the specified
operation. This method should be overridden by contexts that have complex rules
for whether they should be assigned to an operation. Simple contexts generally
answer true. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a
boolean indicating whether this context should be assigned to the operation.<o:p></o:p></span></p>

<pre>public boolean <b>equals</b>(IOperationContext&nbsp;context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
whether this context is equal to the specified context. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the contexts are equal, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h3>IOperationApprover</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperationApprover
defines an interface for approving the undo or redo of a particular operation
within an operation history. Operations that are candidates for undo or redo
have already been validated against their current state and according to the
rules of the history.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>By the time
an IOperationApprover is consulted, the undo has already been requested.
Approvers should true if the operation should proceed, and false if it should
not. When an operation is rejected, it is expected that the object rejecting
the operation has already consulted the user if necessary or otherwise provided
any necessary information to the user about the rejection.<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>proceedUndoing</b>(IOperation operation, IOperationHistory history)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
a status indicating whether the specified operation should be undone. Any
status that does not have severity </span><code><span style='font-size:10.0pt'>IStatus.OK</span></code><span
style='font-size:10.0pt'> will not be approved. Implementers should not assume
that the undo will be performed when the status is </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, since
other operation approvers can veto the undo. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be undone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>history</span></code><span
style='font-size:10.0pt'> - - the history undoing the operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus describing whether the operation is approved. The undo will not proceed
if the status severity is not </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, and the caller requesting the undo will be returned
the status that caused the rejection. Any other status severities will not be
interpreted by the history.<o:p></o:p></span></p>

<pre>public org.eclipse.core.runtime.IStatus <b>proceedRedoing</b>(IOperation operation, IOperationHistory&nbsp;history)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
a status indicating whether the specified operation should be redone. Any
status that does not have severity </span><code><span style='font-size:10.0pt'>IStatus.OK</span></code><span
style='font-size:10.0pt'> will not be approved. Implementers should not assume
that the redo will be performed when the status is </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, since
other operation approvers may veto the redo. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be redone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>history</span></code><span
style='font-size:10.0pt'> - - the history redoing the operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
IStatus describing whether the operation is approved. The redo will not proceed
if the status severity is no </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, and the caller requesting the redo will be returned
the status that caused the rejection. Any other status severities will not be
interpreted by the history.<o:p></o:p></span></p>

<h3>IOperationHistoryListener</h3>

<pre>public void <b>historyNotification</b>(OperationHistoryEvent event)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Something
of note has happened in the IOperationHistory. Listeners should check the
supplied event for details. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>event</span></code><span
style='font-size:10.0pt'> - - the OperationHistoryEvent that describes the
particular notification.<o:p></o:p></span></p>

<h3>OperationHistoryEvent</h3>

<pre>public IOperationHistory <b>history</b></pre><pre><o:p>&nbsp;</o:p></pre><pre>public IOperation <b>operation</b></pre><pre><o:p>&nbsp;</o:p></pre><pre>public boolean <b>operationAdded</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was added to the history. Listeners typically use
this to add their context to a new operation as appropriate or otherwise record
the operation. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been added, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>operationRemoved</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was removed from the history. Listeners typically
remove any record of the operation that they may have kept in their own state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been removed, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>aboutToExecute</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation is about to execute. Listeners should prepare for
the execution as appropriate. Listeners will receive a done notification if the
operation is successful, or an operationNotCompleted notification if the
execution is cancelled or otherwise fails. This notification is only received
for those operations executed by the operation history. Operations that are
added to the history after execution do not trigger these notifications. If the
operation successfully executes, clients will also receive a notification that
it has been added to the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation is about to execute, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>aboutToUndo</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation is about to be undone. Listeners should prepare for
the undo as appropriate. Listeners will receive an undone notification if the
operation is successful, or an operationNotCompleted notification if the undo
is cancelled or otherwise fails. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation is about to undo, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>aboutToRedo</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation is about to be redone. Listeners should prepare for
the redo as appropriate. Listeners will receive a redone notification if the
operation is successful, or an operationNotCompleted notification if the redo
is cancelled or otherwise fails. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation is about to redo, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>done</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was initially done. Listeners can take appropriate
action, such as revealing any relevant state in the UI. This notification is
only received for those operations executed by the operation history. Operations
that are added to the history after execution do not trigger this notification.
Clients will also receive a notification that the operation has been added to
the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been done, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>undone</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was undone. Listeners can take appropriate action,
such as revealing any relevant state in the UI. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been undone, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>redone</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was redone. Listeners can take appropriate action,
such as revealing any relevant state in the UI. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been redone, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public boolean <b>operationNotOK</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was attempted and not successful. Listeners
typically use this when they have prepared for an execute, undo, or redo, and
need to know that the operation did not successfully complete. For example,
listeners that turn redraw off before an operation is undone would turn redraw
on when the operation completes, or when this notification is received, since
there will be no notification of the completion. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been redone, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h2>UI Support Classes<span style='font-size:10.0pt'><o:p></o:p></span></h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional support
classes will be provided in the package org.eclipse.ui.operations.<span
style='mso-spacerun:yes'>  </span>These classes handle policy decisions about
the undo model to be used by the workbench.<span style='mso-spacerun:yes'> 
</span>Access to the undo and redo commands, as well as the operations history,
will be provided through workbench.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h3>Workbench Operation History</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
workbench will manage a common operation history that can be used by any
plug-in to integrate its undo and redo history with the workbench.<span
style='mso-spacerun:yes'>  </span>This operation history will be accessible
through workbench API, to be determined by M5.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts
will be defined for text editors (with specialization for source editors) and
for the workspace.<span style='mso-spacerun:yes'>  </span>Throughout the
development of R3.1, plug-ins will be encouraged to define operations that
represent their existing actions or command handlers.<span
style='mso-spacerun:yes'>  </span>Additional contexts may be defined by
plug-ins.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Existing
workbench actions will be modified to support undo by mapping existing
workbench actions and handlers to operations.<span style='mso-spacerun:yes'> 
</span>The operations will be added incrementally once the framework is in
place.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations
that are assigned the workspace context will implement a subinterface,
IWorkspaceOperation.<span style='mso-spacerun:yes'>  </span>IWorkspaceOperation
adds protocol to access the model elements manipulated by an operation
(getElements()), so that listeners can decide if the workspace operation
affects their model.<span style='mso-spacerun:yes'>  </span>This protocol is
not generalized to IOperation.<span style='mso-spacerun:yes'>  </span>Prior
experience with model-based operation frameworks has shown that there needs to
be a very specific contract regarding how and when validation is performed,
what underlying model listeners are used to validate the operation, and whether
operations history notifications or internal model notifications are used to
maintain the validity of the operation and the undo stack.<span
style='mso-spacerun:yes'>  </span>These details for IWorkspaceOperation will
evolve as more workbench operations are created. <o:p></o:p></span></p>

<h3>UndoHandler and RedoHandler</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
Edit&gt;Undo and Edit&gt;Redo commands should be handled by any parts that wish
to support undo.<span style='mso-spacerun:yes'>  </span>Common handlers for the
undo and redo commands will be provided.<span style='mso-spacerun:yes'> 
</span>These handlers can be assigned a context that should be used to filter
the undo and redo history.<span style='mso-spacerun:yes'>  </span>The handlers
are responsible for the following:<o:p></o:p></span></p>

<ul style='margin-top:0in' type=disc>
 <li class=MsoNormal style='mso-list:l6 level1 lfo11;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Undo and Redo commands will be
     enabled based on the status of the history.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l6 level1 lfo11;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The Undo and Redo commands will
     be appended with the label of the operation for the handler’s context.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l6 level1 lfo11;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The undo and redo history will
     be flushed for the handler’s context whenever the most recent operation in
     the history is invalid.<span style='mso-spacerun:yes'>  </span>This
     aggressive maintenance of the history is the most conservative approach
     for ensuring that the history contains valid operations, and this strategy
     may evolve with experience.<o:p></o:p></span></li>
</ul>

<h3>Undo and Redo Toolbar Items</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Time
permitting, classes that support toolbar dropdown items for undo and redo will
be developed.<span style='mso-spacerun:yes'>  </span>These will also be
assigned a context.<span style='mso-spacerun:yes'>  </span>By clicking on the
drop-down arrow, the user will see the history for that particular
context.<span style='mso-spacerun:yes'>  </span>The user will only be able to
select a range, starting from the top item, to be undone or redone.<span
style='mso-spacerun:yes'>  </span>It is expected that the ability to view the
history is more valuable to the user than the ability to multi-select
operations for undo.<o:p></o:p></span></p>

<h3>Operation Approvers</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
workbench will provide and install an IOperationApprover that consults the
contexts of an operation to determine whether undo or redo should proceed.<span
style='mso-spacerun:yes'>  </span>The policy is described as follows:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
workbench will allow undo or redo of any valid operation in the history, <i
style='mso-bidi-font-style:normal'>as long as there are no more recent
operations in the history that share a context with the operation to be
executed.</i> <span style='mso-spacerun:yes'>  </span>If the operation to be
undone or redone has contexts that are also present in operations appearing
later in the history, then the undo or redo of the operation will not be
permitted.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A concrete
example will help explain this.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<ol style='margin-top:0in' start=1 type=1>
 <li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user makes local edits in
     editor A.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user initiates a
     refactoring operation whose context is “A” and “workspace.”<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user makes additional local
     edits to editor A.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user goes to the navigator
     and selects Undo.<o:p></o:p></span></li>
</ol>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the proposed
implementation, the navigator requests an undo for the workspace context.<span
style='mso-spacerun:yes'>  </span>The refactoring operation triggered in the
editor is the most recent operation that has the workspace context, but it also
contains context “A.”<span style='mso-spacerun:yes'>  </span>Since subsequent
operations in the history also have context “A,”, the operation will not be
allowed.<span style='mso-spacerun:yes'>  </span>An explanation will be provided
to the user after the fact:<span style='mso-spacerun:yes'>  </span>“Cannot undo
the refactoring operation because there have been subsequent changes to
A.”<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Future
releases may warn the user or provide a preference to determine whether the
undo should proceed anyway, and whether the subsequent changes to “A” should
also be undone, or be flushed from the history. Early prototypes of the
framework showed that such warnings interrupt workflow and can be very
difficult to understand, so the initial UI will be to prohibit the undo,
explaining why.<span style='mso-spacerun:yes'>   </span><o:p></o:p></span></p>

<h2>Migration Examples</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
following examples explain how existing code can be migrated to use the
operations framework.<span style='mso-spacerun:yes'>  </span>An early prototype
used these techniques to integrate the SDK text editor, refactoring framework,
and sample applications into a common undo framework.<span
style='mso-spacerun:yes'>  </span></span></p>

<h3>Mapping existing actions or command handlers to operations</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Converting
an existing action to use operations is straightforward, apart from
implementing the undo and redo behavior for the action.<span
style='mso-spacerun:yes'>  </span>The run() or runWithEvent method inside the
action should create an operation, execute it, and add it to the operations
history, rather than run the code inside the method.<span
style='mso-spacerun:yes'>  </span>The following code shows the existing run()
method in the EditorAction of the readme tool example
(org.eclipse.ui.examples.readmetool):<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<pre>public void run() {</pre><pre><span style='mso-spacerun:yes'>            </span>String editorName = MessageUtil.getString(&quot;Empty_Editor_Name&quot;); </pre><pre><span style='mso-spacerun:yes'>            </span>if (activeEditor != null)</pre><pre><span style='mso-spacerun:yes'>                </span>editorName = activeEditor.getTitle();</pre><pre><span style='mso-spacerun:yes'>            </span>MessageDialog</pre><pre><span style='mso-spacerun:yes'>                    </span>.openInformation(</pre><pre><span style='mso-spacerun:yes'>                            </span>shell,</pre><pre><span style='mso-spacerun:yes'>                            </span>MessageUtil.getString(&quot;Readme_Editor&quot;), </pre><pre><span style='mso-spacerun:yes'>                            </span>MessageUtil.format(&quot;ReadmeEditorActionExecuted&quot;, </pre><pre><span
style='mso-tab-count:4'>                               </span>new Object[] { getText(), editorName })); </pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span
style='font-family:Arial'>Using operations, the run method simplifies:<o:p></o:p></span></pre><pre><span
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre><span style='mso-spacerun:yes'>        </span>public void run() {</pre><pre><span style='mso-spacerun:yes'>            </span>String editorName = MessageUtil.getString(&quot;Empty_Editor_Name&quot;); </pre><pre><span style='mso-spacerun:yes'>  </span><span style='mso-spacerun:yes'>          </span>if (activeEditor != null)</pre><pre><span style='mso-spacerun:yes'>                </span>editorName = activeEditor.getTitle();</pre><pre><span style='mso-spacerun:yes'>            </span>// create the operation</pre><pre><span style='mso-spacerun:yes'>            </span>IOperation operation = new EditorOperation(</pre><pre><span
style='mso-tab-count:2'>               </span>getText(),shell, editorName);</pre><pre><span style='mso-spacerun:yes'>            </span>// execute (and add to the history)</pre><pre><span style='mso-spacerun:yes'>            </span>history.execute(operation, null);</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span
style='font-family:Arial'>The operation encapsulates the old run behavior, as well as the undo and redo for the operation:<o:p></o:p></span></pre><pre><span
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre>class EditorOperation extends AbstractOperation {</pre><pre><span style='mso-spacerun:yes'>        </span>Shell fShell;</pre><pre><span style='mso-spacerun:yes'>        </span>String fEditorName;</pre><pre><span style='mso-spacerun:yes'>        </span>public EditorOperation(String label, Shell shell, String editorName) {</pre><pre><span style='mso-spacerun:yes'>            </span>super(label);</pre><pre><span style='mso-spacerun:yes'>            </span>fShell = shell;</pre><pre><span style='mso-spacerun:yes'>            </span>fEditorName = editorName;</pre><pre><span style='mso-spacerun:yes'>            </span></pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>        </span>public IStatus execute(IProgressMonitor monitor) {</pre><pre><span style='mso-spacerun:yes'>            </span>MessageDialog.openInformation(</pre><pre><span style='mso-spacerun:yes'>                    </span>fShell,</pre><pre><span style='mso-spacerun:yes'>                    </span>MessageUtil.getString(&quot;Readme_Editor&quot;), </pre><pre><span style='mso-spacerun:yes'>                    </span>MessageUtil.format(&quot;ReadmeEditorActionExecuted&quot;, </pre><pre><span
style='mso-tab-count:3'>                       </span>new Object[] { getLabel(), fEditorName }));<span style='mso-spacerun:yes'>  </span></pre><pre><span style='mso-spacerun:yes'>            </span>return Status.OK_STATUS;</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>        </span>public IStatus undo(IProgressMonitor monitor) {</pre><pre><span style='mso-spacerun:yes'>            </span>// implement the undo here</pre><pre><span style='mso-spacerun:yes'>            </span>return Status.OK_STATUS;</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>        </span>public IStatus redo(IProgressMonitor monitor) {</pre><pre><span style='mso-spacerun:yes'>            </span>// implement the redo here</pre><pre><span style='mso-spacerun:yes'>            </span>return Status.OK_STATUS;</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>    </span>}</pre><pre><o:p>&nbsp;</o:p></pre><pre><span
style='font-family:Arial'>If an IHandler is provided for a command instead of using actions, the execute method of the handler is mapped similarly to the run method in an action:<o:p></o:p></span></pre><pre><span
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre><span style='mso-spacerun:yes'>        </span>public Object execute(Map params) throws ExecutionException {</pre><pre><span style='mso-spacerun:yes'>        </span>try {</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>IEditorPart activeEditor = params.get(&quot;ACTIVE_EDITOR&quot;);</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>Shell shell = params.get(&quot;SHELL&quot;);</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>String label = params.get(&quot;NAME&quot;);</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>String editorName = MessageUtil.getString(&quot;Empty_Editor_Name&quot;); </pre><pre><span style='mso-spacerun:yes'>            </span>if (activeEditor != null)</pre><pre><span style='mso-spacerun:yes'>                </span>editorName = activeEditor.getTitle();</pre><pre><span style='mso-spacerun:yes'>            </span>// create the operation</pre><pre><span style='mso-spacerun:yes'>            </span>IOperation operation =new EditorOperation(label, shell, editorName);</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>            </span>// execute (and add to the history)</pre><pre><span style='mso-spacerun:yes'>            </span>history.execute(operation, null);</pre><pre><span style='mso-spacerun:yes'>        </span>} catch (Exception e) {</pre><pre><span style='mso-spacerun:yes'>            </span>throw new ExecutionException(</pre><pre><span style='mso-spacerun:yes'>                    </span>&quot;While executing the operation, an exception occurred&quot;, e); </pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>        </span>return null;</pre><pre><span style='mso-spacerun:yes'>    </span>}</pre><pre><span
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre><span
style='font-family:Arial'>When an action launches a wizard. then the operation is typically created as part of processing the “Finish” button in the wizard.<span style='mso-spacerun:yes'>  </span>Some restructuring may be required.<span style='mso-spacerun:yes'>  </span>For example, wizards are often implemented in hierarchies and make use of convenience methods in the wizard hierarchy.<span style='mso-spacerun:yes'>  </span>Some of these methods may have to move to a corresponding hierarchy of operations.</span> </pre>

<h3>Refactoring example:<span style='mso-spacerun:yes'>  </span>mapping
existing protocol to IOperation</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the
current SDK implementation, org.eclipse.ltk.core.refactoring provides an undo
framework for undoing refactoring operations.<span style='mso-spacerun:yes'> 
</span>This framework is based on the notion of “Change” objects.<span
style='mso-spacerun:yes'>  </span>Change objects that can be undone are
responsible for returning the undo version of a change when they are
executed.<span style='mso-spacerun:yes'>  </span>An undo stack is maintained by
an internal undo manager.<span style='mso-spacerun:yes'>  </span>This undo
manager invalidates the history whenever an unknown workspace change
occurs.<span style='mso-spacerun:yes'>  </span>Undo-aware objects send signals
to the undo manager as they perform operations, so that the undo manager will
not invalidate the history.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A prototype
integrated the refactoring change framework with the operations framework as
follows:<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The change objects were wrappered
with a class that implements IOperation (and IWorkspaceOperation) and maps the
operation protocol to the Change protocol.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The refactoring undo manager was
replaced with an alternate implementation that uses the operations history to
maintain the undo and redo history.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>3.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The workspace listener and
validation strategy used in the Change framework was maintained since the
timing of the notifications was critical.<span style='mso-spacerun:yes'> 
</span>Additional integration work could be done to use the operations history
listeners for the same purpose, or to change the validation strategy as more
workspace operations are supported outside of refactoring.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>4.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>Unrelated listeners (such as text
editors) listened for new operations being added.<span
style='mso-spacerun:yes'>  </span>These listeners could check the elements
affected by the workspace operation and determine whether another context
should be assigned to the operation.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>5.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>Refactoring operations could be
undone and redone from any view or editor that installed the undo and redo
handlers on the workspace context.<o:p></o:p></span></p>

<h3>Text editor example:<span style='mso-spacerun:yes'>  </span>implementing
IOperation in preexisting commands</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The JFace
text framework supports undo and redo of text editing operations.<span
style='mso-spacerun:yes'>  </span>This implementation relies on private undo
stacks that are maintained by each editor.<span style='mso-spacerun:yes'> 
</span>The JFace IUndoManager listens to text changes coming from the
underlying widget, and builds a TextCommand for each undoable edit.<span
style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A prototype
integrated the text undo in JFace with the operations framework as follows:<o:p></o:p></span></p>

<ol style='margin-top:0in' start=1 type=1>
 <li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The existing TextCommand was
     altered to implement the IOperation interface.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Specialized contexts (one
     instance for each text editor) are assigned to the operations.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The existing UndoManager was
     replaced with an alternate implementation that added text commands to the
     operations history instead of a local stack, and used the operation
     history protocol when handling undo and redo commands.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The undo manager installs a
     listener on the history to monitor new operations that are added to the
     history.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>When an “outside” operation is
     added to the history, the undo manager consults the editor’s operation
     context to see if the outside operation is relevant.<span
     style='mso-spacerun:yes'>  </span>The editor context can check the
     elements affected by workspace operations and add itself to the
     operation’s context if appropriate.<o:p></o:p></span></li>
</ol>

<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
font-family:Arial'><o:p>&nbsp;</o:p></span></p>

</div>

</body>

</html>