| 31 | | * Keys |
| 32 | | * Children |
| 33 | | * Composite |
| 34 | | * Root |
| 35 | | * Simple |
| 36 | | * Templated |
| 37 | | * Meta, Security |
| 38 | | * [diagram: todo] |
| 39 | | * Accesses |
| 40 | | * App |
| 41 | | * Memory |
| 42 | | * Root |
| 43 | | * Top |
| 44 | | * Inner |
| 45 | | * [diagram] |
| 46 | | * File, Server |
| 47 | | * Changes |
| 48 | | * Model |
| 49 | | * Draft Notes: |
| 50 | | || ResourceAccess.open(..) || |
| | 31 | |
| | 32 | Resume of the current design ideas that are going to support all need functionality for Sophie 2.0 : |
| | 33 | |
| | 34 | == ResourceRevision == |
| | 35 | The resources revision is a version of the resource after application of a change. Revisions know the previous revision – the one they come from but have separate models. The model should be immutable so that it is preserved intact in the previous revisions. The only way to modify this model will be by applying change, resulting in new revisions with a new changed model. |
| | 36 | |
| | 37 | == Key == |
| | 38 | Keys provide a read access to the resource model. Different keys implement different logic for getting values kept in the model. There will be seven kinds of keys for the different types of model values and they will all have a get method. |
| | 39 | Children keys - Key used to access the children sub resources of a given resource. It can retrieve a list of the children ResourceRefs and get a key to a child provided a ResourceRef. |
| | 40 | |
| | 41 | Composite keys - Key used to access the sub keys of a given key. For example the BOREDER key is a composite key for its sub keys – COLOR, INSETS… It can retrieve a list of the kept sub keys. |
| | 42 | Root keys – keeps a key to a resource. It has a sub(T extends Key<?>) method that takes as argument a sub key to get a new key of the same type as the passed one pointing to the same value starting from the root. Example: If the root key is pointing to “PageA/frameA” and the passed key is BORDER the new key that is going to be created will be pointing the value of “PageA/frameA/Border”. |
| | 43 | Simple keys – Keys providing the simpler logic for getting the values of the model – using directly the getRaw() method. |
| | 44 | Templated keys – Keys that support templating. They know about the Simple key pointing to a ResourceRef TEMPLATE and use it to get value for a template key when the getRaw returns null. The TEMPLATE`s value is got from the access and the access is used to open the pointed resource. Then the value is got by it recursively by the template key`s get method. |
| | 45 | Meta keys – Keys getting values that are not kept only in the model. They implement different logic for every instance and are used for things like getting the revision id or some other value that depends on the state of the whole access. |
| | 46 | Security keys – Keys used to get the access options for a certain access. |
| | 47 | The resource model should be immutable so that it is preserved intact in the previous revisions. The only way to modify this model will be by applying change, resulting in new ResourceRevision with a new model. |
| | 48 | |
| | 49 | == Change == |
| | 50 | Every Change should be immutable and have the following properties: |
| | 51 | |
| | 52 | RevisionId revisionId – the id of the revision it initiates. |
| | 53 | |
| | 54 | ResourceRef user – The user that created it. |
| | 55 | |
| | 56 | String viewId – The id of the view it comes from. |
| | 57 | |
| | 58 | String description – Human readable explanatory description of what exactly was changed to be presented to the user when undo/redo or browsing history. |
| | 59 | |
| | 60 | boolean significant – A flag indication whether this change is significant. For example the transitional states of a drag and drop operations or typing of a single letter in a text are not significant changes despite the fact those states should be visible for the user. They should not be incorporated in a single change; however they should be processed as a whole when undoing and redoing. |
| | 61 | There will be two basic types of changes – Model and Meta changes . |
| | 62 | |
| | 63 | == ModelChange == |
| | 64 | This type of change will affect the model structure. Thought those changes developers should be able to add, remove and change values of different properties of the model. When developing an upper level logic it is more intuitive to use a direct get and set operations to the model so it would be better if developers should not create changes themselves. |
| | 65 | |
| | 66 | === AutoAction === |
| | 67 | AutoAction is a basic abstracts helper class that have a performAuto() method. When a developer wants to modify the model he should just use a new instance of a AutoAction class and implement an appropriate performAuto() method directly managing the model. This “direct” interaction with the model should internally lead to creation of changes and registration of reads. For this interaction are responsible the ResourceChangers. |
| | 68 | |
| | 69 | === ResourceChanger === |
| | 70 | Every AutoAction class has access to a ResourceChanger which holds the model and can modify it internally without causing any effect on the actual resource model. When a developer wants to change the model he should just create the appropriate ResourceChanger with the model he wants to manipulate and pass it to the AutoAction by setModel() method. |
| | 71 | When managing the model in the performAuto() method developers should use the two methods getRaw(Key<T> key) and setRaw(Key<T> key, T value)of the ResourceChanger. This will transparently register reads and writes for the appropriate operations and thus the change`s effect could be extracted after the method is complete. |
| | 72 | The ResourceChanger should also present several useful helper methods for resource manipulation - makeResource(ResourceRef ref), copyResource(ResourceRef source, ResourceRef destination), moveResource(ResourceRef source, ResourceRef destination), removeResource(ResourceRef ref), makeRedirect(ResourceRef source, ResourceRef destination) and getSub(ResourceRef subRef) which returns an inner Changer and delegates all its logic to its top ResourceChanger. |
| | 73 | The ResourceChanger will be abstract class implementing the ResourceReader interface and providing definitions of the other needed for the perfomAuto() methods. It will be extended by two classes - ModelResourceChanger and SubResourceChanger. |
| | 74 | The SubResourceChanger would implement simpler logic just delegating to the ResourceChanger they are made by. For They would need to know this parent to delegate to and also the ResourceRef by which they are made so that the delegation is made with the appropriate key. |
| | 75 | When a ModelChange is created it should be provided with everything needed to resurrect an AutoAction object so that it could get the resulting effect for any model anytime by resurrecting it and providing it with different ResourceChanger. So a ModelChange keeps the AutoAction class from which to take effect and all external fields it uses. |
| | 76 | |
| | 77 | == Meta Changes == |
| | 78 | Meta changes are the changes that does not change the model directly by setting particular values but change the current revisions by undoing and redoing user operations. |
| | 79 | |
| | 80 | == Accesses == |
| | 81 | The resource model is not accessible by the developers directly. For this are used special classes ResourceAccesses. They are responsible for location and manipulation of resources. |
| | 82 | |
| | 83 | === ResourceChannel === |
| | 84 | ResourceChannel provides fundamental methods for managing ResourceAccesses. It provides methods for opening, closing and getting AccessOptions and AccessInfo. AccessOptions are all the options of the view that is using this access. They identify the view id, user and the write scope of the ResourceChanel. AccessInfo is information about the location and security of a given ResourceChanel. |
| | 85 | |
| | 86 | === ResourceReader === |
| | 87 | |
| | 88 | The resource reader is interface implemented by all classes that have access to a model. The only method it provides is getRaw(Key<T> key). |
| | 89 | |
| | 90 | === ResourceLocator === |
| | 91 | The locator interface extends the ResourceChannel and adds a method for creation of resources. Only the locators can create resources of a certain type. |
| | 92 | |
| | 93 | === ResourceAccess === |
| | 94 | |
| | 95 | ResourceAccess is responsible for location and manipulation of a resource. It implements the ResourceChanel and ResourceReader and provides method for registering changes and tracking history. |
| | 96 | The accesses can be classified in different ways but the common classification is done by the kind of the resources they are managing. |
| | 97 | |
| | 98 | Root accesses are not extending the base class ResourceAccess . They don`t have a particular resource they are responsible for and they are used to access all the other accesses of their type. They implement the ResourceLocator interface and that is the reason they are referred to as 'locators'. |
| | 99 | Such accesses are the RootServerAccess which manages all top server accesses, RootMemAccess which manages all top mem accesses, RootFileAccess which manages all file accesses. |
| | 100 | The 'app' access is also a root access. It gives access to all top mem and top file accesses. |
| | 101 | |
| | 102 | Top accesses are used for access to the top level resources. They have a resource model, can register changes to it and keep the correct revision of the resource. They also implement the ResourceChanel interface. They know how to manage their inner accesses and delegate to the root accesses for higher level resources. All top resources will be opened in a top access and every inner access will be created based on a top access. |
| | 103 | |
| | 104 | Inner accesses are used for more convenient manipulation of inner resources to a top resource. They have no model of their own. They get their values from their top resource and delegate all their changes to it also. If you want to access a single frame`s properties you should have the top access of the book it is in opened and a inner access created for the appropriate ResourceRef that delegates to the top. |
| | 105 | |
| | 106 | Accesses have some specific logic for delegation of the method open(): |
| | 107 | |
