Defining Class Projections
This topic discusses class projections, which provide a way to customize what happens when a class is compiled or removed.
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.AbstractProjectionOpens in a new tab class) provides methods that InterSystems IRIS® uses to automatically generate additional code at two times:
This mechanism is used by the Java projections (hence the origin of the term projection) to automatically generate the necessary client binding code 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.JavaOpens in a new tab 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.
InterSystems IRIS 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
To create a new projection class, create a subclass of the %Projection.AbstractProjectionOpens in a new tab class, implement the projection interface methods (see the subsection), and define any needed class parameters. For example:
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...
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:
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.
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:
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. When implementing this method, be sure to 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.