modelverse/doc/wrappers.rst

Wrappers
========

Several wrappers can be defined for the Modelverse, as the Modelverse is merely a service running externally.
To communicate effectively, and automatically, a programming language wrapper is recommended.
Nonetheless, it is possible to communicatie manually as well.
These are some of the implemented wrappers.

Prompt
------

The simplest wrapper is the prompt wrapper, which merely sends the input and output directly to the user.
This wrapper has almost no code, but requires users to manually decide which content to send next.
It has no built-in integration with any model or action language compilers.
Nonetheless, it is an easy way to test out the raw communication protocol manually.

Python
------

The first real wrapper is the Python-based wrapper.
It provides a set of functions for use by Python code.
These functions wrap not only the interface, but also provides simple error handling through the use of Python exceptions and contains the model and action language compilers.
An overview of all functions and associatied exceptions is provided below.
All operations happen *synchronously*, meaning that they block until the Modelverse has performed the requested operation.

Note that some functions are only applicable in a certain *context*.
In practice, this means that you should first issue the *init* and *login* operations, as otherwise your connection with the Modelverse will not have started up yet.

Functions
^^^^^^^^^

.. function:: init(address_param="http://127.0.0.1:8001", timeout=20.0)

   Start up the connection to the Modelverse, residing at *address_param*.
   This connection is an XML/HTTPRequest and will start up a new task at the Modelverse.
   Retries for *timeout* seconds until giving up.
   The timeout includes all HTTP errors, and will therefore keep retrying even on failed attempts.
   As this request is synchronous, like all others, it will block until a connection has been established.

.. function:: login(username, password)

   Explanation
   Logs in the currently active Modelverse connection to the specified *username* and *password*.
   If the user does not exist, it will create a new user with the specified password.
   If the user already exists, it will try to log in with the provided password.

.. function:: model_add(model_name, metamodel_name, model_code=None)

   Explanation
   Upload a new model that can later be referred to as *model_name*, conforming to *metamodel_name*.
   The model itself is stored in the string *model_code*.
   This string is parsed using the HUTN compiler and subsequently sent to the Modelverse.
   When *model_code* is empty, an empty model is created.

.. function:: upload_code(code)

   Upload a string of *code* in the Action Language formalism.
   This piece of code is compiled with the HUTN compiler and sent to the Modelverse directly.
   Makes the assumption that the **construct_function()** operation is currently running on the Modelverse, as otherwise the data will be misinterpreted.
   This is normally only useful in model transformations, where you want to upload a piece of code on-the-fly (e.g., adding a breakpoint in Action Language).

.. function:: model_delete(model_name)

   Delete the model referred to by name *model_name*.
   This is a non-cascading delete, with almost no checks: model transformations depending on this model will likely become corrupted.

.. function:: model_list()

   Returns a list of all models existing in the Modelverse, together with their type.

.. function:: model_list_full()

   Returns a detailed list of all models existing in the Modelverse.
   This list includes information on permissions, owner, and group.

.. function:: verify(model_name)

   Verify whether *model_name* conforms to its specified metamodel, as stored in the Modelverse.
   Returns either "OK" if the model conforms, or a string specifying the reason for non-conformance.

.. function:: model_overwrite(model_name, new_model_code=None)

   Overwrites the model previously known under the name *model_name* with the model code in *new_model_code*.
   This operation differs from first deleting the model and then recreating it, as all metadata of the model is kept, such as access permissions.
   The new model can be kept empty, in which case the model will be cleared.

.. function:: user_logout()

   Logs out the current user, thereby closing the task.
   Subsequent operations will no longer have any effect, as the task was terminated.
   To log in as a different user, the *init* operation has to be executed again.

.. function:: user_delete()

   Delete the current user and thereafter log out.
   This removes the current user, making it impossible to log in as this user again.
   Existing models tied to this user, such as those the user is an owner of, remain bound to the (removed) user.
   While it is possible to recreate a new user with the same name, model permissions will not be inherited to this new user with the same name.

.. function:: model_render(model_name, mapper_name)

   Render the model by name of *model_name* using the mapper by name of *mapper_name*.
   Both parameters have to be known models in the Modelverse.
   Outputs a JSON representation of the rendered model.

.. function:: transformation_between(source, target)

   List all transformations that originate at *source* and end at *target*.
   Transformations can still be selected, even if they take more source models than those specified in the parameters.

