BaseX Database

Motivation

All models created with the XModeler^ML are saved as XML files. Without any database connection, users need to manage and organize these files manually, which can be cumbersome and error-prone. Among others,different versions of the same model need to be carefully labelled in order to be recognized as such (e.g., “WarehouseModel_v17.xml“). Connecting the XModeler^ML to a database that helps managing user models would provide numerous benefits such as:

• Automatic versioning of models
• Support querying of models
• Support collaborative work on models
• Allocate different rights to user roles

To realize these benefits, we wanted to provide native support to connect the XModeler^ML with an XML database instance. For this purpose, we used the open-source XML database management system BaseX.

Database Features Implemented in XModeler^ML

With version 2.4 of the XModeler^ML (and version 1.2 of UML-MX), a BaseX database can be connected to our modeling tool. The following features are currently implemented:

Establishing database connections. Users can add a database connection in the properties window that can be accessed from the Control Center via “File > Preferences…“. If the database server is running (see step 4 in step-by-step configuration guide) and all connection data have been entered correctly, you have successfully connected your database instance to the XModeler^ML. The connection can be verified using the “Check Database Connection“ button.

Loading models from the database. From the Control Center all models from the database can be loaded using the “Database -> Get Projects from Databse“ button. This will automatically load the most recent versions of each model in the database. If only a selection of models or older versions of models should be loaded, users can click “Database -> Version Selection “ to select which (versions of) models should be loaded.

Querying models. Via “Database -> Database Console”, it is possible to query all models in the database. For simple queries, like looking for a class or attribute that contain a certain string, users can use the “XML Console” tab. Here, it is only required to enter a search string and select which modeling elements (e.g., attributes, constraints) should be searched and which filters (e.g., minimum level, model name) apply. More advanced queries can be written using XQuery in the “Custom Console” tab.

Deleting projects in the database. While it is always to possible to manage the XML files within the BaseX database management system itself, models currently saved in the database can be deleted from within the XModeler^ML, too. This can be done using the “Database > Delete Project” button.

Saving (different versions of) models in the database. Once a successful database connection is established, models can also be saved to the database from within the XModeler^ML. In the diagram editor window, select “Model > Save to database” or, alternatively, press CTRL+SHIFT+S to save your model to the database. The key combination CTRL+S allows you to safe the XML file separately.

Managing branches of models. It is also possible to create different branches to manage versions of a model. When saving a model for the first time, a default “main” branch is created. When clicking “Model > Save to database” from within the diagram editor a dialog appears that allows users to add and remove branches.

Setting up an XBase Connection in XModeler^ML

Before setting up a database connection, you must install the BaseX XML database management system. You can download it here. Aftwards, execute the following steps. Steps 1-3 are only required if you want to create a new database instance in BaseX.

Step 1: In BaseX, create a new database

To begin using XModeler^ML with BaseX, you first need to create a new database within the BaseX environment. You can create a new database either using the BaseX GUI or the BaseX console.

Creating a database from the BaseX console: CREATE DATABASE <database_name>
For example: CREATE DATABASE exampleDB

This command will create a new database named exampleDB, which will be used to store and manage your XModeler^ML diagrams. For further information, see https://docs.basex.org/12/Databases

Step 2: In BaseX, add at least one user to access your database

Once the database is created, you need to add users who will be able to access and interact with the database. This is done using the BaseX console by executing the following command: CREATE USER <username> <password>
For example: CREATE USER newuser password123

This command creates a user named newuser with the password password123.

Step 3: In BaseX, grant permissions to your user

After adding users, you need to assign appropriate permissions to ensure they can read from and write to the database. Use the GRANT command to assign these permissions:
Granting write permissions: GRANT write ON <database_name> TO <username>
Granting read permissions: GRANT read ON <database_name> TO <username>
For example, to grant newuser both read and write permissions on the exampleDB database, use the following commands:
GRANT write ON exampleDB TO newuser
GRANT read ON exampleDB TO newuser
These commands ensure that newuser can both write to the database and read from it. For further information on user management, see: https://docs.basex.org/12/User_Management

NOTE: USER PERMISSIONS BECOME ACTIVE ONLY AFTER THE BASEX APPLICATION IS RESTARTED.

Step 4: In BaseX, start the database server

Before using XModeler^ML with BaseX, you need to start the BaseX database server. This can be done through the BaseX GUI, where there are specific batch files designed to
start and stop the server.

To start the database server, follow these steps:

1. Open the folder where the BaseX database is installed.
2. Locate the files basexserver.bat and basexserverstop.bat.
3. To start the database, right-click on basexserver.bat and select “Open externally”. This will launch the BaseX server.
4. When you want to stop the server, right-click on basexserverstop.bat and select “Open externally”.

After starting the server, you can proceed with configuring XModeler^ML and begin using the database for reading and writing operations

NOTE: THIS STEP NEEDS TO BE PERFORMED ANY TIME THE DATABASE SHOULD BE CONNECTED. Otherwise, no connection to database can be established.

Step 5: In XModeler^ML, configure the database connection

After setting up the database and users, you need to configure XModeler^ML to connect to

the BaseX database. To do this, follow these steps:

1. From the Control Center, navigate to “File > Preferences“.
2. In the Preferences window, find the section for configuring database connections.
3. Enter the connection details for the BaseX database:

• • Hostname: The hostname or IP address where the BaseX database is running (e.g., localhost if the server is hosted locally).
  • Database name: The name of the database (e.g., exampleDB).
  • Port: The port number used by BaseX (default is 1984).
  • Username: The username you created (e.g., newuser).
  • Password: The password associated with the user (e.g., password123).

Screencast of BaseX Installation and Conifguration