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)

   Expl

.. function:: user_logout()

   Expl

.. function:: user_delete()

   Expl

.. function:: model_render(model_name, mapper_name)

   Expl

.. function:: transformation_between(source, target)

   Expl

.. function:: transformation_add_MT(source_metamodels, target_metamodels, operation_name, code)

   Expl

.. function:: transformation_add_AL(source_metamodels, target_metamodels, operation_name, code)

   Expl

.. function:: transformation_add_MANUAL(source_metamodels, target_metamodels, operation_name)

   Expl

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

   Expl

.. 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.