matlab.serialization.ElementSerializationContent - Representation of serialized object - MATLAB (original) (raw)

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

Representation of serialized object

Since R2024b

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.

Creation

matlab.serialization.ElementSerializationContent objects are created by themodifyOutgoingSerializationContent andmodifyIncomingSerializationContent methods of matlab.mixin.CustomElementSerialization. You cannot instantiatematlab.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 methodmodifyIncomingSerializationContent. 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, callhasNameValue on the serialized object, sObj, which is an instance ofmatlab.serialization.ElementSerializationContent. If the object has a property named X, the object was created using the old definition of Rectangle, andmodifyIncomingSerializationContent 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 ofmatlab.serialization.ElementSerializationContent to update the object:
  • rename — Rename the X andY properties of the old class definition toX1 and Y1.
  • getValue — Retrieve the values ofWidth and X from the old object and add them to find the value of X2. Do the same forHeight and Y.
  • addNameValue — Add the new propertiesX2 and Y2 and their values.
  • remove — Remove the old propertiesWidth 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.

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

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 ofmatlab.serialization.ElementSerializationContent. Define a classDynDemo that defines two properties, Prop1 andTempData.

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 andmatlab.mixin.CustomElementSerialization.
• Implement the static methodmodifyIncomingSerializationContent. 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, callserializedPropertyNames("dynamic") on the serialized object,sObj, which is an instance ofmatlab.serialization.ElementSerializationContent. If the object has no dynamic properties, the object was created using the old definition of theDynDemo class. Remove the nondynamic version ofTempData 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.

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.

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, andsuperclassA defines a private property namedprivProp. Use the fully qualified syntax to referenceprivProp 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