Using Caché Objects
Defining Class Projections
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter discusses class projections, which provide a way to customize what happens when a class is compiled or removed. It discusses the following topics:

When viewing this book online, use the preface of this book to quickly find related topics.
Introduction
Class projections provide a way to customize what happens when a class is compiled or removed. A class projection associates a class definition with a projection class. The projection class (derived from the %Projection.AbstractProjection class) provides methods that Caché uses to automatically generate additional code at two times:
This mechanism is used by the Java and C++ projections (hence the origin of the term projection) to automatically generate the necessary client binding code (Java or C++) whenever a class is compiled.
Adding a Projection to a Class
To add a projection to a class definition, use the Projection statement within a class definition:
class MyApp.Person extends %Persistent
{
Projection JavaClient As %Projection.Java(ROOTDIR="c:\java");
}
This example defines a projection named JavaClient that will use the %Projection.Java projection class. When the methods of the projection class are called, they will receive the value of the ROOTDIR parameter.
A class can have multiple uniquely named projections. In the case of multiple projections, the methods of each projection class will be invoked when a class is compiled or deleted. The order in which multiple projections are handled is undefined.
Caché provides the following projection classes:
Class Description
%Projection.Java Generates a Java client class to enable access to the class from Java.
%Projection.Monitor Registers this class as a routine that works with Caché Monitor. Metadata is written to Monitor.Application, Monitor.Alert, Monitor.Item and Monitor.ItemGroup. A new persistent class is created called Monitor.Sample.
%Projection.MV Generates an MV class that enables access to the class from MV.
%Projection.StudioDocument Registers this class as a routine that works with Studio.
%Studio.Extension.Projection Projects the XData menu block to the menu table.
%ZEN.Object.Projection Projection class used by %ZEN.Component.object classes. This is used to manage post-compilation actions for Zen components.
%ZEN.PageProjection Projection class used by %ZEN.Component.page. Currently this does nothing.
%ZEN.Template.TemplateProjection Projection class used by %ZEN.Templage.studioTemplate class.
You can also create your own projection classes and use them in the same way as you would any built-in projection class.
Creating a New Projection Class
To create a new projection class, create a subclass of the %Projection.AbstractProjection class, implement the projection interface methods (see the subsection), and define any needed class parameters. For example:
Class MyApp.MyProjection Extends %Projection.AbstractProjection
{

Parameter MYPARAM;

/// This method is invoked when a class is compiled
ClassMethod CreateProjection(cls As %String, ByRef params) As %Status
{
    // code here...
    QUIT $$$OK 
}

/// This method is invoked when a class is 'uncompiled'
ClassMethod RemoveProjection(cls As %String, ByRef params, recompile as %Boolean) As %Status
{
    // code here...
    QUIT $$$OK 
  }
}
The Projection Interface
Every projection class implements the projection interface, a set of methods that are called in response to certain events during the life cycle of a class. This interface consists of the following methods:
CreateProjection()
The CreateProjection() method is a class method that is invoked by the class compiler after it completes the compilation of a class definition. This method is passed the name of the class being compiled as well as an array containing the parameter values (subscripted by parameter name) defined for the projection.
RemoveProjection()
The RemoveProjection() method is a class method that is invoked either:
This method is passed the name of the class being removed, an array containing the parameter values (subscripted by parameter name) defined for the projection, and a flag indicating whether the method is being called as part of a recompilation or because the class definition is being deleted.
When a class definition containing a projection is compiled, the following events occur:
  1. If the class has been compiled previously, it will be uncompiled before the new compile begins; that is, all the results of the previous compilation are removed. At this time, the compiler invokes the RemoveProjection() method for every projection with a flag indicating that a recompilation is about to occur.
    Note that you cannot call methods of the associated class from within the RemoveProjection() method, because the class does not exist at this point.
    Also note that if you add a new projection definition to a class that had been previously compiled (without the projection), then the compiler will call the RemoveProjection() method on the next compilation even though the CreateProjection() method has never been called. Implementers of the RemoveProjection() method must plan for this possibility.
  2. After the class is completely compiled (that is, it is ready for use), the compiler will invoke the CreateProjection() method for every projection.
When a class definition is deleted, the RemoveProjection() method is invoked for every projection with a flag indicating that a deletion has occurred.