KRNL ToDo and TBD

Open Issues

• TreeStructure imposed on other documents -- how?
  • ex: Legacy email (=> tree of paragraphs)
  • ex: array of musical notes (=> tree of sections)
• ViewControl -- class or interface? How will it work?
• Display/printing mechanisms TBD
  • probably done via java 2D graphics, passing a graphics context.
  • Works for printing as well as online viewing?
• Stylesheets -- need a mechanism for defining StyleControl objects that are used to display content. StructureNodes and ContentNodes then need pointers to StyleControl objects, or else the content display mechanism needs to look up StyleControl using ContentNode name.
• VersionControl
  • static init: set up userID and systemID
  • ??add with getUser and getVersionStamp methods that nodes use to init themselves??
  • ??add Factory methods that generate nodes??
    
• Do we need separate LinkDisplayPolicy and ContainedNodeDisplayPolicy classes, or is one DisplayPolicy class sufficient for both?
• User Functionality
  • "commit" and "publish" mechanisms
    -- the ability to control the visibility of changes (needs to be implemented in the outer system, but the KRNL needs to support those behaviors)
  • Does a "touch" that clears highlighting that marks a change consist of a click or a mouse over?
• ORDERED_LIST and UNORDERED_LIST list types, or single LIST type with different. attributes??
• Type-free KRNL?? Or type-safe??
• Genereral FILTER objects
  • VIEW objects (sally as programmer, as mother, as daughter, as wife) -- to define ROLES
  • LOCALIZATION, for example an InlineNode filter object for currency displays.
  • ViewControl objects: how deep to display, what kinds of nodes to display, single or multi-line display
    

Action Items

Design

• change AbstractNode to AbstractEntity, NodeTypes to EntityTypes, nodetype to entityType
• change "nodetype" and "type" in all classes to "entitytype" since the entities are nodes and lists.
• relationship of prev-version links to AbstractVersionedWrapper, UndoVersionWrapper, and OldVersionWrapper
• Add constructors to abstract classes!! --specify parent.
• Test: if abstract class has a non-null constructor, can subclass define one that doesn't call super()?
• abstract class static constructor calls an abstract method to set the node type! --classes implement the method
• StructureLink
  • Can be in a StructureList, like a StructureNode
  • Points to a StructureNode
  • Adds link type, which may dictate a display policy
  • Specifies version (or null for most recent version)
  • Includes a ViewControl (should version be in that??)
  • Virtually identical to a NodeLink in a ContentList
    • except that "expand inline" is not an appropriate display policy for a NodeLink
    • note to that "hide link" is not an appropriate display policy for an INLINE NodeLink
    • "hide link" is only appropriate for StructureLinks and for APPENDED NodeLinks (e.g. references and other such "decorations" as usage may dictate.
• Categories
  • Changes to a Category list are reported to all parents
    • When the parent is a structure node, it reflects an add or remove of a category
      • Note: No "moves" for category lists
    • When the parent is the main list of categories, it reflects a difference in the set of categories
  • Changes to a Category node are NOT reported to all parents
    • They are still versioned, hence delivered with other new nodes during system sync-age
      (and marked as "new")
    • The change is reported to the main category list/tree (and up the hierarchy) but not to structure nodes that have that category
    • That way, simple category name-changes are not treated like document changes
    • So categoryNodes need a single parent pointer (category list) and a nodeList that is treated like a parent list, when appropriate
  • When a category "splits" (some members become one thing, others become something else, as in ToDo->Bug:Open or Feature:Open), or when categories "merge":
    • The split/merge is treated as a name change.
    • Changes are versioned and reported to the main category list.
    • Category lists for affected structure nodes are modified with a special NON-VERSIONED change that replaces the old pointer with a new one.
    • CategoryList therefore needs a replace(existingCategoryNode, newCategoryNode) API that doesn't do versioning
• StructureNode: Flags (implement and move this section to N&L doc)
  • Visited
    • initialized to false when new nodes delivered after synchronization
    • set to true by outer system after node displayed, mouse over, or click, depending on implementation and user preferences
  • CurrentlyVisited
    • lets the outer authoring/viewing) system identify cycles when displaying or processing nodes, and prevent re-vistitng.
  • Unpublished
    • A "new" flag that can be set to the indicate that the node is not visible to the outside world. The sync system ignores them. The display system can highlight them in some muted, pastel way.
      
