/*
* Copyright 2003-2014 JetBrains s.r.o.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jetbrains.mps.persistence;
import org.jetbrains.annotations.Nullable;
import org.jetbrains.mps.openapi.model.SModel;
import org.jetbrains.mps.openapi.persistence.ModelFactory;
/**
* PROVISIONAL API
*
* Indicator for models that track version of model persistence.
* Version set is specific to particular persistence, i.e. there might be range 1..8 for xml persistence and 1..2 for binary.
* Model implementing this interface is not necessarily persisted with the version indicated, nor is persisted at all. It's possible to save
* the same model with different persistence mechanisms, hence this version number is merely a hint and value tracker for persistence
* implementations that do recognize versions, and is useless for others.
*
* Primary purpose of this interface is to break tight coupling of general MPS code with DefaultSModelDescriptor and DefaultSModel which
* used to keep persistence version, and to get rid of <code>instanceof SDefaultModelDescriptor</code> (limits to particular model implementation).
*
* Generally, two models implementing this interface not necessarily share same persistence, thus <code>instanceof PersistenceVersionAware</code>
* is not sufficient to tell persistence version values could be directly compared.
* However, persistence version gets updated the model is read and written, and as such indicates version of the most recent (in case of
* free-floating models) or default (for regular SModel with associated DataSource) persistence mechanism.
* @author Artem Tikhomirov
*/
public interface PersistenceVersionAware extends SModel {
/**
* Indicated persistence version for model serialization
* @param version persistence version number, or <code>-1</code> for undefined/unknown
*/
void setPersistenceVersion(int version);
/**
* Version of persistence this model was loaded with, or desired persistence version for model save.
* @return persistence version number, or <code>-1</code> when undefined
*/
int getPersistenceVersion();
/**
* Actual {@link org.jetbrains.mps.openapi.persistence.ModelFactory} which is currently responsible for model load/save,
* or <code>null</code> if model knowns nothing about persistence at the moment.
* @return model load/save facility or <code>null</code> if undefined
*/
@Nullable
ModelFactory getModelFactory();
}