Custom Persistence Overview

What is custom persistence

There is a lot of different data formats today. For example J2EE framework descriptors, IDE plugin descriptors and XML based DSLs. Often they have no or have very unusable editors. It is possible to use MPS to transparently work with them. MPS supports loading models from different formats and saving models into different formats using a technique that we call a custom persistence.

SModelDescriptors

All nodes in MPS when they are loaded in memory are stored within SModels. But because in a project there is often a lot of SModels visible from it and their loading is a rather expensive operation we use lazy initialization of SModels. To make lazy initialization more transparent we use SModelDescriptor class. It makes possible to know some important information about a model like its file name or timestamp, without loading, and it loads its model if required.

Model Roots

Model roots in MPS are similar to source roots in IDEA and other IDEs. A model root specifies a place where and how models are stored. Each module (i.e a language, a solution or a generator) has one or more model roots. You can add and remove model roots in a language/solution/generator properties dialog. When you add a model root, you should specify its directory and a model root manager for your model root. A directory specifies where the models under your root are stored. A model root manager is responsible for how they are stored. The default model root manager knows how to work with default mps models (.mps files) but you may want to create your own. If you want to work with your format in MPS you will have to create a new model root manager that will handle it.

IModelRootManager

If you want to create you own model root manager you have to implement jetbrains.mps.smodel.IModelRootManager interface or derive a class from a helper class jetbrains.mps.smodel.AbstractModelRootManager. This class has sensible defaults for most methods and we recommend to derive from AbstractModelRootManager when you want to create model root manager. The most important methods in AbstractModelRootManager are :

• SModel loadModel(SModelDescriptor modelDescriptor); - loads a SModel from a specified SModelDescriptor. In this method, usually you have to create a new SModel and fill it with nodes loaded somehow from a file on a disk (it's you who writes the nodes' loading itself).
• Set<SModelDescriptor> read(ModelRoot root, ModelOwner owner); - looks into a directory (root.getPath) and loads all model descriptors from it
• void saveModel(SModelDescriptor modelDescriptor); - saves model from a specified SModelDescriptor

Often you want not only to load and save models but also to create new ones. To do so you have to override models creating related methods.

• boolean isNewModelsSupported(); - if you want your model root manager to support new models this method should return true;
• SModelDescriptor createNewModel(ModelRoot root, SModelUID modelUID, ModelOwner owner); - this method will be called when user creates new model from UI. The parameter 'root' contains information about directory where a new model will be placed. The parameter 'modelUID' contains model's fully-qualified name and its stereotype. The parameter 'owner' is an owner of a new model. The most important kinds of model owners are projects, generators, languages and solutions. To create a new model descriptor you should use method DefaultModelRootManager.createNewModel(ModelRoot root, SModelUID uid, ModelOwner owner). After you create model you should notify UI by calling the following method:

              SModelRepository.getInstance().markChanged(modelDescriptor, true);
            

Class loading issues

After you created a new model root manager, you want to use it. To do it, you need your model root manager class to be available in a MPS project classpath. You can set project classpath in a project settings dialog. After that, you'll be able to see your model root manager in a completion menu in model root's inspector. You need to install MPS plugin for doing this, so this menu works only when you have a running IDEA.