Talk:Collaboration design

I think that for a running freeplane instance there should be no big difference whether it is connected to another freeplane instance or to a server.

• When the connection is established, the connected instance should get a copy of the edited map.
• Afterwards editing can happen on all instances simultaneously.
• All own editing events should be sent to another instance or to the server.
• All incoming events should be processed and merged into the edited map.

We should decide what kinds of events should be exchanged.

We could transmit user actions (AFreeplaneAction) like FreeMind, but I think there is no need to serialize the actions because

• we already have mechanism for serializing the map content, and
• it actually does not matter what user action generated the map change.

Therefore I suggest to use as a content of each editing event

• either a complete content of the changed nodes, or
• a complete content of the changed extensions, or
• a diff between the serialized content before and after the change.

Content can be both text or binary. For the pure map content itself XML seems to be fine, if we want to synchronize another contents like images or pdf there should be ways to transmit them too. The framework should not be limited to only XML content, but I think XML is enough for the first iteration.

Currently the changes node is not always explicitly known: if an action changes an extension which manages their viewers itself, it does not have to know what node it belongs to.

All node extensions should know their host nodes for creating an editing event for them. It could be easily done by introducing an interface like

INodeExtension extends IExtension 
{public NodeModel getHostNode(); public void setHostNode(NodeModel node); }

and changing node add/remove extension methods so that extensions always know their hosts.

The server used to connect multiple users should

• have an actual map copy,
• send it to the new connected instances,
• broadcast editing event coming from one instance to all other connected instances,
• actualize the own map version
• manage users and connections

I think that the server implementation can use parts of the freeplane implementations even if it is closed source: GPL does not enforce anyone to distribute the code in any way. It applies only if somebody wants to distribute the program.

Some open questions

• If the outgoing and incoming events try to change the same map element in different ways, how to resolve the conflict?
• What happens if user changes the current map?
• Can connections for multiple maps be open at the same time?
• Should undo / redo operations be handled directly by server?

Undo based collaboration implementation

In a discussion Dimitry and I had we came up with the following sketch for the implementation of the collaboration feature:

1. System architecture

- Freeplane collaboration is client-server based, i.e. it needs one server to which multiple clients can connect.

- Every Freeplane desktop instance can play the role of a Freeplane server. This allows two and more Freeplane applications to connect via the network to work together on one map. One FP instance ("the first") has the server role, all others are clients.

- Every Freeplane desktop instance has (at any point of time) a consistent image of the complete map, i.e. once deconnected one can work on the map stand-alone. (Note that a re-synchronization after some off-line work is not covered yet by our considerations.)

- We assume that the most interesting and most relevant applications of collaboration on mind maps will have a dedicated server which hosts mind maps for users.

2. The FP undo mechanism as the backbone of the collaboration feature

- In FP all changes of a map are undoable by virtue of the FP undo mechanism.

- The undo mechanism groups user interactions into small transactions, primarily based on time slices.

- For collaborations single undo transactions (or shortly: "transactions") are transmitted to the server.

- The server distributes each transactions to all connected clients.

3. Conflict resolution

- On connect the client synchronizes his clock with the server clock. (Saving an offset to the local clock will be sufficient.)

- Transactions are always accompanied with their commit timestamp on transfer.

- The server applies transactions strictly in the order of the commit timestamp, not in the order of their arrival.

- If two or more transactions are in conflict then the first transaction is applied, all others are cancelled.

4. Locking

- It might be desirable to include locks for single nodes or branches into the protocol. This could avoid conflicts when they would be very costly, e.g. when extended changes made in an editor would be lost.

5. Dedicated FP server

- Once collaboration is possible between FP desktop clients it should be not that hard to extend that to a scenario with a dedicated FP server hosting managing multiple maps at once.

Open issues

1. Transaction serialization

Obviously the whole thing won't work without a proper serialization of transactions. This could either be based on the serialization of single actions (as in FreeMind) or better of undo blocks which are all implementations of the org.freeplane.core.undo.IActor interface.

DimitryPolivaev 12:56, 16 September 2012 (UTC) I suggest to serialize changes in the model representation instead of the actions leading to them. To make it more efficient and avoid serializing and deserializing of the whole map on each action we should serialize changes only for the nodes contents changed by an actions. I consider serialization of actions themselves to be a design mistake because it would require to be implement serialization of every action or script. My proposal allows to reuse existing map serialization mechanism instead.

Volker Börchers 18:25, 16 September 2012 (UTC) Sounds good - we should use whatever works best :-)

2. Edit

Edit operations in editors are not covered by the undo mechanism. That means that there is only one single undo step for changing the text of a note when the editor is closed. Since the edit of a node might take quite long it will be not acceptable for the user if the whole work on a node is completely lost due to conflict resolution. Possible ways to resolve that:

- Extend the undo mechanism to the editors. That would mean that smaller changes (e.g. single words) would be committed.

- Save the result of canceled edit operations to some special area in the local map so that it isn't completely lost.

- Create a lock on the server for a node once it is

3. Transaction ordering

It might be necessary to adjust/relax the commit timestamp ordering mechanism for the handling of network delays - at least for conflicting changes. Alternatively the arrival time at the server could be used instead of the commit timestamp.

4. Re-synchronization on reconnect

Each FP instance is free to disconnect from a collaborative session and to work off-line afterwards. The problem is what should happen on re-connect:

- Save the transactions locally?

- Have a dedicated compare-and-sync mechanism that allows to manually merge maps?

- Such a merge mechanism might even be the first step towards collaborative FP!