ReleaseCompatibilityException

Exception that occurs when upgrading toolbox

expand all in page

Description

A ReleaseCompatibilityException object represents an exception that occurs when upgrading the personal settings of a toolbox.

Creation

Create a ReleaseCompatibilityResults object for a specific toolbox version number by using the matlab.settings.loadSettingsCompatibilityResults function. Access the PreValidationExceptions property to get an array of ReleaseCompatibilityException objects.

For example, this code gets the prevalidation exceptions for version 2 of the toolbox mytoolbox as an array of ReleaseCompatibilityException objects.

myCompatibilityResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
myCompatibilityResults.PreValidationExceptions
ans = 
  0×0 ReleaseCompatibilityException array with properties:
    ExceptionString
    ExceptionID

Properties

expand all

Exception message, specified as a character vector. If an exception occurs, ExceptionString contains the exception message.

Example: 'Toolbox settings upgrade failed. Unable to load factory changes for the 'mytoolbox' toolbox.'

Exception identifier, specified as a string scalar. If an exception occurs, ExceptionID contains the identifier of the exception.

Example: "MATLAB:settings:config:FactoryTreeChangesAreEmpty"

Examples

collapse all

Create functions to create and then upgrade a toolbox factory tree and then test that the upgrade completes successfully.

The function createMyToolboxFactoryTree creates the factory settings tree for the toolbox mytoolbox.

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'MyFontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'MyFontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

Create the function createMyToolboxSettingsFileUpgraders with an empty matlab.settings.SettingsFileUpgrader object.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader.empty;
end

Create the settingsInfo.json file for the toolbox. Specify mytoolbox as the root settings group name, createMyToolboxFactoryTree as the settings tree creation function, and createMyToolboxSettingsFileUpgraders as the settings tree upgrade function. Place settingsInfo.json in the toolbox resources folder.

{
"ToolboxGroupName" : "mytoolbox",
"Hidden" : false,
"CreateTreeFcn" : "createMyToolboxFactoryTree",
"CreateUpgradersFcn" : "createMyToolboxSettingsFileUpgraders"
}

Add the folder that contains the settings tree creation function and the toolbox resources folder to the MATLAB® path. Then, load the factory settings tree for mytoolbox.

matlab.settings.reloadFactoryFile('mytoolbox');

Use the settings function to access the root of the settings tree and set the personal value for the MyFontSize setting.

s = settings;
s.mytoolbox.font.MyFontSize.PersonalValue = 15;

Change the settings names in createMyToolboxFactoryTree from MyFontSize and MyFontColor to FontSize and FontColor.

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'FontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'FontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

Record the rename of the two settings in the createMyToolboxSettingsFileUpgraders function as changes to the settings tree for version 2 of mytoolbox. When recording the rename of the two settings, introduce an error in one of the paths. For example, remove mytoolbox from the destination path of the first recorded change.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader('Version2'); 
    upgraders.move('mytoolbox.font.MyFontSize','font.FontSize'); 
    upgraders.move('mytoolbox.font.MyFontColor','mytoolbox.font.FontColor');
end

Reload the factory settings tree for mytoolbox.

matlab.settings.reloadFactoryFile('mytoolbox');

Use the settings function to access the root of the settings tree and verify the personal value for the FontSize setting. Notice that the personal value was not moved.

s = settings;
s.mytoolbox.font.FontSize
ans = 
  Setting 'mytoolbox.font.FontSize' with properties:
       ActiveValue: 11
    TemporaryValue: <no value>
     PersonalValue: <no value>
      FactoryValue: 11

Get the upgrade results for version 2 of mytoolbox and check the exception log for the first operation.

upgradeResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
upgradeResults.Results.VersionChanges(1).ExceptionLog
ans = 
  ReleaseCompatibilityException with properties:
    ExceptionString: ''Toolbox settings upgrade failed. Unable to load factory 
                     changes for the 'mytoolbox' toolbox.''
        ExceptionID: "MATLAB:settings:config:FactoryTreeChangesAreEmpty"

Version History

Introduced in R2019b

See Also

|

Topics