Creating Class Definitions
Studio lets you create and edit class definitions. A class definition specifies the contents of a particular class including its members (such as methods and properties) and characteristics (such as superclasses).
With Studio you can work with class definitions with several tools:
Wizards to quickly create classes and class members
Class Inspector to view and edit class characteristics in a table
Class Editor to directly edit the class definition. The Class Editor is a full-featured text editor that provides syntax coloring, syntax checking, and code completion drop-down menus of available options.
You can use all of these techniques interchangeably; Studio automatically ensures that all of these representations are synchronized.
This topic discusses general aspects of creating class definitions. Most of the following chapters describe how to create class members, such as properties, methods, parameters, and so forth.
Creating New Class Definitions
You can create a new class definition in Studio by using the New Class wizard.
You must have an open project before you can work with class definitions in Studio. When working with class definitions, Studio performs numerous interactions with the InterSystems IRIS® server (such as for providing lists of classes, class compiling, etc.). Internally, Studio uses projects to manage the details of this server interaction.
New Class Wizard
To open the New Class wizard, select File > New > General and select Class Definition.
The New Class wizard prompts you for information. Select Finish at any time (in this case, default values are provided for any information you have not specified).
Name and Description Page
The New Class wizard prompts you for the following information (with the exception of class and package name, you can later modify any of these values):
Package to which the new class belongs. You can select an existing package name or enter a new name. If you enter a new name, the new package is automatically created when you save your class definition. The only punctuation marks that property names can contain are a dot (.) and a leading percent sign (%).
For more information on packages, see Package Options in Defining and Using Classes.
Name of your new class. This must be a valid class name and must not conflict with the name of a previously defined class. Note that you cannot change this class name later.
See Rules and Guidelines for Identifiers.
(optional) Description of the new class. This description is used when the class' documentation is displayed in the online class library documentation.
A description may include HTML formatting tags. See Creating Class Documentation in Defining and Using Classes.
Class Type Page
The New Class wizard asks you what type of class you would like to create. You can either extend (inherit from) a previously defined class or create a new class by selecting one of the following options:
Create a definition for a persistent class. Persistent objects can be stored in the database.
Create a definition for a serial class. Serial objects can be embedded in persistent objects to create complex data types such as addresses.
Create a definition for a registered class. Registered objects are not stored in the database.
Create a definition for an abstract class with no superclass.
Create a definition for a data type class. A data type class is used to create user-defined data types.
CSP (used to process HTTP events)
Create a definition for a %CSP.PageOpens in a new tab class. A CSP class is used to create a CSP event handling class. This is a programmatic way to create CSP Pages or to respond to HTTP events (for example, to create an XML server). Using CSP files with InterSystems IRIS is not recommended.
Extend an existing class: check Extends and enter (or choose from a list) the name of an existing superclass.
Data Type Class Characteristics Page
If you are creating a new data type class, the New Class wizard prompts for certain items particular to data type classes. These include:
Client Data Type
The data type used by clients to represent this data enter a client application.
ODBC Data Type
The data type used by ODBC or JDBC to represent this data type. Choose a type that corresponds to how you want this data type to appear to ODBC/JDBC based applications.
The SQL Category used by the InterSystems SQL Engine when it performs logical operations on this data type.
Persistent, Serial, Registered Class Characteristics Page
If you are creating a new persistent, serial, or registered class, the New Class wizard prompts for certain items particular to persistent or serial classes. These include:
(optional) For a persistent class, enter the SQL username to be the owner of the new class. This username controls privileges when this class is used via SQL. If this field is left blank, then the default owner, _system, is used.
SQL Table Name
(optional) For a persistent class, enter a name to be used for the SQL table that corresponds to this class. If this field is left blank, then the SQL table name is identical to the class name. If the class name is not a valid SQL identifier, you must enter an SQL table name here.
This feature is not supported in InterSystems IRIS.
(optional) If you select this option, your new class supports automatic data population. This is equivalent to adding the %Library.PopulateOpens in a new tab class to the class' superclass list.
Automatic data population allows you to easily create random data with which you can test the operation of your class. To populate a class, compile it and then execute the class' Populate method (inherited from the %Library.PopulateOpens in a new tab class). For example, using the Terminal:
For more information see InterSystems IRIS Data Population Utility in Defining and Using Classes.
CSP Class Characteristics Page
If you are creating a new CSP class, the New Class wizard prompts for the following value:
Specifies what the content type served by this CSP class is. The available options are HTML or XML. This option is used to set the value of the CONTENTTYPE parameter of the new class to text/html or text/xml respectively. You can later change this to whatever value you want.
Using CSP files with InterSystems IRIS is not recommended.
Results of Running the New Class Wizard
After running the New Class wizard, Studio displays a new Class Editor window. The Class Editor window contains your new class definition. For example:
/// This is a Person class
class MyApp.Person extends %Persistent
You can save this class definition in the InterSystems IRIS database, add class members such as properties or methods, or edit the class definition using the Class Inspector.
Opening Class Definitions
You can open a previously saved class definition and display it in a Class Editor window by selecting the class in the Project tab of the Workspace window and double-clicking it with the mouse.
If the class definition you want to open is not part of the current project, first add it to the current project using Project > Add Class.
If the class definition you want to open is currently being edited by someone else, you are asked if you want to open the class definition for read-only access.
Editing Class Definitions
You may modify any of the characteristics of a newly created or previously existing class definition (with the exception of the class or package name). You can do this in two ways:
For a list of class keywords and their meanings, see Defining and Using Classes. For details on class definitions, see the Class Definition Language reference.
Saving and Deleting Class Definitions
If you have modified a class definition, save it to the InterSystems IRIS database in either of the following ways:
To delete a class definition, in the Workspace window, select a class and select Edit > Delete class classname. The class and all of its generated files are deleted.
Compiling Class Definitions
You can compile class definitions from Studio by:
Using Build > Compile or the Compile icon, . This saves all modified class definitions and compiles the current class definition (the one displayed in the active editor window).
Using Build > Rebuild All or the Rebuild All icon, . This saves all open, modified class definitions and compiles all classes in the current project.
You can control how classes are compiled using options on Tools > Options dialog, Compiler tab.
Studio can do incremental compilation of classes. The feature is enabled with the Skip Related Up-to-date Classes option. To find this option, open the Tools > Options dialog, Compiler, Flags & Optimization tab.
When enabled, if changes have been made to source code in one or more methods, only those methods are compiled with Build > Compile. (Use Build > Rebuild All to override.) Any changes to the class interface (properties, method signatures, etc.) or storage definition cause a full compilation.
Incremental compilation is typically much faster than a full compilation and speeds up the process of making incremental changes to methods (application logic) during development.
Incremental compilation works as follows:
The Class Compiler finds all methods whose implementation has changed, places their runtime code into a new routine, such as MyApp.MyClass.5.INT, and compiles this routine.
The Class Compiler then modifies the runtime class descriptor for the class to use the new implementations of the compiled methods. When an application invokes one of these methods, the new code is dispatched to and executed.
The rest of the class definition (compiled meta-information, storage information for persistent classes, runtime SQL information) is left unchanged. Note that the previous implementation of the modified methods remains in the runtime code, but is not executed.
When a full (non-incremental) compilation is performed, all of the extra routines containing incrementally compiled methods are removed. Perform a full compilation on all classes before deploying an application to avoid having extra routines.
Renaming Class Definitions
Once you have created a class definition you cannot change its name. You can perform the equivalent of this operation by creating a copy of the class with a new name as follows:
Select Tools > Copy Class.
Select the class you want to rename in the From field.
Enter the new class name in the To field.
Select any of the three options: Add new class to project, Replace instances of the class name, or Copy Storage Definition.
You have a new Class Editor window containing a copy of the original class definition. Using the Class Editor, you can make any additional changes you desire. You can save this new class definition when you like.
You can, if you want, delete the old class definition.
The Class Inspector displays the current class definition in an editable table. The main components of the Class Inspector are described below:
Member Selector: Controls which set of keywords is displayed. You can choose to view either the Class-wide keywords or the keywords for a specific class member (such as properties or methods).
Item Selector: Controls which specific class member is displayed (such as a particular property). The contents of the list depend on the value of the Member Selector. Selecting (Summary) displays a list of all the members of the type specified by the Member Selector.
Keywords: Lists the keywords for the current class or class member selected by the Member and Item Selectors. Highlighting a keyword displays its description and allows editing select Edit at the right of the value or directly edit the value). Keywords whose value was set explicitly (not inherited or set by default) are shown in bold.
Values: Lists the values of keywords displayed in the keyword list. Values modified since the last time the class definition has been saved are displayed in blue.
Starting the Class Inspector
To start the Class Inspector, select View > Inspector. The Class Inspector shares a pane with the Workspace; click on the Inspector tab to access the Class Inspector.
Activating the Class Inspector
The Class Inspector displays current information when it is activated (it is gray when inactive). To activate the Class Inspector:
Make sure that the current editor window contains a class definition (the Class Inspector does not work with Routines).
Select the Class Inspector
When the Class Inspector is activated, its background turns white and its contents are updated to reflect the current class definition. If you modify any keyword values using the inspector, the corresponding Class Editor window becomes inactive (turn gray). When you are finished with the inspector, select the original Class Editor window. It becomes active and displays the result of the modifications you made using the Class Inspector.
If you right-click in the Class Inspector, it displays a popup menu allowing you to perform operations such as adding new class members.
Studio includes a class browsing utility that lets you view all available classes arranged by class hierarchy. Within each class you can view class members such as properties and methods, including those inherited from superclasses. The Class Browser displays class members in a table. By select a column title, you can sort the class members by that column.
Open the Class Browser with Tools > Class Browser.
Right-click an item in the Class Browser and select whether to add it to the project, open it in the Class Editor, or view documentation.
Superclass Browser and Derived Class Browser
Studio includes two additional browsers, one for listing all superclasses and one for listing derived classes from the current class definition.
Open the Superclass Browser using Class > Superclasses to display an alphabetical list of all superclasses of the current class.
Select a class and then select a button to either add it to the current project, open it in the Class Editor, or view documentation.
Derived Class Browser
Open the Derived Class Browser using Class > Derived Classes to display a list, in alphabetical order, of all the classes derived from the current class definition.
Select a class and then select a button to either add it to the current project, open it in the Class Editor, or view documentation.
Within Studio, you can view and edit information about a specific class package using the Package Settings dialog.
To open Package Information, in the Workspace window, in the Project tab, right-click the package name and select Package Information.
Package Settings dialog
The Package Information window displays the following information:
||Name of the package.
||Description of the package
||SQL Owner name of this package. This is used to provide Schema-wide privileges to the SQL representation of the package.
||Name of the SQL Schema used to represent the package relationally.
||Package name used for the generated projection of this package's classes. For example, if this package contains a class named bank.account, and you give it a client package name of com.mycompany.bank. when the class is compiled, a Java projection of this class is put into com.mycompany.bank.account.
||String that is used as a prefix for the routines generated from classes in this package
||String that is used as a prefix for the default global names used by persistent classes in this package
For more information on class packages, see Packages in Defining and Using Classes.