Difference between revisions of "Undo Mechanism"

From Developer Documents
Jump to navigation Jump to search
 
(15 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This page documents a mechanism for defining context specific undo/redo operations.
+
[[Category: Database Development]]
 +
 
 +
This page documents a simple global non-contextual undo/redo mechanism.
  
 
== Mechanism ==
 
== Mechanism ==
  
Client keeps context specifc lists of undoable/redoable operations. Operations are added to undo list during commit if committed request has an undo context. Each commit creates a change set to server which defines the changes to resource values and statements. Change set also contains metadata for interpreting the change. The metadata format is defined by client and the server can not read or interpret it. Each operation has unique change set identifier. Sequential operations can be tagged as combined by giving them the same operation id. All operations with same id will be treated as single undoable/redoable operation.
+
Database client keeps a global list of undoable/redoable operations. Operations are added to undo list during commit. Each commit creates a change set to server which defines the changes to resource values and statements. Change set also contains metadata for interpreting the change. The metadata format is defined by client and the server can not read or interpret it. Each operation has a unique change set identifier. Sequential operations are tagged as combined by giving them the same operation id. All operations with same id will be treated as single undoable/redoable operation.
 +
 
 +
=== Combining write requests ===
  
== Procedure ==
+
Currently there is only one way to combine several database write requests into a single operation.
  
Create context
+
Normally an operation is created out of each separate write transaction. This happens when write transactions are initiated by invoking '''Session.async/asyncRequest'''. To combine a separate write transaction into a single operation, the write request must be initiated from within the write transaction using any '''WriteGraph.async/asyncRequest''' interface methods. The database client will group all write transaction change sets initiated like this into one operation.
  
<pre>
+
== Undo and redo handling in the Simantics workbench ==
    Session session = getSession();
 
    UndoContext uctx = new UndoContextEx();
 
</pre>
 
  
Create request with context
+
If '''org.eclipse.ui.edit.undo''' and '''org.eclipse.ui.edit.redo''' commands are bound to handlers '''Session{Undo,Redo}Handler''' then the undo/redo mechanism is activated. The handlers undo/redo one operation from the global undo/redo lists with each button press. It is desirable that each developer who develops requests that modify the graph comment their changes as shown by thefollowing example.
  
<pre>
+
<div style="background-color:#f8f8f8; border: 1px dashed #cccccc; padding: 1ex; margin-left:2em; margin-top: 1em; margin-bottom:1em;">
     session.syncRequest(new UndoWriteRequest(uctx, true) {
+
<syntaxhighlight lang="java">
 +
     session.sync(new WriteRequest() {
 
         @Override
 
         @Override
 
         public void perform(WriteGraph graph) throws DatabaseException {
 
         public void perform(WriteGraph graph) throws DatabaseException {
Line 27: Line 29:
 
             // Add comment to change set.
 
             // Add comment to change set.
 
             CommentMetadata cm = graph.getMetadata(CommentMetadata.class);
 
             CommentMetadata cm = graph.getMetadata(CommentMetadata.class);
             cm.add("My comment.");/
+
             cm.add("My comment.");
 
             graph.addMetadata(cm);
 
             graph.addMetadata(cm);
 
         }
 
         }
 
     });
 
     });
 +
</syntaxhighlight>
 +
</div>
 +
 +
You can test your operations using the following procedure:
 +
 +
* Do the operation.
 +
* Check from ''Teamwork'' / ''Graph History'' view which change sets have been created and that they are commented properly.
 +
 +
== Marking undo-points in database version history ==
 +
 +
Should the user simply perform write requests as described in [[#Undo and redo handling in the Simantics workbench]], each write request would simply create a new version into the database version history but all the changes would simply pile up into a single undoable operation.
 +
 +
The database API has two methods for telling the database that it's current persistent state should be regarded as an undo point and new undoable operation should be started. These are in interfaces <code>org.simantics.db.session</code> and <code>org.simantics.db.WriteOnlyGraph</code>:
 +
<pre>
 +
public interface Session extends RequestProcessor {   
 +
    ...
 +
    /**
 +
    * Marks the current database state or the beginning of the current ongoing
 +
    * write transaction as an undo point. Calling this method several times
 +
    * before or during the same write transaction has no effect.
 +
    */
 +
    void markUndoPoint();
 +
    ...
 +
}
 +
 +
 +
public interface WriteOnlyGraph extends ServiceLocator, MetadataI {
 +
    ...
 +
    /**
 +
    * Marks the beginning of the ongoing write transaction as an undo point.
 +
    * Calling this method several times during the same transaction has no
 +
    * effect.
 +
    */
 +
    void markUndoPoint();
 +
    ...
 +
}
 
</pre>
 
</pre>
Use undo and redo operations
 
 
    UndoRedoSupport support = session.getService(UndoRedoSupport.class);
 
    uctx.undo(support);
 
    uctx.redo(support);
 
  
== Diagram undo and redo handling ==
+
josta puuttuu kokonaan maininta Session/WriteOnlyGraph.markUndoPoint:sta.
  
Each diagram viewer has its own undo context which can be get with getAdapter call. Crtl-z and crtl-y keys are mapped to call DiagramUndo/RedoHandler which uses getAdapter call to get the undo context and then calls undo/redo operation. Each developer who develops diagram(s)) must check that wanted operations are undoable for the diagram undo to be consistent. This can be done by the following procedure:
+
== Related Documents ==
  
* Do the operation.
+
* [[Undo and Redo]] - internals of the mechanism.
* Check from local history view which change sets have been created.
 
* Check from undo view that change sets are combined to operations and added to the undo context correctly.
 

Latest revision as of 10:48, 15 October 2015


This page documents a simple global non-contextual undo/redo mechanism.

Mechanism

Database client keeps a global list of undoable/redoable operations. Operations are added to undo list during commit. Each commit creates a change set to server which defines the changes to resource values and statements. Change set also contains metadata for interpreting the change. The metadata format is defined by client and the server can not read or interpret it. Each operation has a unique change set identifier. Sequential operations are tagged as combined by giving them the same operation id. All operations with same id will be treated as single undoable/redoable operation.

Combining write requests

Currently there is only one way to combine several database write requests into a single operation.

Normally an operation is created out of each separate write transaction. This happens when write transactions are initiated by invoking Session.async/asyncRequest. To combine a separate write transaction into a single operation, the write request must be initiated from within the write transaction using any WriteGraph.async/asyncRequest interface methods. The database client will group all write transaction change sets initiated like this into one operation.

Undo and redo handling in the Simantics workbench

If org.eclipse.ui.edit.undo and org.eclipse.ui.edit.redo commands are bound to handlers Session{Undo,Redo}Handler then the undo/redo mechanism is activated. The handlers undo/redo one operation from the global undo/redo lists with each button press. It is desirable that each developer who develops requests that modify the graph comment their changes as shown by thefollowing example.

<syntaxhighlight lang="java">

   session.sync(new WriteRequest() {
       @Override
       public void perform(WriteGraph graph) throws DatabaseException {
           // Do your modifications.
           Layer0 b = Layer0.getInstance(graph);
           Resource s = graph.newResource();
           graph.claim(s, b.InstanceOf, b.Entity);
           
           // Add comment to change set.
           CommentMetadata cm = graph.getMetadata(CommentMetadata.class);
           cm.add("My comment.");
           graph.addMetadata(cm);
       }
   });

</syntaxhighlight>

You can test your operations using the following procedure:

  • Do the operation.
  • Check from Teamwork / Graph History view which change sets have been created and that they are commented properly.

Marking undo-points in database version history

Should the user simply perform write requests as described in #Undo and redo handling in the Simantics workbench, each write request would simply create a new version into the database version history but all the changes would simply pile up into a single undoable operation.

The database API has two methods for telling the database that it's current persistent state should be regarded as an undo point and new undoable operation should be started. These are in interfaces org.simantics.db.session and org.simantics.db.WriteOnlyGraph:

public interface Session extends RequestProcessor {    
    ...
    /**
     * Marks the current database state or the beginning of the current ongoing
     * write transaction as an undo point. Calling this method several times
     * before or during the same write transaction has no effect.
     */
    void markUndoPoint();
    ...
}


public interface WriteOnlyGraph extends ServiceLocator, MetadataI {
    ...
    /**
     * Marks the beginning of the ongoing write transaction as an undo point.
     * Calling this method several times during the same transaction has no
     * effect.
     */
    void markUndoPoint();
    ...
}

josta puuttuu kokonaan maininta Session/WriteOnlyGraph.markUndoPoint:sta.

Related Documents