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.
-
-
Field Summary
Fields Modifier and Type Field Description static String
OPTION_CONTENT_ONLY
Deprecated.String option is not informatory.static String
OPTION_MODELNAME
Deprecated.this option is unnecessary.static String
OPTION_MODULEREF
Deprecated.not used currentlystatic String
OPTION_PACKAGE
Deprecated.not used currentlystatic String
OPTION_RELPATH
Deprecated.not in use anymore
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description 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.SModel
create(DataSource dataSource, Map<String,String> options)
Deprecated.use more flexiblecreate(DataSource, SModelName, ModelLoadingOption...)
insteaddefault SModel
create(DataSource dataSource, SModelName modelName, ModelLoadingOption... options)
Creates a new model with the suppliedmodelName
on the givenDataSource
.String
getFileExtension()
Deprecated.Outrageous breaking of the separation location from the loading strategy principle, which is planted in the create, load, etc.String
getFormatTitle()
Deprecated.usegetType()
andModelFactoryType.getFormatTitle()
insteaddefault 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
.boolean
isBinary()
returns true if plain text is not enough to represent stored data.SModel
load(DataSource dataSource, Map<String,String> options)
Deprecated.Map
is hardly perceivable.default SModel
load(DataSource dataSource, ModelLoadingOption... options)
Loads an existing model from the givenDataSource
.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.
-
-
-
Field Detail
-
OPTION_MODULEREF
@Deprecated static final String OPTION_MODULEREF
Deprecated.not used currently- See Also:
- Constant Field Values
-
OPTION_PACKAGE
@Deprecated static final String OPTION_PACKAGE
Deprecated.not used currently- See Also:
- Constant Field Values
-
OPTION_RELPATH
@Deprecated static final String OPTION_RELPATH
Deprecated.not in use anymore- See Also:
- Constant Field Values
-
OPTION_MODELNAME
@Deprecated static final String OPTION_MODELNAME
Deprecated.this option is unnecessary. Usecreate(DataSource, SModelName, ModelLoadingOption...)
instead.Denotes a model name, used as a key in theMap
parameter in thecreate(DataSource, Map)
methods.- See Also:
- Constant Field Values
-
OPTION_CONTENT_ONLY
@Deprecated static final String OPTION_CONTENT_ONLY
Deprecated.String option is not informatory. Use aContentOption
insteadBoolean value, indicates we don't care to build complete model on load, rather read content as-is, and tread loaded model as mere container for nodes,SModelData
-like. We use this mechanism from merge driver and various tools that are going to access nodes from the model but are not going to expose this model anywhere else.- See Also:
- Constant Field Values
-
-
Method Detail
-
load
@Deprecated @NotNull SModel load(@NotNull DataSource dataSource, @NotNull Map<String,String> options) throws IOException
Deprecated.Map
is hardly perceivable. Please use ratherload(DataSource, ModelLoadingOption...)
insteadInstantiates a model on a given data source. Options can be used to pass additional parameters like stream encoding (usually, the default is utf-8), package name, containing module reference or module relative path of the source.- Returns:
- The loaded model
- Throws:
UnsupportedDataSourceException
- if the data source is not supportedIOException
-
create
@Deprecated @NotNull SModel create(@NotNull DataSource dataSource, @NotNull Map<String,String> options) throws IOException
Deprecated.use more flexiblecreate(DataSource, SModelName, ModelLoadingOption...)
insteadCreates a new empty model. Implementor must throwUnsupportedDataSourceException
if #canCreate returns false.- Parameters:
dataSource
- if null then the default data source is created for the supplied model nameoptions
- must contentOPTION_MODELNAME
mapping.- Throws:
UnsupportedDataSourceException
- if the data source is not supported, in other wordscanCreate(DataSource, Map)
returns falseIOException
- if the model cannot be created for some other reasons
-
canCreate
@Deprecated 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
-
needsUpgrade
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
-
save
void save(@NotNull SModel model, @NotNull DataSource dataSource) throws UnsupportedDataSourceException, ModelSaveException, IOException
Saves the model in the factory-specific format (including conversion when needed).- Throws:
UnsupportedDataSourceException
- if the data source is not supportedModelSaveException
IOException
-
isBinary
boolean isBinary()
returns true if plain text is not enough to represent stored data. // @deprecated The contract is not clear ("not enough" means what exactly?). We would rather turn this into some marker interface than have it here
-
getFileExtension
@Deprecated @Nullable String getFileExtension()
Deprecated.Outrageous breaking of the separation location from the loading strategy principle, which is planted in the create, load, etc. methods. The location notion is hidden inDataSource
and there is absolutely no need to expose it. In order to work out the currently running scenarios we set up special DataSourceFactory <-> ModelFactory relations which are exposed through theDataSourceFactoryRuleService
,ModelFactoryService
andgetPreferredDataSourceTypes()
.- Returns:
- the file extension this factory is registered on null if for instance model factory is associated rather with a group of files than one file.
-
getFormatTitle
@NotNull @Deprecated String getFormatTitle()
Deprecated.usegetType()
andModelFactoryType.getFormatTitle()
insteadUser-readable title of the storage format.
-
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 default 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'.
-
-