Creating and Managing Class Aliases
A class alias definition is a mapping of one or more old class names to a new name. Creating alias definitions enables you to rename classes while maintaining backward compatibility with code and MAT-files that use one or more older class names. In effect, MATLAB® recognizes more than one name for the same class. This functionality enables you to update class names when the older names no longer reflect your current design.
Creating an Alias Definition File
matlab.alias.AliasFileManager class provides an API for creating and
maintaining alias definitions. Aliases are not part of class definitions. Instead, alias
definition files are stored in
resources folders that are located in
the same folder as the latest class file.
The recommended process for creating and maintaining alias files is to use functions to automate the process. To create a class alias definition, the function must:
Create an instance of
addAliasmethod on the instance with the new class name and the old class names as arguments.
writeAliasFilemethod on the instance to write the alias definition file. The method writes the definition file to a folder called
resources. The method creates the
resourcesfolder if one does not already exist.
Run the function from the same folder that contains the new class
definition. For example, a class named
FirstName is defined in a folder
Work. Update the name of the class from
SecondName using a function called
createAliasFile with this folder structure:
function createAliasFile fileMgr = matlab.alias.AliasFileManager; addAlias(fileMgr,NewName="SecondName",OldNames="FirstName"); writeAliasFile(fileMgr); end
FirstName class file is not needed to create the alias. In fact,
you must remove the original definition from the path so that MATLAB finds the newer alias instead of the older definition.
The final folder structure after running
createAliasFile looks like
MATLAB recognizes both
the same class as long as
SecondName.m and the associated alias
resources folder are in the same folder on the MATLAB path.
See the example Rename Class for more details.
Renaming a Class Multiple Times
You can define multiple aliases for the same class. When doing so, you must pass
in all of the old aliases to the
addAlias method. The aliases must
be listed in order from newest to oldest. Keeping the original function used to
define the alias can help you avoid errors by maintaining a record of the alias
addAlias returns an error if all of the previous
aliases are not included as part of the
For an example, see Rename Class That Has Existing Aliases.
Renaming a Package
Renaming the entire contents of a package in one step is not supported. To rename a package, you must define aliases for all the classes in the package. For an example, see Rename Package of Two Classes.
You cannot create aliases for package functions. To rename a package that contains functions, keep the old package in place and redefine the package functions to redirect to the functions in the new package.
Viewing Alias Definitions
There are two ways to view alias definitions:
meta.classinstance for the class you want to investigate. The
meta.classreturns all of the defined class aliases in a string array, in order from newest to oldest. For more information, see
matlab.alias.AliasFileManagerinstance with the
locationinput argument, where
locationpoints to the folder that contains the
resourcesfolder of the class alias definition file. The
Aliasesproperty of the
matlab.alias.AliasFileManagerinstance returns an array of all alias definitions in that given definition file. For an example of accessing the
Aliasesproperty, see Rename Package of Two Classes.
Note that reading in an existing alias definition file does not validate that the current class names in that file exist.
Backward and Forward Compatibility of Aliases
To share code that includes classes that have been renamed using aliasing, include one of these two items with your code:
The alias-creating function in the setup script of your application or toolbox
resourcesfolder that contains the class alias definition file
The alias definition enables MATLAB to recognize both names as the same class. Including or creating an alias definition in your new code ensures backward compatibility:
New code can work with code that uses old class names because the old names are recognized as aliases.
New code can load and work with MAT-files containing serialized objects that were created using the old names.
When serializing objects, using the oldest defined alias for the objects allows the greatest range of compatibility. Objects serialized using the oldest alias can be used by any code back to the original definition and any future code that maintains the full alias definition. Deleting alias definitions or deleting old names from existing definitions is not recommended because backward and forward compatibility can be limited.