wiki:GROUP_CHANGES_R0

Version 19 (modified by meddle, 16 years ago) (diff)

--

Error: Macro BackLinksMenu(None) failed
compressed data is corrupt

Error: Macro TicketQuery(summary=GROUP_CHANGES_R0, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|) failed
current transaction is aborted, commands ignored until end of transaction block

Analysis

Overview

The changes to the pro object have to be tracked and use for undoing and redoing actions, skipping and unskipping actions, synchronizing with the server, getting different revisions, and user visualization of the history of an Pro. The user actions are significant changes to a pro object and they should be visible to for the user and editable by him or her. The insignificant changes will be not. Every change should be composed of a set of primitive changes or should be a primitive change. This primitive changes should be serializable and defined.

Task requirements

  • Define the primitive changes and list them in the design section.
  • Provide interfaces for storing and synchronizing the changes of a Resource.
  • Provide a functionality for grouping of primitive changes to the developers.
  • Provide a logic that can group changes from different resources to something that can be shown to the user as one significant change.
  • Provide interface for redo/undo/skip/unskip (implementation in later revisions).
  • Refactor the old code to work for the requirements above.
  • Provide a palette the shows the changes to the currently selected book.

Task result

The task result will be source code and palette with the changes to the currently selected book.

Implementation idea

  • Use some of the code of the old UndoManager.
  • Create DefaultChange manager to execute the changes to all the pros...
  • Create special ChangeManager for the Resources, and for the pro object that are in their space.
  • Think of an algorithm for global grouping for the user.
  • Think of the primitive changes connected to Resource creation and destruction, also entering of a pro object into a ResourceSpace and leaving from it.
  • Think of use cases connected to server communication and persistence.

GROUP_RESOURCE_R0
GROUP_PERSISTENCE_R0

How to demo

  • Unit tests.
  • Demonstration:
    • Run the Sophie 2 author application.
    • Create a new book.
    • Insert a text frame.
    • See in the changes palette the change to this actions for the book...

Design

There is implementation changes and events now. There is UndoManager that is used like a change manager and additionally can perform undo-redo. There are a few step that have to be taken into when designing this task:

  • First of all the old UndoManader have to be deprecated and later when not needed removed (after the undo-redo-skip implementation).
  • The current changes should be researched and their hierarchy may be will be enlarged.
  • The resources are the most important part of the changes design, because their state will be saved or transfered to the server and back.
  • The ProObjects should work with changes but if they are not part of a resource space, the changes should not be stored.
  • The grouping for the user have to have prototype.

That is a diagram of some of the changes that are used now and some that I will add:
source:branches/private/meddle/sophie2-platform/modules/org.sophie2.base.model.resources/doc/Changes.jpg

  • In the new design of the changes:
    • All the actions that on the pro-objects will be trackable and will be Changes.
    • The Undo and Redo actions will have changes, because they can be skipped, unskipped.
    • Skip and Unskip have to be Changes to because they are also undo-able redo-able, skip-able and unskip-able.
  • The changes will use the old GroupChange for grouping.
    • Groups can be created from the developer using the AutoChanges.
    • All AutoChanges will have to have descriptions, so they will be constructed with description and the description will be asserted to be not null or empty.
    • The old DummyChange can be used for closing groups if there is no present closing change. (Think of a better name for the next revision.).
  • About resources. Having in mind that Resources will be buildable from a list of Changes and will be transferable through the net to the server and back, we can look at the resources as a sequence of changes that describes their life time so:
    • There will be changes for creating and destroying resource, as beginning and ending of it's lifetime. (Will be implemented with the serialization in some of the next revisions).
    • There will be changes for entering of a pro object in a given resource space and exiting of a pro object from a given resource space.
    • All of the resources have to have their own history, and that history will include the changes of all the objects in their own ResourceSpace => it will be part of the ResourceSpace.

After all this ideas we can list all of the primitive changes that will be serializable and all the grouped changes will be set of them:

  • Set a value to a non list property : ValueChange.
  • Set an element to a given index of a pro-list : BaseProListChange.SET
  • Add an element to a pro-list : BaseProListChange.ADD
  • Remove an element from a pro-list : BaseProListChange.REMOVE
  • Create a Resource : CreateResourceChange (will be designed in the next revision).
  • Destroy a Resource : DestroyResourceChange (will be designed in the next revision).
  • Create a pro-object in a ResourceSpace (Attach) : CreateProObjectChange. (may be better name is AttachChange or AttachProObjectChange).
  • Destroy a pro-object that is an a ResourceSpace (Detach) : DestroyProObjectChange. (may be better name is DetachChange or DetachProObjectChange).
  • Undo a change : UndoChange.
  • Redo a change : RedoChange.
  • Skip a change : SkipChange. The Unskip action is skip of a skip so this change will work for it.

