openstudio::osversion::VersionTranslator Class Reference

#include <VersionTranslator.hpp>

Public Member Functions
Constructors and Destructors
	VersionTranslator ()
Actions
Update files on disk to the current version of OpenStudio.
boost::optional< model::Model >	loadModel (const openstudio::path &pathToOldOsm, ProgressBar *progressBar=nullptr)
	Returns a current-version OpenStudio Model, if possible. More...
boost::optional< model::Model >	loadModel (std::istream &is, ProgressBar *progressBar=nullptr)
boost::optional< model::Model >	loadModelFromString (const std::string &str, ProgressBar *progressBar=nullptr)
	Load a model from string. More...
boost::optional< model::Component >	loadComponent (const openstudio::path &pathToOldOsc, ProgressBar *progressBar=nullptr)
	Returns a current-version OpenStudio Component, if possible. More...
boost::optional< model::Component >	loadComponent (std::istream &is, ProgressBar *progressBar=nullptr)
Queries
Access warnings, errors, and other information about the last translation process. All this data is cleared by subsequent calls to loadModel or loadComponent.
VersionString	originalVersion () const
	Get the version of the loaded file. More...
std::vector< LogMessage >	warnings () const
	Get warning messages generated by the last translation. More...
std::vector< LogMessage >	errors () const
	Get error messages generated by the last translation. More...
std::vector< IdfObject >	deprecatedObjects () const
	Returns objects that were removed from the model because the object type or particular use has been deprecated. More...
std::vector< IdfObject >	untranslatedObjects () const
	Returns objects that were removed from the model because there is not a straightforward, unique way to upgrade them. More...
std::vector< IdfObject >	newObjects () const
	Returns objects that were added to the model to make it work properly in the latest version of OpenStudio. More...
std::vector< RefactoredObjectData >	refactoredObjects () const
	Returns an (original object, new object) pair for objects that have been significantly refactored. More...
bool	allowNewerVersions () const
	Returns true if loading newer versions is allowable. More...
void	setAllowNewerVersions (bool allowNewerVersions)
	Set whether or not loading newer versions is allowed. More...

Detailed Description

This class updates OpenStudio Models and Components to the latest version of OpenStudio.

It must be maintained to keep everything working. The developer who is wrapping up the current release and starting the next one should:

1. Run openstudio_osversion_tests.exe and verify that all the tests pass.
2. Create the release branch.
3. Copy the latest resources/osversion folder from the build directory to the source directory, add those files to the resources/CMakeLists.txt, and commit to trunk.
4. Increment the OpenStudio version in CMakeLists.txt
5. Increment the OpenStudio version in openstudiocore/resources/model/OpenStudio.idd (at the top and in the \default of OS:Version's Version Identifier field).
6. Register a trivial update method for the new version in the constructor. Further instructions are provided in the cpp code for VersionTranslator::VersionTranslator.
7. Add the just-branched-for-release version number to m_startVersions, also in the constructor.

To support the current iteration, developers should:

1. Create a non-trivial update method upon the first IDD or other change that should result in data changes to models of the earlier vintages.
2. Add to this non-trivial update method should any other such changes occur during the iteration.
3. Feel free to just log warnings and errors if the desirable changes cannot be reliably completed at the data (IDF) level. Such messages could prompt the user to take specific actions in the OpenStudio Application once they have a nominally valid (updated) model.

Constructor & Destructor Documentation

openstudio::osversion::VersionTranslator::VersionTranslator

(

)

Member Function Documentation

bool openstudio::osversion::VersionTranslator::allowNewerVersions

(

)

const

Returns true if loading newer versions is allowable.

Defaults to true.

std::vector<IdfObject> openstudio::osversion::VersionTranslator::deprecatedObjects

(

)

const

Returns objects that were removed from the model because the object type or particular use has been deprecated.

std::vector<LogMessage> openstudio::osversion::VersionTranslator::errors

(

)

const

Get error messages generated by the last translation.

boost::optional<model::Component> openstudio::osversion::VersionTranslator::loadComponent	(	const openstudio::path &	pathToOldOsc,
		ProgressBar *	progressBar = nullptr
	)

Returns a current-version OpenStudio Component, if possible.

The file at pathToOldOsc must be an osc of version 0.7.0 or later.

boost::optional<model::Component> openstudio::osversion::VersionTranslator::loadComponent	(	std::istream &	is,
		ProgressBar *	progressBar = nullptr
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

boost::optional<model::Model> openstudio::osversion::VersionTranslator::loadModel	(	const openstudio::path &	pathToOldOsm,
		ProgressBar *	progressBar = nullptr
	)

Returns a current-version OpenStudio Model, if possible.

The file at pathToOldOsm must be an osm of version 0.7.0 or later.

boost::optional<model::Model> openstudio::osversion::VersionTranslator::loadModel	(	std::istream &	is,
		ProgressBar *	progressBar = nullptr
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

boost::optional<model::Model> openstudio::osversion::VersionTranslator::loadModelFromString	(	const std::string &	str,
		ProgressBar *	progressBar = nullptr
	)

Load a model from string.

Not overloading loadModel so paths passed as strings in bindings will work.

std::vector<IdfObject> openstudio::osversion::VersionTranslator::newObjects

(

)

const

Returns objects that were added to the model to make it work properly in the latest version of OpenStudio.

VersionString openstudio::osversion::VersionTranslator::originalVersion

(

)

const

Get the version of the loaded file.

Is 0.0.0 before loadModel or loadComponent is called. 0.7.0 is the default if no Version object is found in the file.

std::vector<RefactoredObjectData> openstudio::osversion::VersionTranslator::refactoredObjects

(

)

const

Returns an (original object, new object) pair for objects that have been significantly refactored.

void openstudio::osversion::VersionTranslator::setAllowNewerVersions

(

bool

allowNewerVersions

)

Set whether or not loading newer versions is allowed.

std::vector<IdfObject> openstudio::osversion::VersionTranslator::untranslatedObjects

(

)

const

Returns objects that were removed from the model because there is not a straightforward, unique way to upgrade them.

std::vector<LogMessage> openstudio::osversion::VersionTranslator::warnings

(

)

const

Get warning messages generated by the last translation.