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)

   Executes the manual model operation *operation_name*.
   Furthermore, this is identical to *transformation_execute_AL*, with the exception of the *callback* function.
   In this case, the callback function can be just another series of Modelverse operations, though pertaining to a single model.
   As such, the *model_name* parameter of these operations **MUST** be set to *None*.

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

   Executes the model transformation operation *operation_name*.
   Identical to *transformation_execute_AL*.

.. function:: transformation_list()

   Returns a list of all operations specified in the Modelverse, together with their type.

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

   Execute the process model stored as *process_name*.
   All models are stored with their names prefixed with *prefix* to allow for multiple executions of the same model.
   Note that this applies to the resolution of input models as well.
   Optionally, a dictionary of *callbacks* can be defined with as key the operation that is being executed, and value the actual callback.
   The callbacks must be similarly defined just like how they were defined in the individual *transformation_execute* operations.

.. function:: permission_modify(model_name, permissions)

   Change the permissions of *model_name* to *permissions*.
   The permissions is a string of three characters, each between 0 and 2.
   The format is similar to the UNIX permission system: the leftmost character is the permission for the owning user, the middle character for members of the ownin group, and the rightmost character for all other users.
   Character 0 signifies no access, 1 read-only access, and 2 full read/write access.

.. function:: permission_owner(model_name, owner)

   Change the owner of the model *model_name* to *owner*.

.. function:: permission_group(model_name, group)

   Change the owning group of the model *model_name* to *group*.

.. function:: group_create(group_name)

   Create a new group named *group_name*.

.. function:: group_delete(group_name)

   Delete the group named *group_name*.

.. function:: group_owner_add(group_name, user_name)

   Add user *user_name* as an owner of group *group_name*.
   This automatically makes the user join the specified group if this was not yet the case.

.. function:: group_owner_delete(group_name, user_name)

   Remove user *user_name* as an owner of group *group_name*.

.. function:: group_join(group_name, user_name)

   Have user *user_name* join the group *group_name* as an ordinary user.

.. function:: group_kick(group_name, user_name)

   Remove user *user_name* from the group *group_name*.
   If the user was an owner of the group, these permissions are also revoked.

.. function:: admin_promote(user_name)

   Promote user *user_name* to admin status.
   Admin status grants users access to all operations.

.. function:: admin_demote(user_name)

   Demote user *user_name* to ordinary user.

.. function:: element_list(model_name)

   Returns a list of all elements and their type specified in the model named *model_name*.

.. function:: types(model_name)

   Returns a list of all types usable in the model named *model_name*.
   This is similar to executing *element_list* on the metamodel of this model.

.. function:: types_full(model_name)

   Returns a list of all types usable in the model named *model_name*.
   In contrast to *types*, this includes hidden elements as well (i.e., those starting with __)

.. function:: read(model_name, ID)

   Read the content of model element *ID* in model *model_name*.
   This returns the type of the element, and the set of source and destination if the element is an edge (*None* otherwise).

.. function:: read_attrs(model_name, ID)

   Return a dictionary of all attributes of model element *ID* in model *model_name*, containing their values.
   All values in the Modelverse are primitive types, and as such, this is also the case in this operation.

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

   Instantiate a new instance of *typename* in the model *model_name*.
   If the instance is an edge, provide a tuple containing the source and target as *edge*.
   A preferred *ID* can be specified, though there is no guarantee that this name is actually taken (e.g., if it is already taken by another element).
   This operation returns the actually assigned ID.

.. function:: delete_element(model_name, ID)

   Delete the element *ID* in the model *model_name*.
   This is a recursive delete, and all incoming and outgoing edges will be removed (recursively) as well.

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

   Assign the value *value* to the attribute named *attr* of the element *ID* in the model named *model_name*.
   If the attribute already has an assigned value, the previous value is removed first.

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

   Assign the code block *code* to the attribute named *attr* of the element *ID* in the model named *model_name*.
   If the attribute already has an assigned value, the previous value is removed first.
   The assigned code is compiled to Action Language by the HUTN compiler.

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

   Unset the attribute *attr* of model element *ID* in the model *model_name*.

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

   Returns a list of all outgoing associations of *ID*, typed by *typename*, in model *model_name*.
   Typename can be set to the empty string to indicate that all types must match.
   Note that this returns the association itself, **NOT** the destination.

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

   Returns a list of all incoming associations of *ID*, typed by *typename*, in model *model_name*.
   Typename can be set to the empty string to indicate that all types must match.
   Note that this returns the association itself, **NOT** the source.

.. function:: read_association_source(model_name, ID)

   Returns the identifier of the source of association *ID* in model *model_name*.

.. function:: read_association_destination(model_name, ID)

   Returns the identifier of the target of association *ID* in model *model_name*.

Exceptions
^^^^^^^^^^

Below is a list of all exceptions that the wrappers can raise, together with a summary of the kind of error that occured.

.. exception:: ModelverseException

   Generic Modelverse Exception, of which all others inherit.
   This should be the only type of exception that the wrapper can raise.

.. exception:: UnknownError

   Unknown exception has occured.
   This is likely something wrong with the connection, such as the Modelverse that suddenly disconnected.

.. exception:: UnknownIdentifier

   The specified identifier could not be resolved in the Modelverse.

.. exception:: UnknownType

   The specified identifier could not be resolved as a type in the Modelverse.

.. exception:: NotAnAssociation

   The specified identifier does not resolve to an association (or edge), even though this was intended.

.. exception:: UnsupportedValue

   The specified value is not a primitive that can be serialized.
   Supported types are: string, boolean, integer, float, and action.

.. exception:: CompilationError

   Error in the HUTN compiler during compilation.

.. exception:: NoSuchAttribute

   The specified attribute does not exist for this element.

.. exception:: UnknownModel

   The specified model can not be resolved in the Modelverse.

.. exception:: ConnectionError

   Error with the connection to the Modelverse.

.. exception:: ModelExists

   The identifier to give to the newly created model already exists.

.. exception:: PermissionDenied

   Permission denied to either write or read the specified resource.

.. exception:: InvalidMode

   An operation was executed in the wrong context.
   For example, all operations are only valid after a successful *init* and *login* call.

.. exception:: InterfaceMismatch

   The Modelverse responded with an unexpected response.
   As a response came, the Modelverse is likely still running, though we have no idea how to interpret the result.
   Likely, the wrapper is not up to date with the latest Modelverse operations.

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.