Class Projections and Projection Classes

John Murray — Tue, 21 Sep 2021 09:31:56 +0000

The purpose of this post is to raise the profile of a powerful mechanism that has long been available to us, and to open a discussion about ways in which it can be used or abused.

You can read more detail about the mechanism in the InterSystems documentation. To summarize, your class definition can use the Projection keyword to reference one or more projection classes. A projection class can implement methods that get invoked at key points in the lifecycle of your class.

A projection class must extend %Projection.AbstractProjection and will typically implement at least one or the following methods:

CreateProjection
RemoveProjection

CreateProjection will be called after your class has been compiled. RemoveProjection will be called just before your class is recompiled, or just before it is deleted.

I think one of the original uses of this mechanism was to generate Java files that implemented a Java projection of an InterSystems class. Since then, it has been used more extensively and become more sophisticated. In InterSystems IRIS 2021.1 I found twenty-six %-classes that derive from %Projection.AbstractProjection.

Apart from how InterSystems uses the mechanism I have also seen it exploited in other ways. Here are a couple of examples:

UMLExplorer ships as an XML file containing four classes. One of these is a projection class called ClassExplorer.WebAppInstaller, which ingeniously projects itself:

Class ClassExplorer.WebAppInstaller Extends %Projection.AbstractProjection
{

Projection Reference As WebAppInstaller;
...

So when this class is compiled its CreateProjection method executes, performing whatever steps the developer coded there. In this case it adds a web application called /CacheExplorer, but it could do anything that the permissions of person compiling the class allow.

A site using our Deltanji source code management tool created a utility projection class. Whenever they are deploying a piece of work that requires some installation steps to run in a target namespace, they implement those steps in a deployment class (D) that has a projection referencing their utility projection class (P). Then they bundle (D) with the piece of work. When (D) gets loaded and compiled in a target namespace the CreateProjection method of (P) is automatically invoked, and is passed the classname (D), allowing it to invoke methods of (D).

If you've seen projection used in other ways, or if you've devised a novel use yourself, please share it as a comment on this post.

One more thought from me at this point. The mechanism means we should probably think twice before compiling during import an XML file whose contents we aren't sure we can trust. The scope for a malicious projection class is great.

Running OS-level commands from the InterSystems IRIS command prompt

John Murray — Tue, 23 Mar 2021 18:45:55 +0000

I originally posted this tip a few years ago on InterSystems Developer Community.

When working at the IRIS (or Ensemble or Caché) command prompt I sometimes want to run an operating system command on the server host. By prefixing my command line with ! or $ I can do this with ease. The following examples are from 2020.1 on Windows, but I think the feature is available on all versions and platforms:

USER>!dir

 Volume in drive C is Windows
 Volume Serial Number is XXXX-XXXX

 Directory of c:\intersystems\iris201\mgr\user

11/12/2020  17:31    <DIR>          .
11/12/2020  17:31    <DIR>          ..
23/03/2021  14:00         1,048,576 IRIS.DAT
14/03/2021  10:00                37 iris.lck
11/12/2020  17:30    <DIR>          stream
               2 File(s)      1,048,613 bytes
               3 Dir(s)  134,542,090,240 bytes free
USER>$dir

 Volume in drive C is Windows
 Volume Serial Number is XXXX-XXXX

 Directory of c:\intersystems\iris201\mgr\user

11/12/2020  17:31    <DIR>          .
11/12/2020  17:31    <DIR>          ..
23/03/2021  14:00         1,048,576 IRIS.DAT
14/03/2021  10:00                37 iris.lck
11/12/2020  17:30    <DIR>          stream
               2 File(s)      1,048,613 bytes
               3 Dir(s)  134,542,159,872 bytes free
USER>

If I need to issue more than one command I can almost get myself an interactive shell:

USER>!

c:\intersystems\iris201\mgr\user\> dir
 Volume in drive C is Windows
 Volume Serial Number is XXXX-XXXX

 Directory of c:\intersystems\iris201\mgr\user

11/12/2020  17:31    <DIR>          .
11/12/2020  17:31    <DIR>          ..
23/03/2021  14:00         1,048,576 IRIS.DAT
14/03/2021  10:00                37 iris.lck
11/12/2020  17:30    <DIR>          stream
               2 File(s)      1,048,613 bytes
               3 Dir(s)  134,542,151,680 bytes free
c:\intersystems\iris201\mgr\user\> date
The current date is: 23/03/2021
Enter the new date: (dd-mm-yy)
c:\intersystems\iris201\mgr\user\> exit
USER>

I wrote "almost" because in the example above the date command prompted me to enter a new date but didn't wait for my keystrokes. It behaved as though I had immediately pressed Enter.

Still, I find it a useful feature.

To use it you will need the %System_Callout:USE privilege.

Forem: John Murray

Class Projections and Projection Classes

Running OS-level commands from the InterSystems IRIS command prompt