.. function:: transformation_add_MT(source_metamodels, target_metamodels, operation_name, code, callback=lambda: None)

   Create a new model transformation operation.
   The new transformation takes *source_metamodels* as input, and generates *target_metamodels* as output.
   Both parameters are dictionaries of the form {name: metamodel_name}.
   The name is used later on in the model transformation as a prefix to the type.
   A single metamodel_name can be used for multiple names.
   Note that the target metamodel names may overlap with the source metamodel names, but the metamodel type should be identical.
   The operation is henceforth known by *operation_name* and is provided as a model in the string *code*.
   Optionally, a callback is defined which performs some operations on the merged metamodel, for example to define tracability links between (previously unrelated) metamodels.
   In the background, this operation does all necessary RAMification and model merging.

.. function:: transformation_add_AL(source_metamodels, target_metamodels, operation_name, code, callback=lambda: None)

   Creates a new action language operation.
   Similar to *transformation_add_MT*, but now does not require RAMification.
   The *code* parameter also is not specified as a Modelverse model (.mvc), but as action language (.alc).

.. function:: transformation_add_MANUAL(source_metamodels, target_metamodels, operation_name, callback=lambda: None)

   Creates a new manual operation.
   Identical to *transformation_add_AL*, but does not take any code as content.

.. function:: transformation_execute_AL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)

   Executes the Action Language model *operation_name* with *input_models_dict* as inputs and *output_models_dict* as outputs.
   For both dicts, the contents describe the mapping between the parameter names of the operation to the names in the Modelverse.
   Values in *input_models_dict* must be existing models, whereas values in *output_models_dict* can be non-existing upon invocation.
   A *callback* function can be defined when the action language model requires user input or output.
   This callback function can be used to communicate with the executing action language directly.

.. function:: transformation_execute_MANUAL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)

   Expl

.. function:: transformation_execute_MT(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)

   Expl

.. function:: transformation_list()

   Expl

.. function:: process_execute(process_name, prefix, callbacks)

   Expl

.. function:: permission_modify()

   Expl

.. function:: permission_owner()

   Expl

.. function:: permission_group()

   Expl

.. function:: group_create()

   Expl

.. function:: group_delete()

   Expl

.. function:: group_owner_add()

   Expl

.. function:: group_owner_delete()

   Expl

.. function:: group_join()

   Expl

.. function:: group_kick()

   Expl

.. function:: admin_promote()

   Expl

.. function:: admin_demote()

   Expl

.. function:: element_list(model_name)

   Expl

.. function:: types(model_name)

   Expl

.. function:: types_full(model_name)

   Expl

.. function:: read(model_name, ID)

   Expl

.. function:: read_attrs(model_name, ID)

   Expl

.. function:: instantiate(model_name, typename, edge=None, ID="")

   Expl

.. function:: delete_element(model_name, ID)

   Expl

.. function:: attr_assign(model_name, ID, attr, value)

   Expl

.. function:: attr_assign_code(model_name, ID, attr, code)

   Expl

.. function:: attr_delete(model_name, ID, attr)

   Expl

.. function:: read_outgoing(model_name, ID, typename)

   Expl

.. function:: read_incoming(model_name, ID, typename)

   Expl

.. function:: read_association_source(model_name, ID)

   Expl

.. function:: read_association_destination(model_name, ID)

   Expl

Exceptions
^^^^^^^^^^

.. exception:: ModelverseException

   Expl

.. exception:: UnknownError

   Expl

.. exception:: UnknownIdentifier

   Expl

.. exception:: UnknownType

   Expl

.. exception:: NotAnAssociation

   Expl

.. exception:: UnsupportedValue

   Expl

.. exception:: CompilationError

   Expl

.. exception:: NoSuchAttribute

   Expl

.. exception:: UnknownModel

   Expl

.. exception:: ConnectionError

   Expl

.. exception:: ModelExists

   Expl

.. exception:: PermissionDenied

   Expl

.. exception:: InvalidMode

   Expl

.. exception:: InterfaceMismatch

   Expl

Custom
------

Other wrappers can be made as desired, in whatever language required.
This is due to the fact that the Modelverse communicates only through XML/HTTPRequests.
As such, all languages that support this, can simply mimic the interface used by any of the implemented wrappers.