This topic describes the basics of defining classes in InterSystems IRIS®.
Kinds of Classes
InterSystems IRIS provides a large set of class definitions that your classes can use in the following general ways:
-
You can use classes as superclasses for your classes.
-
You can use classes as values of properties, values of arguments to methods, values returned by methods, and so on.
-
Some classes simply provide specific APIs. You typically do not use these classes in either of the preceding ways. Instead you write code that calls methods of the API.
The most common choices for superclasses are as follows:
-
%RegisteredObjectOpens in a new tab — This class represents the object interface in its most generic form.
-
%PersistentOpens in a new tab — This class represents a persistent object. In addition to providing the object interface, this class provides methods for saving objects to the database and reading objects from the database.
-
%SerialObjectOpens in a new tab — This class represents an object that can be embedded in (serialized within) another object.
-
Subclasses of any of the preceding classes.
-
None — It is not necessary to specify a superclass when you create a class.
The most common choices for values of properties, values of arguments to methods, values returned by methods, and so on are as follows:
Object Classes
The phrase object class refers to any subclass of %RegisteredObjectOpens in a new tab. With an object class, you can create an instance of the class, specify properties of the instance, and invoke methods of the instance.
The generic term object refers to an instance of an object class.
There are three general categories of object classes:
The following figure shows the inheritance relationship among these three classes. The boxes list some of the methods defined in the classes:
Collection classes and stream classes are object classes with specialized behavior.
Data Type Classes
The phrase data type class refers to any class whose ClassType keyword equals datatype or any subclass of such a class. These classes are not object classes (a data type class cannot define properties, and you cannot create an instance of the class). The purpose of a data type class (more accurately a data type generator class) is to be used as the type of a property of an object class.
Defining a Class: The Basics
This section discusses basic class definitions in more detail. It discusses the following topics:
Typically, you use an Integrated Development Environment (IDE) to define classes. You can also define classes programmatically using the class definition classes or via an XML class definition file. If you define an SQL table using SQL DDL statements, the system creates a corresponding class definition.
Choosing a Superclass
When you define a class, one of your earliest design decisions is choosing the class (or classes) which to base your class. If there is only a single superclass, include Extends followed by the superclass name, at the start of the class definition.
Class Demo.MyClass Extends Superclass
{
//...
}
If there are multiple superclasses, specify them as a comma-separated list, enclosed in parentheses.
Class Demo.MyClass Extends (Superclass1, Superclass2, Superclass3)
{
//...
}
It is not necessary to specify a superclass when you create a class. It is common to use %RegisteredObjectOpens in a new tab as the superclass even if the class does not represent any kind of object, because doing so gives your class access to many commonly used macros, but you can instead directly include the include files that contain them.
Include Files
When you create a class that does not extend %RegisteredObjectOpens in a new tab or any of its subclasses, you might want to include the following include files:
If your class does extend %RegisteredObjectOpens in a new tab or any of its subclasses, these macros are available automatically.
You can also create your own include files and include them in class definitions as needed.
To include an include file at the beginning of a class definition, use syntax of the following form. Note that you must omit the .inc extension of the include file:
Include MyMacros
For example:
Include %occInclude
Class Classname
{
}
To include multiple include files at the beginning of a class definition, use syntax of the following form:
Include (MyMacros, YourMacros)
Note that this syntax does not have a leading pound sign (in contrast to the syntax required in a routine). Also, the Include directive is not case-sensitive, so you could use INCLUDE instead, for example. The include file name is case-sensitive.
See also #include.
Specifying Class Keywords
In some cases, it is necessary to control details of the code generated by the class compiler. For one example, for a persistent class, you can specify an SQL table name, if you do not want to (or cannot) use the default table name. For another example, you can mark a class as final, so that subclasses of it cannot be created. The class definitions support a specific set of keywords for such purposes. If you need to specify class keywords, include them within square brackets after the superclass, as follows:
Class Demo.MyClass Extends Demo.MySuperclass [ Keyword1, Keyword2, ...]
{
//...
}
For example, the available class keywords include Abstract and Final. For an introduction, see Compiler Keywords. InterSystems IRIS also provides specific keywords for each kind of class member.
Introduction to Defining Properties
An object class can include properties.
To add a property to a class definition, add an element like one of the following to the class:
Property PropName as Classname;
Property PropName as Classname [ Keywords ] ;
Property PropName as Classname(PARAM1=value,PARAM2=value) [ Keywords ] ;
Property PropName as Classname(PARAM1=value,PARAM2=value) ;
PropName is the name of the property, and Classname is an optional class name (if you omit this, the property is assumed to be of type %StringOpens in a new tab).
Keywords represents any property keywords. For an introduction to keywords, see Compiler Keywords. For property keywords; see Property Keywords. These are optional.
Depending on the class used by the property, you might also be able to specify property parameters, as shown in the third and fourth variations.
Notice that the property parameters, if included, are enclosed in parentheses and precede any property keywords. Also notice that the property keywords, if included, are enclosed in square brackets.
Introduction to Defining Methods
You can define two kinds of methods in InterSystems IRIS classes: class methods and instance methods.
To add a class method to a class definition, add an element like the following to the class:
ClassMethod MethodName(arguments) as Classname [ Keywords]
{
//method implementation
}
MethodName is the name of the method and arguments is a comma-separated list of arguments. Classname is an optional class name that represents the type of value (if any) returned by this method. Omit the As Classname part if the method does not return a value.
Keywords represents any method keywords. For an introduction to keywords, see Compiler Keywords. For method keywords, see Method Keywords in the Class Definition Reference. These are optional.
To add an instance method, use the same syntax with Method instead of ClassMethod:
Method MethodName(arguments) as Classname [ Keywords]
{
//method implementation
}
Instance methods are relevant only in object classes.
Naming Conventions
Class and class members follow naming conventions, described briefly here.
For complete information, see Rules and Guidelines for Identifiers and What Is Accessible in Your Namespaces.
General Rules
Every identifier must be unique within its context (for example, no two classes in a given namespace can have the same full name).
Identifiers preserve case: you must exactly match the case of a name; at the same time, two classes cannot have names that differ only in case. For example, the identifiers id1 and ID1 are considered identical for purposes of uniqueness.
Class Names
A full class name consists of two parts: a package name and a class name: the class name follows the final . character in the name. A class name must be unique within its package; a package name must be unique within an InterSystems IRIS namespace. A full class name (that is, starting with the package name) must start with either a letter or the % character. Note that any class whose package name starts with a % character is available in all namespaces.
Because persistent classes are automatically projected as SQL tables, a class definition must specify a table name that is not an SQL reserved word; if the name of a persistent class is an SQL reserved word, then the class definition must also specify a valid, non-reserved word value for its SQLTableName keyword.
For details on packages, see Packages.
Class Member Names
Every class member (such as a property or method) must have a name that is unique within its class. InterSystems strongly recommends that you do not give two members the same name, even if they are different types of members; there could be unexpected results.
Further, a member of a persistent class cannot use an SQL reserved word as its identifier. It can define an alias, however, using the SQLName or SQLFieldName keyword of that member (as appropriate).
Member names can be delimited, which allows them to include characters that are otherwise not permitted. To create a delimited member name, use double quotes for the first and last characters of the name. For example:
Property "My Property" As %String;
Inheritance
An InterSystems IRIS class can inherit from already existing classes. If one class inherits from another, the inheriting class is known as a subclass and the class or classes it is derived from are known as superclasses.
The following shows an example class definition that uses two superclasses:
Class User.MySubclass Extends (%Library.Persistent, %Library.Populate)
{
}
In addition to a class inheriting methods from its superclasses, the properties inherit additional methods from system property behavior classes and, in the case of a data type attribute, from the data type class.
For example, if there is a class defined called Person:
Class MyApp.Person Extends %Library.Persistent
{
Property Name As %String;
Property DOB As %Date;
}
It is simple to derive a new class, Employee, from it:
Class MyApp.Employee Extends Person
{
Property Salary As %Integer;
Property Department As %String;
}
This definition establishes the Employee class as a subclass of the Person class. In addition to its own class parameters, properties, and methods, the Employee class includes all of these elements from the Person class.
Use of Subclasses
You can use a subclass in any place in which you might use its superclass. For example, using the above defined Employee and Person classes, it is possible to open an Employee object and refer to it as a Person:
Set x = ##class(MyApp.Person).%OpenId(id)
Write x.Name
We can also access Employee-specific attributes or methods:
Write x.Salary // displays the Salary property (only available in Employee instances)
Primary Superclass
The leftmost superclass that a subclass extends is known as its primary superclass. A class inherits all the members of its primary superclass, including applicable class keywords, properties, methods, queries, indices, class parameters, and the parameters and keywords of the inherited properties and inherited methods. Except for items marked as Final, the subclass can override (but not delete) the characteristics of its inherited members.
Multiple Inheritance
By means of multiple inheritance, a class can inherit its behavior and class type from more than one superclass. To establish multiple inheritance, list multiple superclasses within parentheses. The leftmost superclass is the primary superclass.
For example, if class X inherits from classes A, B, and C, its definition includes:
Class X Extends (A, B, C)
{
}
The default inheritance order for the class compiler is from left to right, which means that differences in member definitions among superclasses are resolved in favor of the leftmost superclass (in this case, A superseding B and C, and B superseding C.)
Specifically, for class X, the values of the class parameter values, properties, and methods are inherited from class A (the first superclass listed), then from class B, and, finally, from class C. X also inherits any class members from B that A has not defined, and any class members from C that neither A nor B has defined. If class B has a class member with the same name as a member already inherited from A, then X uses the value from A; similarly, if C has a member with the same name as one inherited from either A or B, the order of precedence is A, then B, then C.
Because left-to-right inheritance is the default, there is no need to specify this; hence, the previous example class definition is equivalent to the following:
Class X Extends (A, B, C) [ Inheritance = left ]
{
}
To specify right-to-left inheritance among superclasses, use the Inheritance keyword with a value of right:
Class X Extends (A, B, C) [ Inheritance = right ]
{
}
With right-to-left inheritance, if multiple superclasses have members with the same name, the superclass to the right takes precedence.
Note:
Even with right-to-left inheritance, the leftmost superclass (sometimes known as the first superclass) is still the primary superclass. This means that the subclass inherits only the class keyword values of its leftmost superclass — there is no override for this behavior.
For example, in the case of class X inheriting from classes A, B, and C with right-to-left inheritance, if there is a conflict between a member inherited from class A and one from class B, the member from class B overrides (replaces) the previously inherited member; likewise for the members of class C in relation to those of classes A and B. The class keywords for class X come exclusively from class A. (This is why extending classes A and B — in that order — with left-to-right inheritance is not the same as extending classes B and A — in that order — with right-to-left inheritance; the keywords are inherited from the leftmost superclass in either definition, which makes the two cases different.)