Perspectives Technical Documentation

9.1. Booting models

A Perspectives Distributed Runtime installation – e.g. as included in MyContexts – needs Perspectives Models to operate. The basic requirement is model://perspectives.domains/System. This model is retrieved automatically from the website perspectives.domains while installing MyContexts. However, the end user will want to acquire more perspectives and thus needs to add models.

This text explains how this is achieved in the PDR.

9.1.1. Models

Conceptually, a model is a collection of types. Physically, it is a file (the domeinfile). Models reside physically in a repository on a server on the internet. A PDR installation (such as MyContexts) keeps a private collection of models, usually locally.

End users want to extend their perspectives and therefore need to be able to explore models published by authors. To this end, we have the context type Manifest. Instances of this type are public contexts.

End users also need an overview of locally available models. These are currently collected in the end user’s instance of the sys:PerspectivesSystem context. This is an indexed context, meaning the user can access it by entering its name in the address bar of the browser.

Its full name would be model://perspectives.domains/MySystem. However, MyContexts applies fuzzy matching to names, so MyModels stands a good chance to land you in the right place.

But the MySystem context can be accessed from the menubar of MyContexts, anyway. It is accessible through the Home icon.

An end user whose installation does not yet have this model, will acquire it automatically upon visiting the description. (S)he then can boot the model by executing an action on the screen.

9.1.1.1. Booting a model

Using model://perspectives.domains/Models as an example, we’ll show the boot sequence that applies for any model. The purpose of booting is to instantiate indexed contexts and indexed roles of the model and register them with the system and to add the model description to the collection in MyModels.

The first step is to create an instance of the context type ModelsOverview. The system will create a unique identifier for it.
As this type is indexed, we then create a new instance of the role IndexedContexts in sys:MySystem (the indexed context of the system model). We fill it with the context instance we created in the first step.
On this role we add a value to the property Name. This value is precisely the indexed name itself: model://perspectives.domains/MyModels. This construction enables the PDR to maintain a table of indexed names and their local (private) identifiers.
Finally, we add the model’s description to the list of such descriptions in MyModels.

So, in the case of model://perspectives.domains/Models, we end up with an instance of MyModels that has just one entry: the description of its own model.

These steps are implemented in model://perspectives.domains/Models itself, in the form of an Action in the perspective of the Visitor role in the model description.

Acquiring model://perspectives.domains/Models is different from other models in one respect: the type of the model description is contained in this model itself. That is the reason that this model is added automatically to the local installation upon visiting its description. This is the only model for which this is the case. In all other models, the model is only loaded on booting.

9.1.1.2. Booting System

As stated above, model://perspectives.domains/System is a requirement for a PDR installation to operate. We cannot use a client such as MyContexts to acquire this model. Hence, on installing MyContexts, System is installed by the code that runs MyContexts. At that time, we do not have an instance of MyModels; indeed we do not even have model://perspectives.domains/Models! As a consequence, System is not listed in MyModels.

System differs from other models in another respect. It’s indexed names (MySystem and Me) are hard-coded and they are not listed in MySystem.

9.1.2. Authoring a model: booting revisited

The author of a model must include the Action that allows the end user to boot it. This action is fairly standard, but its details need to be written again for each model. Here is the code for model:perspectives.domains/SimpleChat.

perspective of Visitor
  action Boot
    -- Create the indexed context:
    createContext cht:ChatApp bound to IndexedContext in sys:MySystem

    -- Add the indexed name:
    Name = "model://perspect.it/SimpleChat$MyChats"
      for sys:MySystem >> filter IndexedContext
        with binding >> context >> contextType == cht:ChatApp

    -- Add the model description to MyModels:
    bind https://cw.perspect.it/SimpleChat to LocalModels
      in mod:MyModels

Obviously, the value model://perspect.it/SimpleChat$MyChats should be customised in each model.

9.1.3. Booting the Perspectives Universe

A special case of booting has happened during development of Perspectives. We describe it here just in case it has to happen again.

We would like a fresh MyContexts installation to have a list of elementary models that the end user can add to her installation. In other words, we want the repository for the namespace model://perspectives.domains to be available. We could try to include the corresponding Repository description by adding this line to the boot sequence instructions:

bind publicrole pub:https://perspectives.domains/cw_servers_and_repositories/#perspectives_domains$External to BaseRepository in sys:MySystem

However, to compile model://perspectives.domains#System with this line, the compiler needs to be able to look up the type model://perspecives.domains/CouchdbManagement locally - that is in an installation that already has this model. This introduces a catch-22 because this latter model requires the former - hence, we have introduced a circular dependency even though only one model (CouchdbManagement) refers to the other.

We’ve taken the following approach to avoid this problem:

compile model://perspectives.domains#System with this line commented out;
set up an installation with this version of System;
compile model://perspectives.domains#CouchdbManagement with that installation;
uncomment the line;
recompile model://perspectives.domains#System and add it to the Repository

Now, each next installation will have a reference to the base repository (it can be found at https://perspectives.domains/cw_servers_and_repositories/perspectives_domains)

9.1.3.1. Compiling the System model

How do we compile a model before we have a working installation? The developer of the PDR can do so, using a testscript. Here is an example:

  test "upload model://perspectives.domains#System to repository from files" $ runP do
    -- Add a password for "https://localhost:6984/"
    modify \s@({couchdbCredentials}) -> s {couchdbCredentials = insert "https://localhost:6984/" "geheim" couchdbCredentials}
    addAllExternalFunctions
    _ <- loadCompileAndCacheArcFile' "couchdb" modelDirectory
    _ <- loadCompileAndCacheArcFile' "serialise" modelDirectory
    _ <- loadCompileAndCacheArcFile' "sensor" modelDirectory
    _ <- loadCompileAndCacheArcFile' "utilities" modelDirectory
    errs <- loadCompileAndCacheArcFile' "perspectivesSysteem" modelDirectory
    dCache <- domeinCache
    if null errs
      then uploadToRepository (DomeinFileId "model://perspectives.domains#System")
      else liftAff $ assert ("There are instance- or model errors for model://perspectives.domains#System: " <> show errs) false

Now notice the call to uploadToRepository. It infers the location of a database on the internet from the model identifier. It will be: https://perspectives.domains/models_perspectives_domains/. This database must be available for the script to run! That is, Couchdb must be installed on the server that hosts perspectives.domains and the database (and its read-version models_perspectives_domains_read) must be there. See ConfigConfiguring an Apache VirtualHost running Couchdb for a domain of perspectives modelsuring for details on how to set up Apache for this domain.