• IMPLEMENT:
  • StructureNexus interface (multiple sublists -- for ContainedNode and StructureNode)
  • AbstractMultipParentNode extened by StructureNode, CategoryNode
  • All nodes get a parent ptr when created
  • MultiParentNodes add to parent list
  • VersionedNodes store in variable
  • FASCINATING OBSERVATION: Nodes are either multiparented or versioned, not both. Current architecture uses that fact to define single parent ptr in AbstractVersionedNode. Question: Can that distinction be defended on a philosphical basis, or is there some possiblity that one day a node which is both multiparented and versioned will be needed?
  • Ques: CategoryNode. How are changes in category names versioned/undone?
  • ContentNode changes: insert(start, text), delete(start, end), set():
    • make copy, change version stamp
    • invoke parent.ContentChanged()
  • ContentList changes:
    • add, move, delete:
      • make copy, change versions stamp
      • Ques: how to invoke parent.ContentChanged()
        • ListChanged would be nice. Could be defined in AbstractList
          but that breaks when applied to StructureNodes
        • generic types ideal here. Can be defined in AbstractList but still be unique for each subclass
        • generic types would also be ideal for constructors
    • split(node, charPos)
      • to insert a link node, for example
      • NON-VERSIONED operation
    • normalize()
      • merge adjacent text nodes
      • NON-VERSIONED operation
  • StructureList
    • collect() operation. Removes node from current location (versioned) and adds it to a collection buffer
    • insertCollection() operation inserts all elements from collection buffer
      • this is a single-version operation. That's the reason it needs to be built into the kernel.
    • undo() needs to undo the insert
    • It must also be possible to inspect the current collection. Reason: Further undos will change the collection. But it is not possible to undo all additions to the collection at one time, because other edits may have occurred. So the collection should appear in a window of its own, and possibly allow for rearranging items.
  • StructureNode:
    • implement ContentChanged, StructureChanged, CategoryChanged
      • on receipt of change, pass on to all entries in parent list
    • invert(subnode)
      • moves the subnode to the current position, inverting the hierarchy at that point
      • moves current node and everything in the hierarchy under the subnode as "history"
• changes to category nodes, how recorded?
  • ex: "todo" changes to "bug:open" or "feature:open"
• parent lists
• change reporting
• Only StructureNodes have parent lists? No: CategoryNodes can have multiple parents, too.
  But StructureLists, CategoryLists, AttributeLists, and ContentLists only have one parent.
  And all ContentLists and TextNodes in a content hierarchy have the same parent.
  Class hierarchy should be:
  • AbstractNode / AbstractEntity
    • AbstractNexusNode (NexusNode??) -- have parents list & sublists
      • StructureNode -- to report changes
      • CategoryNode --to find nodes in that category & report changes
      • AttributeNode -- to find nodes with that attribute ??
    • AbstractVersionedNode
      • AbstractList -- have a single parent
      • AbstractContentNode -- have a single parent
        • InlineNode
        • TextNode
        • AbstractLinkNode
• Version IDs
  • needed to identify versions, making it possible to reconstruct a particular version
  • set when adding timestamps?
  • really want to condense information for this, so final changes are identified, not every step of undo.
    ex: change a list from unordered to ordered by removing and readding it
  • the unstamped versions list CAN BECOME the version ID list, at this point
• Parent list versioned?
  • probably doesn't need to be, since the act of adding to a list chgs the node's parent list, the undoing the operation should remove it, which would take it out again.
• undo class -- find code -- Java patterns book?
  • Since undo info is needed for versioning, and since versioning needs to be automatic, the operations need to be defined in the structures, so they can do the versioning and store the undo info.
