The IWorkingCopy Interface

< To: Tigerstripe_APIs
All Tigerstripe project components that are persisted on disk implement the IWorkingCopy interface.

The intent for this interface is multi-fold:

• Since most accesses to project components are going to be read-accesses (during generation runs), a single handle is created in memory

to avoid having to re-parse the underlying XML file over and over. This is the "original" handle.

• Changes any attribute on this "original" handle, a client needs to get a "working copy", apply changes to the working copy and then commit them back to the original. This allows for an atomic update of the object and the persisted file.
• Clients can register for changes on the original through a listener pattern.
• When committing a working copy back to the original, the client has an option to check that its working copy is "up2date" with the original (i.e. that the original hasn't changed since the working copy was created).
• A client using a working copy can register a listener to be notified of changes on the original, so it can keep the working copy up to date.

Here is an illustration of how this interface can be used on a ITigerstripeModelProject, extracted from one of the JUnit tests in the org.eclipse.tigerstripe.workbench.base.test plugin:

...
IProjectDetails projectDetails = TigerstripeCore.makeProjectDetails();
projectDetails.setName("testSetOnOriginal");
ITigerstripeModelProject project = (ITigerstripeModelProject) TigerstripeCore
                 .createProject(projectDetails, null, ITigerstripeModelProject.class,
                      null, new NullProgressMonitor());
// We now have a project created on disk and the original handle
IProjectDetails details = project.getProjectDetails();
details.setName("changed");
// make sure we actually got a working object for that field
assertTrue(project.getProjectDetails().getName().equals("testSetOnOriginal"));
try {
  // This will throw a WorkingCopyException because trying to set on an "original".
  project.setProjectDetails(details);
} catch (WorkingCopyException e) {
  // let's try on a working copy now
  ITigerstripeModelProject workingCopy = (ITigerstripeModelProject) project
                    .makeWorkingCopy(null);
  try {
    // performing a set on the working copy is OK.
    workingCopy.setProjectDetails(details);
  } catch (WorkingCopyException ee) {
    // This will not happen
  }
// Commit the changes 
workingCopy.commit(null);
// Check that the original has been updated.
IProjectDetails finalDetails = project.getProjectDetails();
assertTrue(finalDetails.getName().equals("changed"));
...