Skip to main content

Creating Class Definitions

Important:

InterSystems® Studio has been deprecatedOpens in a new tab. Beginning with version 2024.2, it is no longer included with installations of InterSystems IRIS®, and it is no longer receiving maintenance updates. An upgrade to InterSystems IRIS 2024.2 or later will remove any Studio installation which is associated with the instance.

The version of InterSystems Studio which was included with InterSystems IRIS 2024.1 is available as a stand-alone component from the WRC Downloads page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab). To show only the Studio downloads, type studio in the Name column. Neither upgrades nor new installations of InterSystems IRIS will affect a stand-alone Studio installation.

InterSystems provides the following documentation about Studio 2024.1 for legacy support only. InterSystems recommends that all users develop ObjectScript code using the InterSystems ObjectScript Extension Pack for Visual Studio Code. See Migrate from Studio.

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.

Note:

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 Name

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 OptionsOpens in a new tab.

Class Name

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 IdentifiersOpens in a new tab.

Description

(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 DocumentationOpens in a new tab 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:

Persistent

Create a definition for a persistent class. Persistent objects can be stored in the database.

Serial

Create a definition for a serial class. Serial objects can be embedded in persistent objects to create complex data types such as addresses.

Registered

Create a definition for a registered class. Registered objects are not stored in the database.

Abstract

Create a definition for an abstract class with no superclass.

Datatype

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.Page 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.

Extends

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.

SQL Category

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:

Owner

(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.

XML Enabled

(optional) If selected, the class is XML-enabled; that is, it has the ability to project itself as an XML document. It can also be used in Web Service methods. This is equivalent to adding the %XML.Adaptor class to the class' superclass list.

For more information see Using XML ToolsOpens in a new tab as well as Creating Web Services and Web ClientsOpens in a new tab.

Zen DataModel

This feature is not supported in InterSystems IRIS.

Data Population

(optional) If you select this option, your new class supports automatic data population. This is equivalent to adding the %Library.Populate 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.Populate class). For example, using the Terminal:

 Do ##class(MyApp.Person).Populate(100)

For more information see InterSystems IRIS Data Population UtilityOpens in a new tab.

CSP Class Characteristics Page

If you are creating a new CSP class, the New Class wizard prompts for the following value:

Content Type

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:

  • Using the Class Inspector to change the value of a class or class member keyword.

  • Changing a value in the class definition using the Class Editor.

For a list of class keywords and their meanings, see Defining and Using ClassesOpens in a new tab. For details on class definitions, see the Class Definition LanguageOpens in a new tab 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:

  • Use File > Save to save the contents of the current window.

  • Use Save Project to save all modified class definitions in the current project.

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, Pages with single arrow. 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, Box with multiple arrows pointing toward it. This saves all open, modified class definitions and compiles all classes in the current project.

Note:

You can control how classes are compiled using options on Tools > Options dialog, Compiler tab.

Incremental Compilation

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:

  1. 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.

  2. 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.

  3. 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:

  1. Select Tools > Copy Class.

  2. Select the class you want to rename in the From field.

  3. Enter the new class name in the To field.

  4. Select any of the three options: Add new class to project, Replace instances of the class name, or Copy Storage Definition.

  5. Select OK.

  6. 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.

  7. You can, if you want, delete the old class definition.

Class Inspector

The Class Inspector displays the current class definition in an editable table. The main components of the Class Inspector are described below:

Class Inspector
User interface components of the Class Inspector labeled 1 through 4. Items in the following list refer to these numbers.
  1. 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).

  2. 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.

  3. 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.

  4. 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.

Pane containing Workspace and Inspector tabs, with Inspector tab selected.

Activating the Class Inspector

The Class Inspector displays current information when it is activated (it is gray when inactive). To activate the Class Inspector:

  1. Make sure that the current editor window contains a class definition (the Class Inspector does not work with Routines).

  2. 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.

Class Browser

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.

  1. Open the Class Browser with Tools > Class Browser.

  2. 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.

Superclass Browser

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.

Package Information

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
Package settings dialog showing fields which are described in the following table.

The Package Information window displays the following information:

Parameter Description
Package Name Name of the package.
Description Description of the package
Owner SQL Owner name of this package. This is used to provide Schema-wide privileges to the SQL representation of the package.
SQL Name Name of the SQL Schema used to represent the package relationally.
Client Name 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.
Routine Prefix String that is used as a prefix for the routines generated from classes in this package
Global Prefix 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 PackagesOpens in a new tab.

FeedbackOpens in a new tab