Workflow for services/documents

see also janta and  poster.

1. The user makes a request for some unique id services/documents/ID.ext
2. Get Document from DocumentCommons (DocumentCommons.getDoc(ID))
  if document not in document commons (DocumentDoesNotExist)
   Retrieve document from backend (Retriever.getDoc(ID))
   Add document to document commons (DocumentCommons.addDoc(document))
3. Set the corresponding notations
4. Convert to suitable format (*.ext)
5. Return the document to the user

Janta Components

• DocumentCommons?: Handles the collection of documents in-memory; provides different methods, for adding and extracting data from these documents and to create new documents
  • includes a ContentCommons?
  • includes a NarrativeCommons?
  • addDoc(XOM Document)*: Extracts all knowledge items (Infoms = XOM Elements) from the document and adds them to the ContentCommons?, Extracts the NarrativeStructure? (=XOM Documents) of the Document by replacing all upper-level Infoms with include-references (includes)** to their absolute IDs and adds the NarrativeStructure? to the NarrativeCommons?
  • getDoc(ID): Retrieves a NarrativeStructure? with ID from the NarrativeCommons? and flattens it into a XOM Document
  • flattenStructure(ID): Converts a NarrativeStructure? into a Document by replacing all include-references with XOM representation of the referenced Infoms**
  • getToc(ID): Returns the NarrativeStructure? with ID (a XOM Document)
  • Future: getDoc(ID, Context): Retrieves a NarrativeStructure? for a given Context by matching the context parameters with the properties of the NarrativeStructure? (optionally we can add a "match" value for this request), if not yet such a NarrativeStructure?, then create a new one calling createDoc(ID, Context)
  • Future: createDoc(ID, Context): template for generating a variant for a given NarrativeStructure?, replacing all include-reference with an include-reference to a variant Infom, e.g. replacing all include-reference to English Infoms with include-references to German Infoms to create a German variant of the NarrativeStructure?; the new NarrativeStructure? is added to the NarrativeCommons?, it is annotated with the given Context and linked to the original structure ID via a variant relation
  • Future: getGuidedTour(List of IDs): Retrieves a GuidedTour? for the list of infoms, if not yet such a GuidedTour?, call createGuidedTour(List of IDs)
  • Future: createGuidedTour(List of IDs): template for generating a guided tour given a list of IDs to Infoms in the ContentCommons? that should be part of the GuidedTour?
  • Future: getSlides(ID): Retrieves a NarrativeStructure? with ID, if NarrativeStructure? not a SlidePresentation?, a new NarrativeStructure? is generated --- createSlidesFor(ID)
  • Future: createSlidesFor(ID): template for generating a slide presentation for a given NarrativeStructure?, the new NarrativeStructure? is a variant and created by copying all of ID's include-references (includes)** into a slide layout (template); the new NarrativeStructure? is added to the NarrativeCommons? and is linked to the original structure ID via a variant properties and relation (e.g. "slides-for")
  • Future: more sophisticated queries

• ContentCommons?: handles a collection of interlinked knowledge units (Infoms), all Infoms have a globally unique ID
  • includes a ContentGraph?
  • includes a ContentContainer?
  • addInfom(Infom)*: adds the Infom's abs-ID/Category/Properties/Relations to the ContentGraph? and the Infom (XOM Element) to the ContentContainer?; extracts child-Infoms from nested Infoms and replaces these child-Infoms with include-references (includes)** in the nested Infom
  • getAbsoluteID(relative-ID): returns the absolute IDs, which are generated from the ID of the document and the relative-ID of the Infom: "doc-ID/Infom-ID" (there is a XOM method for this)
  • getInfom(ID): returns the Infom with ID from ContentContainer? (used for flattening a narrative structure into a document, all other methods only return IDs)
  • getInfomID(ID, Context): returns the identifier for the variant for Infom with ID that matches the given Context best; the context parameters are matched to the Infom's properties in the ContentGraph?
  • Future: getExamplesFor(ID,int): retrieves identifiers for int examples for the Infom with ID
  • Future: getAllExamplesFor(ID,int): retrieves identifiers for all examples for the Infom with ID
  • Future: more sophisticated queries

