Defining and Using Classes
Defining Persistent Classes
A persistent class is a class that defines persistent objects. This chapter describes how to create such classes. It discusses the following topics:
When viewing this book online, use the preface
of this book to quickly find other topics.
Defining a Persistent Class
To define a class that defines persistent objects, ensure that the primary
(first) superclass of your class is either %Persistent
or some other persistent class.
Class MyApp.MyClass Extends %Persistent
Projection of Packages to Schemas
For persistent classes, the package is represented in SQL as an SQL schema. For instance, if a class is called Team.Player
class in the Team
package), the corresponding table is Team.Player
table in the Team
If an SQL table name is referenced without the schema name, the default schema name (SQLUser) is used. For instance, the command:
Select ID, Name from Person
Select ID, Name from SQLUser.Person
Specifying the Table Name for a Persistent Class
For a persistent class, by default, the short class name becomes the table name.
To specify a different table name, use the SqlTableName
class keyword. For example:
Class App.Products Extends %Persistent [ SqlTableName = NewTableName ]
Although InterSystems IRIS places no restrictions on class names, SQL tables cannot have names that are SQL reserved words
. Thus if you create a persistent class with a name that is a reserved word, the class compiler will generate an error message. In this case, you must either rename the class or specify a table name for the projection that differs from the class name, using the technique described here.
Storage Definitions and Storage Classes
class provides the high-level interface for storing and retrieving objects in the database. The actual work of storing and loading objects is performed by what is called a storage class
Every persistent object and every serial object uses a storage class to generate the actual methods used to store, load, and delete objects in a database. These internal methods are referred to as the storage interface
. The storage interface includes methods such as %LoadData()
, and %DeleteData()
. Applications never call these methods directly; instead they are called at the appropriate time by the methods of the persistence interface (such as %OpenId()
The storage class used by a persistent class is specified by a storage definition
. A storage definition contains a set of keywords and values that define a storage class as well as additional parameters used by the storage interface.
A persistent class may contain more than one storage definition but only one can be active at a time. The active storage definition is specified using the StorageStrategy
keyword of the class. By default, a persistent class has a single storage definition called Default
Updates to a Storage Definition
The storage definition for a class is created when the class is first compiled. Class projection, such as for SQL, occurs after compilation. If a class compiles properly and then projection fails, InterSystems IRIS does not remove the storage definition. Also, if a class is changed in such a way that might affect the storage definition, it is the responsibility of the application developer to determine if the storage definition has been updated and, if necessary, to modify the storage definition to reflect the change. See Resetting the Storage Definition.
The %CacheStorage Storage Class
is the default storage class used by persistent objects. It automatically creates and maintains a default storage structure for a persistent class.
The %CacheSQLStorage Storage Class
Mapping objects to preexisting global structures used by older applications.
Storing objects within an external relational database using the SQL Gateway
When you compile a persistent (or serial) class that uses the default %CacheStorage
storage class, the class compiler analyzes the properties defined by the class and automatically adds or removes them.
Resetting the Storage Definition
During the development process, you may make many modifications to your persistent classes: adding, modifying, and deleting properties. As a result, you may end up with a fairly convoluted storage definition as the class compiler attempts to maintain a compatible structure. If you want the class compiler to generate a clean storage structure, delete the storage definition from the class and then recompile the class.
Controlling How IDs Are Generated
When you save an object for the first time, the system generates an ID for the object. IDs are permanent.
By default, InterSystems IRIS uses an integer for the ID, incremented by 1 from the last saved object.
You can define a given persistent class so that it generates IDs in either of the following ways:
The ID can be based on a specific property of the class, if that property is unique per instance. For example, you could use a drug code as the ID. To define a class this way, add an index like the following to the class:
Index IndexName On PropertyName [ IdKey ];
Index IndexName On PropertyName [ IdKey, Unique ];
If you define a class this way, when InterSystems IRIS saves an object for the first time, it uses the value of that property as the ID. Furthermore, InterSystems IRIS requires a value for the property and enforces uniqueness of that property. If you create another object with the same value for the designated property and then attempt to save the new object, InterSystems IRIS issues this error:
ERROR #5805: ID key not unique for extent
Also, Cache prevents you from changing that property in the future. That is, if you open a saved object, change the property value, and try attempt to save the changed object, InterSystems IRIS issues this error:
ERROR #5814: Oid previously assigned
This message refers to the OID rather than the ID, because the underlying logic prevents the OID from being changed; the OID is based on the ID.
The ID can be based on multiple properties. To define a class this way, add an index like the following to the class:
Index IndexName On (PropertyName1,PropertyName2,...) [ IdKey, Unique ];
Index IndexName On (PropertyName1,PropertyName2,...) [ IdKey ];
If you define a class this way, when InterSystems IRIS saves an object for the first time, it generates an ID as follows:
Furthermore, InterSystems IRIS requires values for the properties and enforces uniqueness of the given combination of properties. It also prevents you from changing any
of those properties.
If a literal property (that is, an attribute) contains a sequential pair of vertical bars (||
), do not add an IdKey index that uses that property. This restriction is imposed by the way in which the InterSystems SQL mechanism works. The use of ||
in IdKey properties can result in unpredictable behavior.
The system generates an OID as well. In all cases, the OID has the following form:
is the generated ID, and Classname
is the name of the class.
Controlling the SQL Projection of Subclasses
When several persistent classes are in superclass/subclass hierarchy, there are two ways in which InterSystems IRIS can store their data. The default scenario is by far the most common.
Default SQL Projection of Subclasses
The class compiler projects a flattened
representation of a persistent class, such that the projected table contains all the appropriate fields for the class, including those that are inherited. Hence, for a subclass, the SQL projection is a table composed of:
All the columns in the extent of the superclass
Additional columns based on properties only in the subclass
Rows that represent the saved instances of the subclass
Furthermore, in the default scenario, the extent of the superclass contains one record for each saved object of the superclass and all its subclasses
. The extent of each subclass is a subset of the extent of the superclass.
To see this, use the following SQL queries. The first lists all instances of Sample.Person
and shows their properties:
SELECT * FROM Sample.Person
The second query lists all instances of Sample.Employee
and their properties:
SELECT * FROM Sample.Employee
Notice that the Sample.Person
table contains records with IDs in the range 1 to 200. The records with IDs in the range 101 to 200 are employees, and the Sample.Employee
table shows the same employees (with the same IDs and with additional columns). The Sample.Person
table is arranged in two apparent groups only
because of the artificial way that the SAMPLES
database is built. The Sample.Person
table is populated and then the Sample.Employee
table is populated.
Typically, the table of a subclass has more columns and fewer rows than its parent. There are more columns in the subclass because it usually adds additional properties when it extends the parent class; there are often fewer rows because there are often fewer instances of the subclass than the parent.
Alternative SQL Projection of Subclasses
The default projection is the most convenient, but on occasion, you might find it necessary to use the alternative SQL projection. In this scenario, each class has its own extent. To cause this form of projection, include the following in the definition of the superclass:
Class MyApp.MyNoExtentClass [ NoExtent ]
Each subclass of this class then receives its own extent.
Redefining a Persistent Class That Has Stored Data
During the development process, it is common to redefine your classes. If you have already created sample data for the class, note the following points:
The compiler has no effect on the globals that store the data for the class.
In fact, when you delete a class definition, its data globals are untouched. If you no longer need these globals, delete them manually.
If you add or remove properties of a class but do not modify the storage definition of the class, then all code that accesses data for that class continues to work as before. See Schema Evolution,
earlier in this chapter.
If you do modify the storage definition of the class, then code that accesses the data may or may not continue to work as before, depending on the nature of the change.
If you modify a property definition in a way that causes the property validation to be more restrictive, then you will receive errors when you work with objects (or records) that no longer pass validation. For example, if you decrease the MAXLEN
parameter for a property, then you will receive validation errors when you work with an object that has a value for that property that is now too long.