Package org.jetbrains.mps.openapi.persistence

Interface ModelFactory

public interface ModelFactory

Represents a data source loading/saving/upgrading strategy. The location resides rather on the DataSource side than here while the storage parameters belong here. NB: The ModelFactory knows about DataSource but not vice versa. creates/saves/loads models (instances of SModel) from data sources.

Method Summary

Modifier and Type	Method	Description
default MFProblem	canCreate(DataSource dataSource, SModelName modelName, ModelLoadingOption... options)	Some issues can arise when one tries to create a model onto some data source.
SModel	create(DataSource dataSource, SModelName modelName, ModelLoadingOption... options)	Creates a new model with the supplied modelName on the given DataSource.
List<DataSourceType>	getPreferredDataSourceTypes()	Declares a list of preferred data source formats, sorted from the most preferred to the less preferred data source type.
ModelFactoryType	getType()	Returns an id which is used to get model factory by id in the ModelFactoryService.
SModel	load(DataSource dataSource, ModelLoadingOption... options)	Loads an existing model from the given DataSource.
default boolean	needsUpgrade(DataSource dataSource)	As for 193 we have multiple versions for the model persistence.
void	save(SModel model, DataSource dataSource)	Saves the model to the provided data source in the factory-specific format (including conversion when needed).
default void	save(SModel model, DataSource dataSource, ModelSaveOption... options)	Serialize the model to the provided data source in the factory-specific format with respect to options, if any
boolean	supports(DataSource dataSource)	Determines whether the provided data source is maintained by this model factory instance.

Method Detail

supports

boolean supports(@NotNull
                 DataSource dataSource)

Determines whether the provided data source is maintained by this model factory instance. Consider calling it before load/create/upgrade methods in order to avoid UnsupportedDataSourceException.

Returns:

true iff the given data source can be managed by this factory

canCreate

@NotNull
default MFProblem canCreate(@NotNull
                            DataSource dataSource,
                            @NotNull
                            SModelName modelName,
                            @NotNull
                            ModelLoadingOption... options)

Some issues can arise when one tries to create a model onto some data source. For instance, data source might be read-only or such model name already exists and data source does not support two different models with the same names. Call it before #create invocation.

Parameters:

dataSource - target of you model write

modelName - the new model's name

options - the additional options you will pass to create(org.jetbrains.mps.openapi.persistence.DataSource, org.jetbrains.mps.openapi.model.SModelName, org.jetbrains.mps.openapi.persistence.ModelLoadingOption...)

Returns:

the problem from which you can extract some text presentation or MFProblem.NO_PROBLEM if there is no problem

create

@NotNull
SModel create(@NotNull
              DataSource dataSource,
              @NotNull
              SModelName modelName,
              @NotNull
              ModelLoadingOption... options)
       throws UnsupportedDataSourceException,
              ModelCreationException

Creates a new model with the supplied modelName on the given DataSource. Might consider additional options provided in the options varargs. [General rule: options.contain(SomeOption) => SomeOption is on]

Parameters:

dataSource - -- location to create the model in

modelName - -- a new model name (note that it might be constructed easily from full-qualified String)

options - -- custom options

Returns:

newly created model

Throws:

UnsupportedDataSourceException - iff supports(DataSource) returns false

ModelCreationException - iff there was an irrecoverable problem during creation (for instance model file already exists) or canCreate(org.jetbrains.mps.openapi.persistence.DataSource, org.jetbrains.mps.openapi.model.SModelName, org.jetbrains.mps.openapi.persistence.ModelLoadingOption...) returns false

See Also:

ModelLoadingOption

load

@NotNull
SModel load(@NotNull
            DataSource dataSource,
            @NotNull
            ModelLoadingOption... options)
     throws UnsupportedDataSourceException,
            ModelLoadException

Loads an existing model from the given DataSource. Might consider additional options provided in the options varargs. [General rule: options.contain(SomeOption) => SomeOption is on]

Parameters:

dataSource - -- location to load model from

options - -- custom options

Returns:

loaded model

Throws:

UnsupportedDataSourceException - iff supports(DataSource) returns false

ModelLoadException - iff there was an irrecoverable load problem (for instance format was broken or unrecognized)

See Also:

ModelLoadingOption

save

void save(@NotNull
          SModel model,
          @NotNull
          DataSource dataSource)
   throws ModelSaveException,
          IOException

Saves the model to the provided data source in the factory-specific format (including conversion when needed).

Throws:

ModelSaveException

IOException

save

default void save(@NotNull
                  SModel model,
                  @NotNull
                  DataSource dataSource,
                  @Nullable
                  ModelSaveOption... options)
           throws ModelSaveException

Serialize the model to the provided data source in the factory-specific format with respect to options, if any

Throws:

ModelSaveException - in case serialization fails

getType

@NotNull
ModelFactoryType getType()

Returns an id which is used to get model factory by id in the ModelFactoryService.

Returns:

model factory unique identification entity

needsUpgrade

default boolean needsUpgrade(@NotNull
                             DataSource dataSource)
                      throws IOException

As for 193 we have multiple versions for the model persistence. Essentially the different versions of the same persistence could be represented by ModelFactory. This method returns true when the version of the particular persistence is not the latest and could be updated. In that case the resaving the model will probably fix the problem.

Throws:

IOException

getPreferredDataSourceTypes

@NotNull
List<DataSourceType> getPreferredDataSourceTypes()

Declares a list of preferred data source formats, sorted from the most preferred to the less preferred data source type. fixme [AP] I will move it from here since it does not relate to the API of the model factory itself, it is just a plugin for DefaultModelRoot to enable automatic 'data source' <-> 'model factory' relation. It was a mistake to put this method here in the first place.

Returns:

a list of data source kinds which might be considered when MPS meets a data source location and needs to choose a model factory which is likely to support the content of the data source. For instance if we have data source types associated with file names (e.g. prefix or suffix) we are able to establish a file name pattern association with a specific model factory. For example each model file which ends with '.mps_binary' suffix would be associated with the corresponding data source type which in turn would be associated with 'MyBinaryModelFactory'.