Using Caché Studio
Adding Properties to a Class
This chapter describes how to add properties in a class definition.
The data, or state, of an object is stored in it properties. Every class definition may contain zero or more property definitions.
You can add a new property to a class in two ways:
Adding the property to the class definition in the Class Editor.
Using the New Property wizard
To add a property using the Class Editor, position the cursor on a blank line in the Class Editor and enter a property declaration:
Class MyApp.Person Extends %Persistent
Property Name As %String;
Property Title As %String;
Alternatively, copy an existing property declaration, paste it into a new location, and edit it.
To open the New Property wizard, select
. Alternatively, right-click the Class Inspector and select
or, if only properties are displayed (Property
heads the left column), right-click and select
or select the New Property
from the toolbar.
The New Property wizard prompts you for information. Select Finish
at any time; default values are provided for any information you have not specified.
Name and Description Page
The New Property wizard prompts you for the following information (you can later modify any of these values):
(required) Name of the new property. This name must be a valid property name and must not conflict with the name of a previously defined property. The only punctuation marks that property names can contain are a dot (.) and a leading percent sign (%).
(optional) Description of the new property. This description is used when the class' documentation is displayed in the online class library documentation.
The New Property wizard asks you to select the property type: single-valued, a collection, a stream, or a relationship. You can further refine each of these choices by specifying additional characteristics, such as data type.
A single-valued property is just that; it contains a single value. A single-valued property has a type associated with it. This type is the name of a Caché class. If the class used as a type is a data type class, then the property is a simple literal property; if it is a persistent class, then the property is a reference to an instance of that class; if it is a serial class, then the property represents an embedded object.
You can enter a class name directly or choose from a list of available classes, including streams, using the Browse
A collection property contains multiple values. There are two collection types, List (a simple, ordered list) and Array (a simple dictionary with elements associated with key values). As with a single-valued property, a collection property also has a data type. In this case, the data type specifies the type of the elements contained in the collection.
Property Characteristics Page
If you are adding a new property to a class definition for a persistent or serial object, the New Property wizard asks for additional characteristics. These include:
(optional) This is only relevant for persistent or serial classes. Specifies that this property is required (NOT NULL in SQL terminology). For persistent or serial objects a required property must be given a value or any attempt to save the object fails.
(optional) This is only relevant for persistent classes. Specifies that an index should be created based on this property. This is equivalent to creating an index based on this field.
(optional) This is only relevant for persistent classes. Specifies that the value of this property must be unique in the extent (set of all) objects of this class. This is equivalent to creating a unique index based on this field.
(optional) A calculated property has no in-memory storage allocated for it when an object instance is created. Instead, you must provide accessor (Get or Set) methods for the property. If you choose this option, the New Property wizard can generate an empty Get accessor method for you.
(optional) In the case of a persistent class, this is the name that should be used for the SQL field that corresponds to this property. By default (when this field is blank) the SQL field name is identical to the property name. Provide an SQL field name if you want to use a different field name or if the property name is not a valid SQL identifier.
Data Type Parameters Page
Every property has a list of parameter values which is determined by the type of the property. The values of these parameters control aspects of the property's behavior. Using the table displayed on the Parameters page of the New Property wizard you can specify the value of particular parameters.
You can override the Set method (used to set the value of a property) and Get method (used to retrieve the value of a property) for a property by selecting the corresponding override check box. Choosing one of these options creates an empty Set or Get method which you have to fill in later.
Results of Running the New Property Wizard
After running the New Property wizard the Class Editor window is updated to include the new property definition. For example:
/// This is a Person class
Class MyApp.Person extends %Persistent
Property Name As %String;
If you want to make further modifications to this property you can do this using either the Class Editor or the Class Inspector.