Using Caché Studio
Adding Properties to a Class
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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:
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.
For details on property definitions see the Class Definition Syntax appendix.
New Property Wizard
To open the New Property wizard, select Class > Add > Property . Alternatively, right-click the Class Inspector and select Add > Property or, if only properties are displayed (Property heads the left column), right-click and select New Property or select the New Property icon, 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):
Property Name
(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 (%).
For a general discussion on names see the chapter Caché Classes in Using Caché Objects.
Description
(optional) Description of the new property. This description is used when the class' documentation is displayed in the online class library documentation.
A description may include HTML formatting tags. For more details see Using HTML in Descriptions in the “Class Definition Syntax” appendix.
Property Type Page
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.
Single Valued
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 button.
For a description of the basic data type classes provided with Caché, see the chapter Data Types in Using Caché Objects.
Collection
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.
Relationship
A relationship property defines an association between two objects. For more details on relationships, see the chapter Adding Relationships to a Class in this book.
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:
Required
(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.
Indexed
(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.
Unique
(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.
Calculated
(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.
SQL Field Name
(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.
Property Accessors Page
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.