OtEngine (apicurio-data-models 1.0.12.Final API)

java.lang.Object
- io.apicurio.datamodels.cmd.ot.OtEngine

```
public class OtEngine
extends Object
```
This class is used to implement Operational Transformation support for OAI documents. For reference: https://en.wikipedia.org/wiki/Operational_transformation Specifically, this implements a simple CC/CCI model, where changes to the document are caused by executing commands against a document in a particular state. This engine ensures that commands are all executed in a consistent order. Note that all commands must have an "undo" operation that is integral to the proper functioning of the OT algorithm. The approach taken is to undo later commands when inserting a command into a queue. In other words, commands can be received and applied asynchronously. This can cause commands to be applied out of order. When applying a command out of order, it must be properly inserted into the command flow. When this is done, the document must be reverted to the proper state prior to executing the command. This is accomplished by "rewinding" the state of the document by invoking the "undo" operation on all commands that have already been applied but temporally occur after the command being inserted. Once the document state has been rewound, the command being inserted can be executed, and then all following commands can be executed.

Author:

eric.wittmann@gmail.com

Constructor Summary

Constructors
Constructor and Description

OtEngine(Document document)
Constructor.

Constructors
Constructor and Description
`OtEngine(Document document)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`executeCommand(OtCommand command, boolean pending)` Executes the given command in the correct sequence.
`void`	`finalizeCommand(long pendingCommandId, long finalizedContentVersion)` Moves a commands from the "pending" queue to the "finalized" command queue.
`Document`	`getCurrentDocument()` Gets the current document.
`boolean`	`hasCommand(OtCommand command)` Returns true if the OT engine has already seen the given command.
`boolean`	`hasPendingCommands()` Returns true if there is at least one pending command in the engine.
`OtCommand`	`redo(long contentVersion)` Called to redo a specific command by its contentVersion identifier.
`OtCommand`	`redoLastLocalCommand()` Called to redo the last "undone" local command.
`OtCommand`	`undo(long contentVersion)` Called to undo a specific command by its contentVersion identifier.
`OtCommand`	`undoLastLocalCommand()` Called to undo the last local command.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - OtEngine
```
public OtEngine(Document document)
```
    Constructor.
    
    Parameters:
    
    document -
- Method Detail
  - getCurrentDocument
```
public Document getCurrentDocument()
```
    Gets the current document.
    
    Returns:
    
    {OasDocument}
  - hasPendingCommands
```
public boolean hasPendingCommands()
```
    Returns true if there is at least one pending command in the engine. A pending command is one that has not yet been finalized. This typically means that the command has been applied to the local document but not persisted in some remote store.
    
    Returns:
    
    {boolean}
  - hasCommand
```
public boolean hasCommand(OtCommand command)
```
    Returns true if the OT engine has already seen the given command.
    
    Parameters:
    
    command -
  - executeCommand
```
public void executeCommand(OtCommand command,
                           boolean pending)
```
    Executes the given command in the correct sequence. This command must have a valid finalized contentVersion property. This property will determine where in the sequence of commands this one falls. The engine will revert the document to an appropriate state so that the command can be executed in the correct order. During this process, existing commands may need to be undone and then re-executed after. Here's what happens when executing a command: 1) "undo" all pending commands, since those are always executed last 2) identify the insertion point of the command in the finalized command queue 3) "undo" all finalized commands that fall AFTER this command in the finalized command queue 4) execute this command and insert it into the finalized command queue 5) re-execute all finalized commands that were undone in step #3 6) re-execute all pending commands 7) profit! A future optimization of this algorithm is to only undo/redo the commands that conflict with this command. This will avoid unnecessary work (why bother undoing/redoing when there is no potential for a conflict in the document). This optimization can be achieved by ensuring that each command has a list of NodePaths that represent the affected parts of the document tree. These paths can be used to determine which commands conflict with other commands.
    
    Parameters:
    
    command -
    
    pending -
  - finalizeCommand
```
public void finalizeCommand(long pendingCommandId,
                            long finalizedContentVersion)
```
    Moves a commands from the "pending" queue to the "finalized" command queue. This occurs when a local (aka pending) command is acknowledged by the coordinating server and assigned a final content version. The engine must remove the command from the pending queue, update its contentVersion, and then insert it at the correct location in the finalized queue. Here's what happens when finalizing a command: 1) "undo" all pending commands, shrinking the pending command queue to 0 2) update the given pending command's contentVersion 3) call "executeCommand()" with the newly finalized command 4) re-execute all remaining pending commands
    
    Parameters:
    
    pendingCommandId -
    
    finalizedContentVersion -
  - undoLastLocalCommand
```
public OtCommand undoLastLocalCommand()
```
    Called to undo the last local command. Returns the command that was undone (on success) or null if there was no command to undo.
  - redoLastLocalCommand
```
public OtCommand redoLastLocalCommand()
```
    Called to redo the last "undone" local command. Returns the command that was redone (on success) or null if there was no command to redo.
  - undo
```
public OtCommand undo(long contentVersion)
```
    Called to undo a specific command by its contentVersion identifier. Note: this will never be invoked for a pending command (pending commands don't have content versions yet).
    
    Parameters:
    
    contentVersion -
  - redo
```
public OtCommand redo(long contentVersion)
```
    Called to redo a specific command by its contentVersion identifier.
    
    Parameters:
    
    contentVersion -

Class OtEngine

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

OtEngine

Method Detail

getCurrentDocument

hasPendingCommands

hasCommand

executeCommand

finalizeCommand

undoLastLocalCommand

redoLastLocalCommand

undo

redo