Using Caché Objects
Defining Class Projections
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.
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:
When the class is compiled
When the class is deleted
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");
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:
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
Class MyApp.MyProjection Extends %Projection.AbstractProjection
/// This method is invoked when a class is compiled
ClassMethod CreateProjection(cls As %String, ByRef params) As %Status
// code here...
/// This method is invoked when a class is 'uncompiled'
ClassMethod RemoveProjection(cls As %String, ByRef params, recompile as %Boolean) As %Status
// code here...
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:
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.
When a class definition is deleted
At the start of a recompilation of the class
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:
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.
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.