• ContentGraph?: represents categories, properties, and interrelation of Infoms
  • addID(ID): adds the ID of the Infom to the ContentGraph?
  • addCategory(ID, Category): adds the Infom's category
  • addProperties(ID, properties): adds properties of an Infoms
  • addRelation(ID, relations): add relations to other Infoms
  • getCategory(Infom): returns the category of the Infom, in OMDoc the name or type attribute of the XML element representing the infom
  • getProperties(Infom): returns all properties, in OMDoc all XML attributes (including cross-references to other Infoms)
  • getRelation(Infom): returns all relations of the Infom to other Infoms, e.g. for Theories the method parses the theory's imports

• ContentContainer?: a map of Infoms (XOM Elements)
  • addInfom(ID, Infom): adds the ID as key and the Infom as value
  • getInfom(ID): Retrieves the Infom with ID and flattens it
  • flattenInfom(ID): replaces include-references (includes)** in the Infom with the referenced Infoms; returning a self-contained Infom with no include-references

• Infom: XOM Element, any non-narrative element of a document (Theory or Statement, e.g. example, proof, definition, omtext, symbol, formulae, ...), NotationDefinitions? are not Infom, variants are not Infoms as they do not represent information of the documents but relations between Infoms
  • upper-level Infom: Are all Infoms that are retrieved without parsing nested Infoms; Infoms cannot include NarrativeStructures?
  • nested Infom: An infom that includes other Infoms, e.g. a theory can include example, definitions, ... , currently we do not go below statement level, e.g. we do not consider an example with a formulae as nested
  • a self-contained Infom, an Infom without include-references

• NarrativeStructure?: XOM Document without any Infoms, all upper-level Infoms are replaced by include-references (includes), NarrativeStructures? include NotationDefinitions? and VariantRelations?
  • a self-contained NarrativeStructure? is a Document

• NarrativeCommons?: handels a collection of interlinked narrative structures, all structures have a global unique ID
  • includes a NarrativeGraph?
  • includes a NarrativeContainer?
  • addStructure(NarrativeStructure?): adds a Narrative Structure to the NarrativeGraph? and NarrativeContainer?;
  • getStructure(ID): Retrieves a NarrativeStructure? from the NarrativeContainer?

• NarrativeGraph?: represents categories, properties, and interrelation of NarrativeStructure?
  • addID(ID): adds the ID of the NarrativeStructure? to the NarrativeGraph?
  • addCategory(ID, Category): adds the NarrativeStructure?'s category
  • addProperties(ID, properties): adds properties of a NarrativeStructure?
  • addRelation(ID, relations): add relations to other NarrativeStructure?
  • getCategory(Infom): returns the category of the NarrativeStructure?, e.g. "Section" or "Paragraph"
  • getProperties(Infom): returns all properties, e.g. context parameters such as language=de, or format=slides
  • getRelation(Infom): returns all relations of the NarrativeStructure? to other NarrativeStructures?, e.g. variant relation such as "translation" or "same-content-as" or "slide-presentation-for" (TODO: specify variant relations)

• NarrativeContainer?: a map of NarrativeStructures?
  • addStructure(ID, NarrativeStructure?): adds the ID as key, and NarrativeStructure? as value
  • getStructure(ID): Returns the NarrativeStructure? with ID

• GuidedTour? is a NarrativeStructure? which is annotated with a list of Infom-IDs that are covered by the GuidedTour?. getGuidedTour selects an existing GuidedTour? if it exactly matches the list of required Infom-IDs (TODO: revise this kind of annotation)

• Context: a list of key-value pairs, see JOMDoc

• NotationDefinition?: a mapping from OpenMath? and MathML

• VariantsRelation?: a specification of difference and similarities between Infoms and NarrativeStructures?; Processing VariantRelations? adds further Relations in the ContentGraph? and NarrativeGraph?

• Retriever: retrieves a document from the backend (file or InputStream?)
  • getDoc(ID): retrieves the document and returns the XOM Document

• NotationRenderer?: sets the corresponding notations; is configure with notation options, see ticket:533

• FormatRender?: converts document into suitable XML format; is configure with format options (the optional extension of the ID in the request); currently we only support *.xhtml

(* No change management: Integration of documents into document commons is trivial. We only add documents, no cross-reference are constructured, no equalities are considered, no merging.

(** include-references (include) are represented by ref-elements in OMDoc, the replacing of includes with Infoms (called flattening or ref-contraction) and replacing of Infoms with includes (ref-expansion) is supported by JOMDoc