Creating Class Definitions
The 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 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.
You must have an open project before you can work with class definitions in the 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 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.
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.
(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 “Using HTML Markup in Class Documentation” in the chapter “Defining and Compiling Classes” in Using Caché Objects.
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.
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).
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:
The data type used by clients, such as Active X, to represent this data enter a client application.
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 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:
(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.
(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.
(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.AdaptorOpens in a new tab class to the class' superclass list.
(optional) If checked, the class includes extends %ZEN.DataModel.Adaptor.
(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 the chapter “Caché Data Population Utility” in Using Caché Objects.
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:
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
By default, the New Class wizard creates classes that use 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:
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 the class keywords and other details on definitions, see “Class Definitions” in the reference “Class Definitions” in Caché Class Definition 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:
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 in these ways:
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).
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:
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 text 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 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).
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.
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 or CSP files).
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.
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.
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 the chapter “Packages” in Using Caché Objects.