Interface ModelFactory
-
public interface ModelFactory
Represents a data source loading/saving/upgrading strategy. The location resides rather on theDataSource
side than here while the storage parameters belong here. NB: TheModelFactory
knows aboutDataSource
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
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description default boolean
canCreate(DataSource dataSource, Map<String,String> options)
Deprecated.rather try callingcreate(DataSource, SModelName, ModelLoadingOption...)
method and catching theModelCreationException
during creation or usesupports(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 suppliedmodelName
on the givenDataSource
.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 theModelFactoryService
.default SModel
load(DataSource dataSource, ModelLoadingOption... options)
Loads an existing model from the givenDataSource
.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 callingcreate(DataSource, SModelName, ModelLoadingOption...)
method and catching theModelCreationException
during creation or usesupports(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 theModelFactory
. I suggest to use the honestsupports(org.jetbrains.mps.openapi.persistence.DataSource)
method and catch theModelCreationException
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 theUnsupportedDataSourceException
.- 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 suppliedmodelName
on the givenDataSource
. Might consider additional options provided in theoptions
varargs. [General rule: options.contain(SomeOption) => SomeOption is on]- Parameters:
dataSource
- -- location to create the model inmodelName
- -- a new model name (note that it might be constructed easily from full-qualifiedString
)options
- -- custom options- Returns:
- newly created model
- Throws:
UnsupportedDataSourceException
- iffsupports(DataSource)
returns falseModelCreationException
- 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 givenDataSource
. Might consider additional options provided in theoptions
varargs. [General rule: options.contain(SomeOption) => SomeOption is on]- Parameters:
dataSource
- -- location to load model fromoptions
- -- custom options- Returns:
- loaded model
- Throws:
UnsupportedDataSourceException
- iffsupports(DataSource)
returns falseModelLoadException
- 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 supportedIOException
-
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 supportedIOException
-
getType
@NotNull default ModelFactoryType getType()
Returns an id which is used to get model factory by id in theModelFactoryService
.- 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'.
-
-