Using InterSystems Development Environments — Atelier and Studio
Creating Class Definitions
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The Caché 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:
You can use all of these techniques interchangeably; Studio automatically ensures that all of these representations are synchronized.
This chapter discusses general aspects of creating class definitions. Most of the following chapters in this book 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 the Caché Studio. When working with class definitions, Studio performs numerous interactions with the Caché 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 and select New 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 the chapter Packages in Using Caché Objects.
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.
For specifics of class naming conventions in Caché, see the section Naming Conventions in Using Caché Objects.
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. For more details see the section Using HTML in Descriptions in the “Class Definition Syntax” appendix in this book.
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).
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, such as Active X, 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 Caché 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 class, or registered, 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 with Caché as well as Creating Web Services and Web Clients in Caché.
Zen DataModel
(optional) If checked, the class includes extends %ZEN.DataModel.Adaptor.
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 Caché terminal:
 Do ##class(MyApp.Person).Populate(100)
For more information see the chapter Caché Data Population Utility in Using Caché Objects.
MultiValue Enabled
The created class inherits from %MV.Adaptor, such that the class uses MV storage and the data appears as a “file” to MultiValue programs and queries.
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.
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 Caché database, add class members such as properties or methods, or edit the class definition using the Class Inspector.
Note:
By default, the New Class wizard creates classes that use Caché ObjectScript for method code. You can change this default value to Basic with Tools > Options dialog, Environment, General tab.
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 Caché 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 Caché 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 in these ways:
Note:
You can control how classes are compiled using options on Tools > Options dialog, Compiler tab).
Incremental Compilation
The 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, General Flags 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 the class you want to rename in the From field.
  2. Enter the new class name in the To field.
  3. Select OK.
  4. You have a new Class Editor window containing a copy of the original class definition. Using the text editor, you can make any additional changes you desire. You can save this new class definition when you like.
  5. 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
  1. Member Selector: Controls which set of keywords are 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.
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 or CSP files).
  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 display 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
The Package Information window displays the following information:
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 the chapter Packages in Using Caché Objects.