Stub Packages

A stub package is an implementation of a package interface that supplies all of the classes, methods, and properties of the package but where each method is a stub that contains none of the functionality.

A stub package is useful in situations when a system needs to be deployed both with and without the full package being present. For example, the full package might be deployed only in sites that have paid an extra licence fee. Rather than deploying two versions of the system, you can write the importing schema as if the package is present and exported.

The stub version of the package means that the exporting classes, methods, and properties are present and can be compiled. The importing schema can then contain code like that shown in the following example.

optionallyCallPackage();
vars
    exported : Exported;
begin
    if Exported.PackagePresent then
        create exported transient;
        exported.exportedInt := 7;
        exported.exportedMethod(5,6);
    else
        write "Package not available";
    endif;
end;

The exported constant PackagePresent on the exported class Exported can be used to check whether the full package rather than the stub is present in the system and then act accordingly.

Although you can write a stub package from the definition of the package interface, it is difficult to do so, as it cannot be developed in the same system as the full package as it would conflict, as it has the same name. However, a simple approach is to develop the full schema with its full version of each package and then extract a version of the schema that contains only stub versions of each package. If this stub version of the schema is then deployed rather than the full version, the importing schema will compile without error and will be able to avoid using the functionality of the full schema as it can check that only the stub version is loaded.

Later, the full version of the schema can be deployed, which would make the full functionality available.

You can extract a stub version of the schema from the full version, by using the B batch extract argument in the jadclient non-GUI client application; for example:

jadclient path=c:\jade\system schema=JadeSchema app=JadeBatchExtract startAppParameters B c:\temp\S1Stub.scm c:\temp\scmS1.ddb S1

For details about batch extractions, see "Extracting Schemas as a Non-GUI Client Application", in Chapter 10 of the JADE Development Environment User’s Guide.

This example extracts a stub version of the schema S1, containing only stub versions of any package to the files c:\temp\S1Stub.scm and c:\temp\S1Stub.ddb or c:\temp\S1Stub.ddx. Any constant with the name PackagePresent on any exported class will be replaced by a Boolean constant with the value false.

In addition, the body of any exported method will be replaced by code that raises exception 1068 (Feature not available in this release) with error item text containing "Packages from schema S1 not available". This means that if the importing schema inadvertently calls an exported method stub (because it did not test the PackagePresent constant, for example), a suitable exception is raised.