Editing Magritte (section)

== How to work with Magritte? ==

Using Magritte effectively involves understanding three key components: managing stashes, utilizing stash stores, and working with graph wrappers. These elements form the core of Magritte's functionality, enabling users to organize, store, and manipulate their model data with precision and flexibility. In the following sections, we will delve into each of these components, providing you with a comprehensive guide to harnessing the full power of the Magritte framework.

=== Managing stashes ===

Managing stashes is a fundamental aspect of using Magritte. A stash is a set of root nodes and their components stored under a qualified name, which is the absolute path of the stash relative to the root folder of the stashes store. Effectively managing stashes is essential for structuring and persisting the graph you are working with in Magritte. In this example, we will work with a graph of cars, being the name of the module car. This is important to consider as all the generated code will contain this name "Car".

When using Magritte, you assign a stash qualified name to each root element to organize your graph. There are three primary operations involving stashes: loading the graph from scratch, saving information to the graph, and creating root nodes.

==== Loading the Graph from Scratch ====
When initializing the system, you must decide which stashes to load into memory. This step is crucial as it determines the structure and components available in your graph at the start. Here is a code example to demonstrate how to load specific stashes:

    carGraph = CarGraph.load("car1", "car2", "car3");
    carGraph = CarGraph.load(store).loadStashes("car1", "car2", "car3");


Here we present two different ways to load the stashes of a empty graph. One for an in memory graph with no store and the second providing the store (check Stores subsection) for persisting the information.

==== Saving Information to the Graph ====
Whenever you save a root node, all root nodes associated with the stash of that node are saved as well. You also have the option to save a particular stash or all stashes. This ensures that your graph's data is consistently updated and preserved. Below is a code example for saving stashes:

    Car car1 = carGraph.car(0);
    car1.save$();
    carGraph.core$().save("car1");
    carGraph.core$().saveAll();

First line is retrieving the first car of the graph. This is a wrapped graph (see Wrapping section) in which you can retrieve all the root elements that were declared in the model. In the second line we are saving this node and all the nodes that are in the same stash. The third line is equivalent to the second line but in this case we are making explicit that we want to save the stash "car1". Note we use the "core$" function to access low level functions of the graph. Also under core$ we have the option to save the whole graph by using saveAll as it can be seen in the last line.

==== Creating Root Nodes ====
When you create a root node, you must specify the stash in which it will be saved. This organization helps maintain the structure and integrity of your graph. The following code example illustrates how to create a root node within a specific stash:

    Car car4 = carGraph.create("car4").car("tesla");
    Car car5 = carGraph.create("car4", "tesla").car("tesla");

In this example we are creating a new car in the stash "car4". Take into consideration that is it also possible to define the name of the node as it is seen in the last line. If this is not provided a random UUID will be assigned as the name of the node. The name should not contain $ and . symbols as they are used to split the qualified name to provide an structure.


=== Stores ===

In Magritte, various stores can be utilized to save your application's graph. Each store offers different functionalities and persistence capabilities. You can also define your own store, provided it complies with the expected interface. Below is a list of existing stores and their descriptions:

==== ResourcesStore ====
This store works with stashes that reside in the resources of your jar file. These stashes are immutable, meaning you cannot modify them at runtime. Any changes made during execution will not be saved when the application restarts.

==== FileSystemStore ====
This store saves the graph in a specified folder as a set of binary files, each representing a stash. It provides a persistent storage solution that retains changes made during execution.

==== InMemoryFileStore ====
Similar to the FileSystemStore, this store automatically loads all stashes in the specified folder into memory. This eliminates the need to manually load stashes, simplifying the initialization process.

==== VolatileStore ====
This store keeps all stashes in memory. Unlike the ResourcesStore, it allows modifications to stashes during runtime. However, all data is lost when the application is closed, as it does not persist changes beyond the application's lifecycle.

These stores provide flexibility in how you manage and persist your application's graph, allowing you to choose the best fit for your specific needs.

=== Graph Wrappers ===

Graph wrappers in Magritte are code generated by the builder, allowing users to work seamlessly with the semantics defined in their models. These wrappers are essential for creating, finding, and managing nodes within the graph. They provide a higher level of abstraction, making it easier to interact with the graph in a way that aligns with the original model definitions.

By using graph wrappers, you can handle nodes more intuitively. For example, instead of using a generic low-level class like "Node," you can work with specific classes like "Car" that are generated to manage Car nodes. This semantic management approach simplifies the process of manipulating graph data, ensuring that interactions remain consistent with the model's logic and structure.

These wrappers empower you to perform various operations on the graph, such as creating new nodes, locating existing nodes, and maintaining the overall structure. The code generator ensures that each wrapper class embodies the particularities, attributes, and constraints of its corresponding concept, providing a tailored and efficient way to manage your application's graph.

In the examples provided above we can see a Graph wrapper: CarGraph and a node wrapper: Car.