Automatic Updates for Modified Classes

When MATLAB Loads Class Definitions

MATLAB® loads a class definition:

  • The first time the class is referenced.

  • Whenever the definition of a loaded class changes and MATLAB returns to the command prompt.

MATLAB allows only one definition for a class to exist at any time. Therefore, all existing objects of a class are updated automatically to conform to the new class definition. You do not need to call clear classes to remove existing objects when changing their defining class.

    Note:   Using an editor other than the MATLAB editor can result in delays to automatic updating.

Results of Automatic Update

MATLAB follows a set of basic rules when updating existing objects. An automatic update can result in existing objects being:

  • Successfully updated to the new class definition.

  • Converted to instances of matlab.lang.ObjectUpdateFailure if MATLAB cannot convert the objects to the new class definition.

Suppose you create an instance of a concrete class, and then edit the class definition to make the class abstract.

>> a = MyClass;
% Edit MyClass to make it Abstract

>> a
a = 

  ObjectUpdateFailure with no properties.

The object display provides information on the specific reason that the objects are not updated.

a = 

This array was created with a previous version of the MyClass class. MATLAB is unable to update this array with the new class definition.
The new class is abstract which means objects must now belong to a concrete subclass.

    Note:   MATLAB does not update meta-class instances when you change the definition of a class. You need to retrieve new meta-class data after updating a class definition.

Result of Changes to Class Definitions

MATLAB updates existing objects when a class definition changes, including the following situations:

  • Value to handle — Existing objects become independent handles referring to different objects.

  • Enumeration member added — Existing objects preserve the enumeration members they had before, even if the underlying value has changed.

  • Enumeration member removed — Existing objects that are not using the removed member have the same enumeration members that they had previously. Existing objects using the removed member have the removed member replaced with the default member of the enumeration.

  • Enumeration block removed — Enumeration members are removed from all existing objects.

  • Superclass definition changed — Changes applied to all subclasses of that superclass.

  • Superclass added or removed — Change of superclass applied to all existing objects.

Actions That Do Not Trigger Updates

Existing objects are not updated by these actions:

  • Calling the class function on an out of date object does not cause an update.

  • Assigning an out of date object to a variable does not cause an update.

When Updates to Classes Fail

Some class updates result in an invalid class definition. In these cases, objects do not update until the error is resolved. For example:

  • Adding a superclass can result in a property or method being defined twice.

  • Changing a superclass to be Sealed when objects of one of its subclasses exists results in an invalid subclass definition.

Potential Side Effects from Class Updates

  • Following an update, existing objects might not be fully compatible with the new class definition. For example, a newly added property might require execution of the constructor to be valid.

  • Removing or renaming properties can lose the data held in the property. For example, if a property holds the only reference to another object and is removed from a class, the object is deleted because there are no references to it.

  • Removing a class from a heterogeneous class hierarchy can result in invalid heterogeneous array elements. In this case, the default object for the heterogeneous hierarchy replaces these array elements.

When Updates of Existing Objects Are Not Possible

If MATLAB cannot update existing objects to conform to a modified class definition, then the existing objects of that class are converted to instances of matlab.lang.ObjectUpdateFailure. This conversion occurs when:

  • An enumeration block is added to a non-enumeration class.

  • A class is redefined to be Abstract.

  • A class is removed from a heterogeneous hierarchy and there is no way to replace existing objects in a heterogeneous array with default objects.

  • A class is updated to restrict array formation behavior, such as overloading array indexing and concatenation.

  • A handle class is redefined to be a value class.

Updates to Property Definitions

When you change the definition of class properties, MATLAB applies the changes in existing objects of the class.

If You Make This ChangeEffect on Existing Objects of the Class

Add property

Adds the new property to existing objects of the class. Sets the property values to the default value (which is [] if the class definition does not specify a default).

Remove property

Removes the property from existing objects of the class. Attempts to access the removed property fail.

Change property default value

Does not apply the new default value to existing objects of the class.

Change property attribute value

Applies changes to existing objects of the class.

Some cases require transitional steps:

  • Abstract — Existing objects of a class that become abstract are converted to matlab.lang.ObjectUpdateFailure objects.

  • Access — Changes to the access lists do not change existing instances. However, if classes are added to the access list, instances of those classes have access to this property. If classes are removed from the access list, instances of those classes no longer have access to this property.

  • Dependent — If changed to true, existing objects no longer store property values. You must add a property get method for the property if you want to query the property value.

  • Transient — If changed to true, objects already saved reload this property value. If changed to false, objects already saved reload this property using the default value.

Updates to Method Definitions

When you change the definition of class methods, the affected class member is changed in existing objects as follows.

If You Make This ChangeEffect on Existing Objects of the Class

Add method

New method is callable on existing objects of the class.

Modify method

Modifications are visible to existing objects.

Remove method

Deleted method is no longer callable on existing objects.

Change method attribute value

Apply changes to existing objects of the class.

Some cases require transitional steps:

  • Abstract — Existing objects of a class that become abstract are converted to matlab.lang.ObjectUpdateFailure objects.

  • Access — Changes to the access lists do not change existing instances. However, if classes are added to the access list, instances of those classes have access to this method. If classes are removed from the access list, instances of those classes no longer have access to this method.

  • Sealed — If changed to true and existing subclasses already have defined the method, MATLAB returns an error because the new class definition cannot be applied to existing subclasses.

Updates to Event Definitions

If You Make This ChangeEffect on Existing Objects of the Class

Add event

New event is supported on existing objects of the class.

Modify event

Modifications are visible to existing objects.

Remove event

Deleted event is no longer supported on existing objects.

Change event attribute value

Apply changes to existing objects of the class.

Some cases require transitional steps:

  • ListenAccess — Changes to the access list does not change existing objects. However, if you add classes to the access list, objects of those classes can create listeners for this event. If you remove classes from the access list, objects of those classes are not allowed to create listeners for this event.

  • NotifyAccess — Changes to the access list does not change existing objects. However, if you add classes to the access list, instances of those classes can trigger this event. If you remove classes, objects of those classes are not able to trigger this event.

Was this topic helpful?