Package org.jetbrains.mps.openapi.persistence

Interface ModelFactory

All Known Subinterfaces:

IndexAwareModelFactory

All Known Implementing Classes:

BinaryModelFactory, DefaultModelPersistence, FilePerRootModelFactory

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/upgrades/saves/loads models (instances of SModel) from data sources. NB: the default implementation of the methods added in 3.5 will be dropped at the 2017.3 minor release. Please do not linger to pass on the new API.

Method Summary

Modifier and Type	Method	Description
default boolean	canCreate(DataSource dataSource, Map<String,String> options)	Deprecated. rather try calling create(DataSource, SModelName, ModelLoadingOption...) method and catching the ModelCreationException during creation or use supports(DataSource) method to acknowledge whether this data source is supported at all.
default 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.
default ModelFactoryType	getType()	Returns an id which is used to get model factory by id in the ModelFactoryService.
default SModel	load(DataSource dataSource, ModelLoadingOption... options)	Loads an existing model from the given DataSource.
default boolean	needsUpgrade(DataSource dataSource)	Checks if the source content is outdated and needs to be upgraded.
void	save(SModel model, DataSource dataSource)	Saves the model in the factory-specific format (including conversion when needed).
default boolean	supports(DataSource dataSource)	Determines whether the provided data source is maintained by this model factory instance.
void	upgrade(DataSource dataSource)	Loads the model content, and saves it back in the up-to-date format.

Method Detail

canCreate

@Deprecated
default boolean canCreate(@NotNull
                          DataSource dataSource,
                          @NotNull
                          Map<String,String> options)

Deprecated.

rather try calling create(DataSource, SModelName, ModelLoadingOption...) method and catching the ModelCreationException during creation or use supports(DataSource) method to acknowledge whether this data source is supported at all.

Indicates, whether the supplied data source can be used to hold models created by this factory. --------- Currently this method implementations are quite shallow and de facto it does not work at all as the API designer must have suggested. Now the real semantics of this method is whether the data source is supported by the ModelFactory. I suggest to use the honest supports(org.jetbrains.mps.openapi.persistence.DataSource) method and catch the ModelCreationException post factum rather then do the check beforehand. AP ---------

supports

default boolean supports(@NotNull
                         DataSource dataSource)

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

Returns:

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

create

@NotNull
default 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)

See Also:

ModelLoadingOption

load

@NotNull
default 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 in the factory-specific format (including conversion when needed).

Throws:

ModelSaveException

IOException

needsUpgrade

default boolean needsUpgrade(@NotNull
                             DataSource dataSource)
                      throws IOException

Checks if the source content is outdated and needs to be upgraded.

Throws:

UnsupportedDataSourceException - if the data source is not supported

IOException

upgrade

void upgrade(@NotNull
             DataSource dataSource)
      throws IOException

Loads the model content, and saves it back in the up-to-date format.

Throws:

UnsupportedDataSourceException - if the data source is not supported

IOException

getType

@NotNull
default ModelFactoryType getType()

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

Returns:

model factory unique identification entity

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.

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'.