Some ideas for the old changes and the new changes:

  • Pro-object related changes:
    • There are some changes that are not in the UML diagram, they are connected with the pro objects only and are already implemented:
    • This changes are all descendants of the ProChange, and more accurately BaseProChanges:
      • BaseProListChange - there are three such changes ADD, REMOVE and SET, they are primitive changes for the pro-lists.
      • CountChange - Used for testing of the AutoTracker.
      • StatusChange - changes that track the status of the properties:
        • InitChanges - used for initializing of the properties they are not primitive changes, because when to a property a value is set they will be triggered automatically.
        • ValueChange - a primitive change for setting properties to a pro-object.
    • ProObjectChange - this change is not used so maybe it will be deleted in the next revisions...
  • Changes connected to the Resources:
    • When creating a pro-object in a ResourceSpace two thing are important, the id of the pro-object given by the resource space and the type of the pro-object, so the constructor of this change will take proObjectId:String and proObjectType:Class<T extends ProObject>.
    • When destroying the pro-object only it's id will be important to know what we have destroyed. So the DestroyProObjectChange will be constructed only by id.
    • When creating a resource we will need the id of the resource and it's type too but the change must be different than this of the pro-objects because it is the beginning of a Resource's lifetime.
    • The destruction of a resource is analogical.
  • Special changes
    • The UndoChange undoes a Change so it will be constructed with a Change.
    • The RedoChange redoes an undo, so it will be constructed with an UndoChange.
    • The SkipChange behavior is unclear for now, but may be it will be constructed with a Change to skip.

All these points clear the model of the changes. Now the logic that will be used for their management will be introduced. First this is the UML diagram:
source:branches/private/meddle/sophie2-platform/modules/org.sophie2.base.model.resources/doc/ChangesLogic.jpg

  • ChangeManager : The old Undomanager will be deprecated, and will be removed from everywhere it's used, but will be saved for now until the undo/redo implementation. In it's place there will be only a ChangeManager. All the changes will be registered in a ChangeManager, it will have only one method - register that takes a Change to register. What will be done with the Change when registered depends of the implementation. For now there will be two implementations :
    • DefaultChangeManager - All the pro-objects by default will register their changes in it, and only one instance of it will be needed for all of the changes so it will be singleton. Other thing is that the changes that are not in a ResourceSpace will be not stored, because only the state of the resource will be important for the server and the persistence... So on registration, the Changes will be just executed.
    • ResourceChangeManager.
      • Every Resource will have it's own ResourceChangeManager. It will be responsible for storing and grouping of the changes in it's Resource's ResourceSpace.
      • The old logic for grouping from the UndoManager will be used for closing and opening groups, the Changes will be grouped on registration.
      • The changes : CreateProObjectChange and DestroyProObjectChange will be handled here and all the values of the properties of the new pro-object and it's sub-pro-objects when attached will be registered as Changes in the history of the resource.
      • The ResourceChangeManager will have History, for now it will store all the changes that the manager gives it as a list but in future it will be used for synchronization with the server, so it will have to visible methods :
        • sync(newChanges : List<Change>) : List<Change> that for now adds the new changes to History and returns the added, in future the returned ones will be these from the server.
        • changeList : ProList<Change> : used to get the ciontent of the history.
      • The UndoChange and RedoChange for now will be part of the ResourceChangeManager, because they are connected with the manager of their changes and automatically will register themselves in it. may be in the future the SkipChange will be the same.
      • The manager will construct itself with a Resource, it's Resource.
  • GlobalResourceChangeManager : It will be used for grouping for the user changes from more than one ResourceSpaces.
    • Important thing is that all the changes will be packed into groups, to have Global grouping, so the ResourceChangeManagers will group single changes too. That is not bad, because when serializing we will ungroup all the groups anyway.
    • It will be one for all the Resources, so it will be singleton, it will group the changes for the current book hierarchy, to be nice for the user. Good AutoChanges must be written from the developers...
    • It will work in this way:
      • If global group must be opened (For every new set of changes or change it will open such a global group) it opens one with root Change the first change of the new set. The method shouldOpenGlobalGroup is used to check that. If there is already a root Change for the global group it will return false, otherwise true.
      • If there is already opened global group it will add the incoming change to it, for that will be used hasOpenedGroup.
      • If global group must be closed (The change that opened the group is closing itself) all the sub groups will be closed and the global group will be closed, so the root Change of the manager will be null. That's the purpose of the willCloseGroup method.
      • All the changes grouped globally will be retrievable through the getAllChangesForResource method.
    • All the global groups are virtual, they are not saved in the History of the Resources and are used only for displaying the list of the changes to the users nicely.
  • ResourceUndoManager - the new undo manager
    • It will be singleton, because it will be used only from the currently selected resource and it don't need to know it at all, only the changes that will be unoded, redoed, skipped.
    • For now it is only a skeleton that will be implemented in the next revisions, it will be able to work with skipping.
    • It will be able to:
      • Retrieve the undo and redo Changes from a Change.
      • To check if is possible to undo or to redo
      • To execute (register) Undo and Redo.

That's all for the logic... The visible part:

  • The edit menu items will be modified to use the new ResourceUndoManager.
  • Will be added AllChangesPalette that will list all the Changes for the current book globally grouped.
    • For now there will be no interactions.
    • Most of the changes won't be grouped nicely, because of bad AutoChanges and the lack of the resource creation/destruction changes.
    • The palette will use the GlobalResourceChangeManager.getAllChangesForResource(resource : Resource) method to get all of it's changes globally grouped.

For now that will be the visible part, the next step is to make the undo/redo work, after that skipping (may be interacting with the changes palette). The primitive changes must be serializable to work with client-server communication and saving the history of a Resource. The changes for creation and destruction of Resources must be designed and all the grouping of changes (AutoChanges) have to be refactored. After that we can work on the visual part :)

There are tests for the new logic:

Revisions for the design related code:

Implementation

(Describe and link the implementation results here (from the wiki or the repository).)

Testing

(Place the testing results here.)

Comments

(Write comments for this or later revisions here.)