Difference between revisions of "FAQ What is a working copy?"

From Eclipsepedia

Jump to: navigation, search
 
m
 
Line 1: Line 1:
''
 
 
 
 
 
 
 
 
 
The Java model supports the creation of so-called working copies of compilation
 
The Java model supports the creation of so-called working copies of compilation
 
units.  A working copy is an in-memory representation of the compilation unit on
 
units.  A working copy is an in-memory representation of the compilation unit on
Line 19: Line 11:
 
thus allowing you to preview or warn the user about possible adverse  
 
thus allowing you to preview or warn the user about possible adverse  
 
side effects of a change before the copy on disk is modified.</li>
 
side effects of a change before the copy on disk is modified.</li>
 
 
  
 
Working copies should generally be used whenever you modify a compilation
 
Working copies should generally be used whenever you modify a compilation
Line 32: Line 22:
 
Examples plug-in:
 
Examples plug-in:
 
<pre>
 
<pre>
   ICompilationUnit unit = ...;//get compilation unit handle
+
   ICompilationUnit unit = ...; //get compilation unit handle
 
   unit.becomeWorkingCopy(null, null);
 
   unit.becomeWorkingCopy(null, null);
 
   try {
 
   try {
 
       IBuffer buffer = unit.getBuffer();
 
       IBuffer buffer = unit.getBuffer();
 
       String oldContents = buffer.getContents();
 
       String oldContents = buffer.getContents();
       String newContents = ...;//make some change
+
       String newContents = ...; //make some change
 
       buffer.setContents(newContents);
 
       buffer.setContents(newContents);
 
       unit.reconcile(false, null);
 
       unit.reconcile(false, null);
Line 45: Line 35:
 
</pre>
 
</pre>
  
You should always put <tt>discardWorkingCopy</tt> in a <tt>finally</tt> block
+
You should always put <tt>discardWorkingCopy</tt> in a <tt>finally</tt> block to ensure that the working copy opened by <tt>becomeWorkingCopy</tt> is discarded even in the case of an exception. Although in this example, we simply replaced the old file contents with new contents, the <tt>IBuffer</tt> API can be used to perform modifications on smaller parts of the buffer, to replace a region, or to append contents to the end of the file.
to ensure that the working copy opened by <tt>becomeWorkingCopy</tt>
+
is discarded even in the case of an exception. Although in this example,
+
we simply replaced the old file contents with new contents, the  
+
<tt>IBuffer</tt> API can be used to perform modifications on smaller
+
parts of the buffer, to replace a region, or to append contents to the
+
end of the file.
+
 
+
  
 
== See Also: ==
 
== See Also: ==
 +
*[[FAQ How do I manipulate Java code?]]
 +
*[[FAQ What is a JDOM?]]
  
[[FAQ_How_do_I_manipulate_Java_code%3F]]
+
{{Template:FAQ_Tagline}}
 
+
[[FAQ_What_is_a_JDOM%3F]]
+
 
+
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>
+

Latest revision as of 23:43, 14 June 2006

The Java model supports the creation of so-called working copies of compilation units. A working copy is an in-memory representation of the compilation unit on disk. Any changes made to the working copy will have no effect on the file on disk until the copy is explicitly reconciled with the original. Using a working copy to manipulate a Java program has a number of powerful advantages over using your own private memory buffer. Most importantly, working copies can be shared between multiple clients. For example, you can programmatically modify the working copy being used by a Java editor, and your changes will appear immediately in the editor. JDT can also detect and report compilation problems on working copies, thus allowing you to preview or warn the user about possible adverse side effects of a change before the copy on disk is modified.</li>

Working copies should generally be used whenever you modify a compilation unit. This ensures that you are modifying the most up-to-date contents of that file, even if they have not yet been written to disk. If you do not use working copies, and a dirty Java editor is open on that file already, the user will be forced to reconcile your changes manually. The following example of using a working copy to replace a compilation unit’s contents is from the implementation of ChangeReturnTypeAction included in this book’s FAQ Examples plug-in:

   ICompilationUnit unit = ...; //get compilation unit handle
   unit.becomeWorkingCopy(null, null);
   try {
      IBuffer buffer = unit.getBuffer();
      String oldContents = buffer.getContents();
      String newContents = ...; //make some change
      buffer.setContents(newContents);
      unit.reconcile(false, null);
   } finally {
      unit.discardWorkingCopy();
   }

You should always put discardWorkingCopy in a finally block to ensure that the working copy opened by becomeWorkingCopy is discarded even in the case of an exception. Although in this example, we simply replaced the old file contents with new contents, the IBuffer API can be used to perform modifications on smaller parts of the buffer, to replace a region, or to append contents to the end of the file.

[edit] See Also:


This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.