Tutorial 3 ( creating your own classes )
You can create your own database structure by defining a set of HDS Class definitions. The contents of these class definitions is not restricted apart from a couple of constants that define the relation of objects of this class to other classes. The HDSTemplate.m file (contents shown below) can be used as a template for creating you own classes.
Make sure to read the MATLAB help section on Object Oriented Programming for an introduction on using objects and classes in MATLAB.
The HDSTemplate file shows an example of a valid simple class-definition for the HDSToolbox.
- On the first line, you can see that the HDSTemplate class is a subclass of the HDS class.
- We defined 4 properties in this class. The first three properties don't have special attributes, and the last one is defined as a 'Transient' property. As we will see in the Constants section, the 'rawData' property is defined to contain 'data' values. These values will be stored in a separate file and therefore, the property should be defined as 'Transient' (Values not stored in object).
- Notice that all properties are initialized in the class-definition. This is not only proper coding, but also informs the HDSToolbox what type of data is stored in the property. If a property is not initialized, the HDSToolbox assumes the contents are numeric.
- Also note that each property has a help line following the property definition. This line is displayed in the Matlab command window when you use the PROPERTIES method. Use this to describe the contents of each property.
- The HDSToolbox does not limit the number of properties, or property-groups. You can add attributes as you wish as long as the 'data' properties are defined as 'Transient'.
The constants section is mandatory in every HDS-Class definition. It creates the links between the different classes and describes other object behavior for this class. Below, each of the constants are described:
-
listas : Default property name in which objects of this class reside. This is used when objects of this class are added to another object. Unless the user specifies a different property-name, the objects will be added to a property with the name specified in this constant.
-
classVersion : Version of class definition, changing this will result in a call to the update method for the class ('UPDATEOBJ'). Every time an object is loaded from disk, the version of the saved object is compared to this classVersion. If they do not match, the HDSToolbox will try to run the UPDATEOBJ method on the object (see below).
-
childClasses : Cell array of strings indicating the classes that can be added to objects of this class.
-
parentClasses : Cell array of strings indicating the classes to which objects of this class can be added.
-
metaProps : Unused at this time, will be used to indicate which properties should be indexed for the search function.
-
dataProps : Indicates which properties contain raw data. Data in these properties will be stored separately such that the object can be loaded without loading the rawdata. These properties should be defined as 'Transient' in the properties section.
-
propsWithUnits : Indicates which properties have associated units. The length of this vector should be the same size as that of 'propUnits' and 'propDims'. Providing units for a property makes the data easier to interpret as the units are shown when an object is displayed in the command window.
-
propUnits : Cell array with strings indicating the unit of the data in the property indicated at the same index in the 'propsWithUnits' property. Use this constant in combination with the 'propsWithUnits' constant.
-
propsDims : Cell array with strings or cell array of strings indicating a label for each dimension of the data in the property indicated at the same index in the 'propsWithUnits' property. Providing names for the dimensions in multidimensional arrays makes the data easier to interpret.
-
strIndexProp : String indicating a property that contains strings which can be used for indexing instead of the numeric index (i.e. 'experiment('02-2009').trial(4)' ). The property that is defined as in this constant has to be initialized with a string.
-
maskDisp : Cell array with strings that indicate properties that should not be evaluated when the object is displayed. This can be useful if you have dependent properties that take a while to return their content. (i.e. dependent properties)
The HDSUPDATEOBJ method is automatically called when the object version is different than the class version defined in the class definition. When an object is created, the object version is set to the class version and is saved as a 'hidden' property of the object.
In the HDSUPDATEOBJ, you can update the contents of the object to adhere to the updated class-definition. If you deleted properties in the updated class-definition, they will be available in a temporary 'orphanProps' property. You can update the object version in the HDSUPDATEOBJ method using the SETOBJVERSION method. See below for the HDSUPDATEOBJ method template (part of the HDSTEMPLATE.M file).
