matlab.serialization.ElementSerializationContent Class

Namespace: matlab.serialization
Superclasses: matlab.mixin.CustomDisplay, matlab.mixin.indexing.RedefinesDot, handle

Representation of serialized object

Since R2024b

expand all in page

Description

A matlab.serialization.ElementSerializationContent instance represents an object to be serialized or deserialized. matlab.serialization.ElementSerializationContent implements methods that add, remove, or change the properties that are saved or loaded.

The matlab.serialization.ElementSerializationContent class is a handle class.

Class Attributes

ConstructOnLoad
true

For information on class attributes, see Class Attributes.

Creation

matlab.serialization.ElementSerializationContent objects are created by the modifyOutgoingSerializationContent and modifyIncomingSerializationContent methods of matlab.mixin.CustomElementSerialization. You cannot instantiate matlab.serialization.ElementSerializationContent directly.

Methods

expand all

Examples

collapse all

Define a class Rectangle that represents a rectangle on the coordinate plane. The properties define the coordinates of the lower-left corner (X and Y) and the width and height of the rectangle.

classdef Rectangle 
  properties 
    X 
    Y 
    Width 
    Height 
  end 

  methods
    function obj = Rectangle(x,y,w,h) 
      obj.X = x; 
      obj.Y = y; 
      obj.Width = w; 
      obj.Height = h; 
    end 
  end 
end

Create an instance of Rectangle and save it. Replace yourfilepath with your local path.

rOld = Rectangle(1,1,4,5);
save("yourfilepath/oldRectangle.mat","rOld");

Revise the class definition of Rectangle so that the constructor takes the same values, but the properties now define the lower-left corner of the rectangle (X1 and Y1) and the upper-right corner (X2 and Y2). To be able to load objects saved under the old definition, make these additional changes to the class definition:

  • Inherit from matlab.mixin.CustomElementSerialization.

  • Implement the static method modifyIncomingSerializationContent. This method is called whenever you attempt to load a Rectangle object. (For more information, see matlab.mixin.CustomElementSerialization.)

  • As the first step of modifyIncomingSerializationContent, call hasNameValue on the serialized object, sObj, which is an instance of matlab.serialization.ElementSerializationContent. If the object has a property named X, the object was created using the old definition of Rectangle, and modifyIncomingSerializationContent modifies the properties of the object to match the new definition.

  • To update an instance serialized under the old definition, modifyIncomingSerializationContent calls four more methods of matlab.serialization.ElementSerializationContent to update the object:

    • rename — Rename the X and Y properties of the old class definition to X1 and Y1.

    • getValue — Retrieve the values of Width and X from the old object and add them to find the value of X2. Do the same for Height and Y.

    • addNameValue — Add the new properties X2 and Y2 and their values.

    • remove — Remove the old properties Width and Height because they are not part of the new class definition.

classdef Rectangle < matlab.mixin.CustomElementSerialization 
  properties
    X1      
    Y1
    X2
    Y2
  end 
  
  methods 
    function obj = Rectangle(x,y,w,h)
      obj.X1 = x;
      obj.Y1 = y;
      obj.X2 = w + x;
      obj.Y2 = h + y;
    end 
  end

  methods (Static) 
    function modifyIncomingSerializationContent(sObj)
        if sObj.hasNameValue("X")
            sObj.rename("X","X1");  
            sObj.rename("Y","Y1");
            newX2 = sObj.getValue("Width") + sObj.getValue("X1");
            sObj.addNameValue("X2",newX2);
            newY2 = sObj.getValue("Height") + sObj.getValue("Y1");
            sObj.addNameValue("Y2",newY2);  
            sObj.remove("Width");  
            sObj.remove("Height");  
        end
    end 
  end 
end

Clear rOld from memory.

clear("rOld")

Remove the old definition of Rectangle from your path. Add the revised definition of Rectangle to the path, and load the rOld object. Display the object to confirm that the variable has been deserialized as an object of the revised definition of Rectangle.

load("yourfilepath/oldRectangle.mat","rOld");
rOld
rOld = 

  Rectangle with properties:

    X1: 1
    Y1: 1
    X2: 5
    Y2: 6

Note

This example shows how to revise a class definition for backward compatibility, so that objects serialized under the old definition can be deserialized under the new definition. For an example that shows backward and forward compatibility, see matlab.mixin.CustomElementSerialization.

The matlab.mixin.CustomElementSerialization class enables you to add dynamic properties to an instance of matlab.serialization.ElementSerializationContent. Define a class DynDemo that defines two properties, Prop1 and TempData.

classdef DynDemo
    properties
        Prop1
        TempData
    end
    methods
        function obj = DynDemo(p,t)
            if nargin > 0
                obj.Prop1 = p;
                obj.TempData = t;
            end
        end
    end
end

Create an instance of DynDemo and save it. Replace yourfilepath with your local path.

d = DynDemo([1:10],14);
save("yourfilepath/oldDynDemo.mat","d");

Revise the class definition so that TempData is now a dynamic property.

  • Inherit from dynamicprops and matlab.mixin.CustomElementSerialization.

  • Implement the static method modifyIncomingSerializationContent. This method is called whenever you attempt to load a DynDemo object. (For more information, see matlab.mixin.CustomElementSerialization.)

  • As the first step of modifyIncomingSerializationContent, call serializedPropertyNames("dynamic") on the serialized object, sObj, which is an instance of matlab.serialization.ElementSerializationContent. If the object has no dynamic properties, the object was created using the old definition of the DynDemo class. Remove the nondynamic version of TempData and add it as a dynamic property.

  • If the object does have a dynamic property, the object was serialized under the new definition, and the object can be deserialized without any additional action.

classdef DynDemo < dynamicprops & matlab.mixin.CustomElementSerialization
    properties
        Prop1
    end
    methods
        function obj = DynDemo(p)
            if nargin == 1
                obj.Prop1 = p;
            end
        end
    end
    methods (Static)
        function modifyIncomingSerializationContent(sObj)
            if isempty(sObj.serializedPropertyNames("dynamic"))
                val = sObj.TempData;
                sObj.remove("TempData");
                sObj.addDynamicNameValue("TempData",val);
            end
        end
    end
end

Clear d from memory.

clear("d")

Remove the old definition of DynDemo from your path. Add the revised definition of DynDemo to the path, and load d.

load("yourfilepath/oldDynDemo.mat","d");

Use findprop to confirm that TempData is now a dynamic property.

findprop(d,"TempData")
ans = 

  DynamicProperty with properties:

                    Name: 'TempData'
                    
                    ...

Tips

  • If you need to customize a superclass private property from the serialization methods of one of its subclasses, use the fully qualified className.propName syntax. For example, subclassA inherits from superclassA, and superclassA defines a private property named privProp. Use the fully qualified syntax to reference privProp from subclasssA serialization methods.

    classdef subclassA < superclassA
    properties
        prop1
    end

    methods (Static)
        function modifyOutgoingSerializationContent(sObj,obj)
            % Access the superclass private property privProp
            x = sObj.getValue("superclassA.privProp");
            % Access the sublcass property prop1
            y = sObj.getValue("prop1");
            ...
        end
    end
end

  • You can use dot notation in place of explicitly using the getValue and updateValue methods. For example, these two syntaxes are equivalent. 

    x = sObj.getValue("prop1")
x = sObj.prop1

    You cannot use dot notation when accessing a private property of a superclass. Use the explicit methods instead.

Version History

Introduced in R2024b

See Also

|

Topics