OperationResult

Status of individual operation when upgrading toolbox

Description

An OperationResult object represents the status of an individual operation 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. The Results property of a ReleaseCompatibilityResults object contains a VersionResults object. The VersionChanges property of that VersionResults object contains an array of OperationResult objects.

For example, this code gets the array of OperationResult objects for version 2 of the toolbox mytoolbox.

myCompatibilityResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
myCompatibilityResults.Results.VersionChanges

ans = 
  1×2 OperationResult array with properties:
    Operation
    Status
    ExceptionLog

Properties

Operation — Upgrade operation performed

string scalar

Upgrade operation performed, specified as a string scalar.

Example: "move mytoolbox.font.MyFontSize mytoolbox.font.FontSize"

Status — Status of upgrade operation

"Succeeded" | "Skipped" | "Failed"

Status of upgrade operation, specified as "Succeeded", "Skipped", or "Failed". This table describes each status and possible causes.

Status	Cause
"Succeeded"	N/A
"Skipped"	Setting or setting group specified in the operation does not exist in the personal settings to be upgraded.
"Failed"	Move operations	Upgraded settings tree already contains a setting or group with the specified name. Specified setting or settings group path is not a valid path.
	Remove operations	Specified setting or settings group path is not a valid path.

ExceptionLog — First upgrade exception

ReleaseCompatibilityException object | 0-by-0 array of ReleaseCompatibilityException objects

First upgrade exception that occurs while performing the upgrade operation, specified as a ReleaseCompatibilityException object. If no exception occurs, ExceptionLog is a 0-by-0 array of ReleaseCompatibilityException objects.

Examples

Get Results of Upgrading Personal Settings

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.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader('Version2'); 
    move(upgraders,'mytoolbox.font.MyFontSize','mytoolbox.font.FontSize'); 
    move(upgraders,'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 that the personal value for the FontSize setting was correctly moved from the MyFontSize setting.

s = settings;
s.mytoolbox.font.FontSize

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

Get the result of the first upgrade operation for version 2 of mytoolbox.

compatibilityResults.matlab.settings.loadSettingsCompatibilityResults("mytoolbox","Version2");
compatibilityResults.Results.VersionChanges(1)

ans = 
  OperationResult with properties:
       Operation: "move mytoolbox.font.MyFontSize mytoolbox.font.FontSize"
          Status: "Succeeded"
    ExceptionLog: [0×0 matlab.settings.ReleaseCompatibilityException]

Version History

Introduced in R2019b