From cbf71e46dad2d775a8fbab4c729b89e5ad64aff1 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Tue, 16 Feb 2010 04:45:52 +0100 Subject: [PATCH] Planning and designing the session API --- doc/devel/draw/Session.Facade-1.svg | 704 ++++++++++++++++++++++++++++ wiki/draw/SessionFacade1.png | Bin 0 -> 8458 bytes wiki/renderengine.html | 38 +- 3 files changed, 735 insertions(+), 7 deletions(-) create mode 100644 doc/devel/draw/Session.Facade-1.svg create mode 100644 wiki/draw/SessionFacade1.png diff --git a/doc/devel/draw/Session.Facade-1.svg b/doc/devel/draw/Session.Facade-1.svg new file mode 100644 index 000000000..7316d816a --- /dev/null +++ b/doc/devel/draw/Session.Facade-1.svg @@ -0,0 +1,704 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + Structure of Placement Scopes + + + Ichthyostega + + + design sketch: Relation of the nested Placement Scopes within the Lumiera session + 2009 + + + + + + + + + + + + + + + Session + + Timeline(s) + + + + + Sequence(s) + all() + default() + focus() + + + + + + + Axis + Pipes + all() + + + + + + + diff --git a/wiki/draw/SessionFacade1.png b/wiki/draw/SessionFacade1.png new file mode 100644 index 0000000000000000000000000000000000000000..ca03a95081675edbfa31603a18ad4632d41da052 GIT binary patch literal 8458 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 -
+
When querying contents of the session or sub-containers within the session, the QueryFocus follows the current point-of-query. As such queries can be issued to explore the content of container-like objects holding other MObjects, the focus is always attached to a container, which also acts as [[scope|PlacementScope]] for the contained objects. QueryFocus is an implicit state (the current point of interrest). This sate especially remembers the path down from the root of the HighLevelModel, which was used to access the current scope. Because this path constitutes a hierarchy of scopes, it can be relevant for querying and resolving placement properties. (&rarr; SessionStructureQuery)
 
 !provided operations
@@ -3588,7 +3588,7 @@ There is a tight integration with PlacementScope through the ScopeLocator, which
 !implementation notes
 we provide a static access API, meaning that there is a singleton (the ScopeLocator) behind the scenes, which holds the mentioned scope stack. The current focus stack top, i.e. the current ScopePath is managed through an ref-counting handle embedded into each QueryFocus instance. Thus, effectively QueryFocus is an frontend object for accessing this state. Moreover, embedded into ScopeLocator, there is an link to the current session. But this link is kept opaque; it works by the current session exposing an [[query service|QueryResolver]], while QueryFocus doesn't rely on knowledge about the session, allowing the focus to be unit tested.
 
-The stack of scopes must not be confused with the ScopePath. Each single frame on the stack is a QueryFocus and as such contains a current ScopePath. The purpose of the stack is to make the scope handling mostly transparent; especially this stack allows to write dedicated query functions directed at a given object: they work by pushing and then navigating to the object to use as starting point for the query, i.e. the //current scope.//
+The stack of scopes must not be confused with the ScopePath. Each single frame on the stack can be seen and accessed as a QueryFocus and as such relates to a current ScopePath. The purpose of the stack is to make the scope handling mostly transparent; especially this stack allows to write dedicated query functions directed at a given object: they work by pushing and then navigating to the object to use as starting point for the query, i.e. the //current scope.//
 
 !!!simplifications
 The full implementation of this scope navigation is tricky, especially when it comes to determining the relation of two positions. It should be ''postponed'' and replaced by a ''dummy'' (no-op) implementation for the first integration round.
@@ -4099,7 +4099,7 @@ For implementation, the HighLevelModel can be reduced to a compound of interconn
 MObject lifetime is managed by reference counting; all placements and client side references to an MObject share ownership. The placement instances attached to the session are maintained by the index; thus, as long as an placement exists, the corresponding object automatically stays alive. A bare PlacementRef on the other hand doesn't guarantee anything about the referred placement; when dereferencting this reference token, the index is accessed to re-establish a connection to the object, if possible. The full-fledged MObjectRef is built on top of such a reference token and additionally incorporates a smart-ptr. For the client code this means, that holding a ref ensures existence of the object, while the //placement// of this object still can get removed from the session.
-
+
"Session Interface", when used in a more general sense, denotes a compound of several interfaces and facilities, together forming the primary access point to the user visible contents and state of the editing project.
 * the API of the session class
 * the accompanying management interface (SessionManager API)
@@ -4114,14 +4114,38 @@ MObject lifetime is managed by reference counting; all placements and client sid
 ** Automation
 * the [[command|CommandHandling]] interface, including the [[UNDO|UndoManager]] facility
 
-{{red{WIP ... just emerging}}}
-
 !generic and explicit API
-The HighLevelModel exposes two kinds of interfaces (which are interconnected btw): A generic, but somewhat low-level API, which is good for processing, and a more explicit API providing access to some meaningful entities within the model. Indeed, the latter (explicit top level entities) can be seen as a ''facade interface'' to the generic structures:
+The HighLevelModel exposes two kinds of interfaces (which are interconnected and rely on each other): A generic, but somewhat low-level API, which is good for processing &mdash; like e.g. for the builder or de-serialiser &mdash; and a more explicit API providing access to some meaningful entities within the model. Indeed, the latter (explicit top level entities) can be seen as a ''façade interface'' to the generic structures:
 * the [[Session]] object itself corresponds to the ModelRootMO
 * the one (or multiple) [[Timeline]] objects correspond to the BindingMO instances attached immediately below the model root
 * the [[sequences|Sequence]] bound into these timelines (by the ~BindingMOs) correspond to the top level [[Track]]-~MObjects within each of these sequences.
-Thus, there is a convenient and meaningful access path through these facade objects, which of course actually is implemented by forwarding to the actual model elements (root, bindings, tracks)
+[<img[Object relations on the session facade|draw/SessionFacade1.png]]
+
+Thus, there is a convenient and meaningful access path through these façade objects, which of course actually is implemented by forwarding to the actual model elements (root, bindings, tracks)
+
+Following this access path down from the session means using the ''dedicated'' API on the objects retrieved.
+To the contrary, the ''generic'' API is related to a //current location (state),// the QueryFocus.
+
+
+
+!purpose of these APIs
+* to discover
+** by ID
+** by filter
+** all contained
+* to add
+* to destroy
+
+
+{{red{WIP ... just emerging}}}
+
+
+!!!Questions
+* what is the exact relation of discovery and mutations?
+* What is the point of locating them on the same conceptual level?
+* how to observe the requirement of ''dispatching'' mutations ([[Command]])?
+* how to integrate the two possible search depths (children and all)?
+* how is all of this related to the LayerSeparationInterfaces, here SessionFacade und EditFacade?