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

The 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:

1. Create an instance of matlab.alias.AliasFileManager.

2. Call the addAlias method on the instance with the new class name and the old class names as arguments.

3. Call the writeAliasFile method on the instance to write the alias definition file. The method writes the definition file to a folder called resources. The method creates the resources folder 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 named Work. Update the name of the class from FirstName to 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

The 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 this:

MATLAB recognizes both FirstName and SecondName as 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 definitions. addAlias returns an error if all of the previous aliases are not included as part of the OldNames input argument.

For an example, see Rename Class That Has Existing Aliases.

Renaming a Namespace

Renaming the entire contents of a namespace in one step is not supported. To rename a namespace, you must define aliases for all the classes in the namespace. For an example, see Rename Namespace of Two Classes.

Note

You cannot create aliases for namespace functions. To rename a namespace that contains functions, keep the old namespace in place and redefine the namespace functions to redirect to the functions in the new namespace.

Viewing Alias Definitions

There are two ways to view alias definitions:

• Create a matlab.metadata.Class instance for the class you want to investigate. The Aliases property of matlab.metadata.Class returns all of the defined class aliases in a string array, in order from newest to oldest. For more information, see matlab.metadata.Class.

• Create a matlab.alias.AliasFileManager instance with the location input argument, where location points to the folder that contains the resources folder of the class alias definition file. The Aliases property of the matlab.alias.AliasFileManager instance returns an array of all alias definitions in that given definition file. For an example of accessing the Aliases property, see Rename Namespace 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

• The resources folder 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.