• versioning:
  • parent lists and version lists are INTERNAL lists. They are not versioned, and must always exist.
  • OTHER lists (category, attribute, structureList) are manipulated by the user system. Changes made to them are versioned, and affect parent lists.
  • When nodes are created, their parent must be the structure node that owns the list they are in
  • When lists are created, their parent must be the structure node that owns them
  • TBD: Additive changes, to limit versions:
    • ex: move a node up, then move it up again. Counts as one change, before time stamping occurs. Accomplished in the user system by invoking a move(node, newPosition) API in the StructureList (other lists have add/remove, no move)
    • ex: Correct one spelling error, then correct another one in the same node. Equals one change?
      • ALSO: Need to think forward to even more fine-grained version control (identify the letter that was added to correct a misspelling, for example)
  • Q: new versions are automatically versionStamped. What about new nodes? how are they automatically created with an originalVersion stamp that matches the latestVersion stamp?
  • VersionLists
    • not an extension of AbstractList, since they are not themselves versioned.
      (more fundamental than that)
    • option #1: one per node
    • option #2: one per list
    • NEED UNDO INFO TO VERSION DELETES, YES???
  • new node versions are currently unattached to any list, and must be added to the list. That means the calling system must store the old version. Not good. The system needs to
  • set the new version stamp on the current entry (done)
  • store the copy in the node's versionList (todo) -- HOW???
    Does every node have a version List?
    
  • code for reportChange() method (depends on parent list)
  • lists need pointer to StructureNode "parent" (owner?)
  • Parent interface ???
    
  • so far, StructureNodes don't know what lists they contain.
    But to report changes to parents, they need understand that they have a parent list, and know how to use it. So perhaps StructureNodes should, at a minimum, initialize themselves with a ParentList.
  • Lists contain a StructureNode pointer, but StructureNodes ALSO contain a structureNode pointer, rather than a list pointer. Should the list be a factory that creates nodes of the right type, with a properly intialized parent?
• contentList
  • when parent is a structureNode, we want to report changes, yes?
    
  • but not when parent is an InlineNode??
  • if parent list is only used for change-reporting, every content node and list under it should point to parent?
  • reportChange() needs to know what kind of node it is, and know what parentList latest version to change -- or else StructureNode needs multiple changeNotification methods, one for each list
  • need a recordChange() method in current
    
• report changes by textNodes? contentNodes?
• StrucutrenNode meta-version field for latest change in any sublist (to improve traversal speed)
  That way, if 10 entries exists in a StructureList, and only one changed, only that one's sublist versions need to be examined. (note: need different terms for list of nodes in a structure list (logical sublist), and the lists in a structure node (mechanical sublists).
  
• code for set() , add(), remove(), operations
  
• diagram?
  
• categories
  -- e.g. IBIS:question
  -- validation mechanism (uncategorized valid everywhere)
  -- validate when adding or changing a category or moving a node,
      to see if the category violates existing category-relationship rules (CRRs)
  --CategoryValidation class? How are category restrictions represented?

Implementation

• Build add, insert, del, and move operations
• Link types need a type-related mechanism (NotificationProxy) to determine whether they are strongly connected (notify parents of changes) or weakly connected (don't)
• When publishing, collapse changes and stamp version times.
  Also: move the list of changes to a tree, where the version identifer is identified by the user as "major, minor, or micro". (Defines logical versions, and maintains a single tree of all nodes in the system, in version order.)
• ContentNode
  • size(): return this.size
  • abstract getText(from, to)
  • Inline node: sizeChange(+/-)
    • But this means content nodes need to pointer to ContentParent, as well as to StructureParent!
    • needs to report sizeChange to ContentParent, and contentChange to StructureParent.
• StructureNode
  • contentChange()
  • categoryChange()
  • structureChange()
  • ?? attributeChange() ??
• LinkNode.getContent delegates to LinkDisplayPolicy which returns "" or call getLinkText().
• ContainedNode.display() passes ContainedNode's type to ContainedNodeDisplayPolicy, which calls node.display(g, VC), or calls node.linkDisplay(g), or simply returns
• add type and getLinkText methods to ContainedNode
• interfaces: VersionControl, ViewControl, LinkDisplayControl?
  relationship of ViewControl to LinkDisplayControl?
• define LinkControl interface:
  • requires objects that implement it to provide
    • getType() method
    • getViewControl() method
    • (unfortunately, there is no good way to force the constructors to specify those values, and we need to avoid set() methods to force versioning -- or we could add set() methods and declare by fiat that view control changes and link type changes are not versioned -- TBD)
  • Implementation:
    • ContainedNode extends StructureNode implements LinkControl
    • Beter: Define a structure node interface. ContainedNode should implement that, as well, instead of extending StructureNode.
    • implementation of reportChange():
      • in NodeLink, changes versionID and stops
      • in ContainedNode, changes current versionID and reports change to parents
    • LinkDisplayPolicy:
      • expand node in place if calling node is an instance of ContainedNode, and policy says to do that
      • if policy says to expand, and calling node is an instance of Nodelink, show link instead
• ConflictNode -- predefine the content structure for a node that will contain conflicting links.
  --addLinkTo(node) api
  --resolveTo(node) api
• ItemNotFoundException, ListNotFoundException, ListExistsException, UnstampedVersionException, LinkDisplayException
• versionNode: add "uncommitted" flag??? or implement as System:XXX categories that normally go undisplayed
• attribute list

...