Summary

Version 5.4 introduces two new methods which support searching and selection of objects from the PegaRULES database:

• Obj-Browse — Executes an SQL SELECT statement; with the WHERE condition limited to exposed properties
• Obj-List-View — Executes the selection, retrieval, and sorting capabilities of a list view rule, without report display

These new methods can improve performance along multiple dimensions — CPU, database demand, and clipboard size (memory) — compared with the Obj-List command. (The Obj-List command is deprecated as of V5.4, with certain exceptions.)

As demonstrated by one simple comparison, performance improvements with the Obj-Browse and Obj-List-View methods can be substantial. Results vary depending on the number of rows of the table, search criteria, and the number and size of columns returned, so a universal best approach cannot be determined.

Suggested Approach

To make best use of these new methods, plan the row selection criteria. Use the View/Modify Database wizard or other means to determine which properties in the class to be searched are exposed as individual database columns.

Only properties exposed as columns can appear in the Criteria area of the Contents tab of the List View form, and in the parameter array of the Obj-Browse method.

This informal comparison describes three one-step activities that produce similar search and retrieval results on a clipboard page.

Search description

A V5.4 Process Commander system contains approximately 8,400 property rules, of which about 5,200 have a Type of Text.

In this example, three separate activities each created a results page (of class Code-Pega-List)  that contains embedded pages for only those properties with a Type of Text. The embedded pages contain the pyLabel, pyDescription, and pyPropertyName properties for each selected property.

Case 1: Obj-List-View method

The Obj-List-View method uses information in the Content tab and Display Fields tab of a list view rule to determine which instances to retrieve, and which columns of those instances to place on the embedded pages of a Code-Pega-List page. Information on other tabs of the List View form is ignored.

On the Display Fields tab, list the properties to be included.

On the Content tab, list the properties to be retrieved, the selection criteria, and the page name (in the Content Page Name field). Clear the Maximum Value field to allow unlimited searching.

Note the Read-Only check box setting, which instructs Process Commander to include in results only the property values from each object that are explicitly requested, not including the entire Storage Stream or "BLOB" column (pzPVStream property).

This restriction makes each embedded page smaller, saving JVM memory, but means that the embedded page contains only some, not all, of the object (and so cannot be rewritten back later).

If the Read-Only check box is checked and the List View references all property values, including those that are present only in the Storage Stream, the Storage Stream is retrieved, the property values extracted, and then the Storage Stream is discarded to save memory.

The activity Rule-Obj-Property.ObjListView contains only a single step, which references the list view rule:

Case 2: Obj-Browse method

The activity Rule-Obj-Property.ObjBrowse contains a single step that defines both selection criteria and properties to be included on embedded pages.

Note the ReadOnly parameter, which marks the embedded pages as using the smaller-memory-footprint format that excludes the Storage Stream (blob) column.

When the ReadOnly parameter is checked, the Obj-Browse method can retrieve all property values, including those that are only in the Storage Stream, but the Storage Stream (BLOB) column is later removed from the results to save memory space.

Case 3: Obj-List method (deprecated)

For comparison purposes, the V5.3 approach using the Obj-List method was included in the test. This method operates identically in V5.4 as in earlier versions.

However, beginning in V5.4, this method is deprecated for new development, except when used with an external class.

A list rule defines the properties retrieved for each selected property:

The activity Rule-Obj-Property.Obj-List contains a single step, specifying the selection criteria and referencing the list rule:

Results

All three activities produced a Code-Pega-List results page containing 5,320 embedded pages, one for each property of type Text. In all three cases, the embedded pages included the three requested properties, plus a few others.

The table compares key performance statistics from these three activities, called for 10 executions by a driver activity that included a Page-Remove step to delete the results page between the first 9 executions:

Analysis

Note these performance improvements:

• The Obj-List-View method (with the ReadOnly setting checked) used less than half the CPU time and elapsed time that the Obj-List method used, and produced a final clipboard page less than one tenth the size of what the Obj-List method produced.
• Similarly the Obj-Browse method (with the ReadOnly parameter setting selected) used less than half the CPU and elapsed time that the Obj-List method used, and also produced a final clipboard page less than one tenth the size.

The bottom two rows show the substantial performance impact of removing the read-only restriction on the Obj-Browse and Obj-List-View cases.

• For Obj-Browse, CPU times and elapsed times are still better than the Obj-List results, but by less impressive margins.
• For the Obj-List-View case, the entire property instances are loaded into each embedded page, resulting in a 41 Megabyte clipboard.

In other circumstances, percentages (and relative rankings) of the three methods will differ, depending on the hardware and software environment, the search criteria, the need to retrieve the Storage Stream (blob) column, and other conditions. However, the new V5.4 methods are significantly superior to the deprecated Obj-List method in a wide variety of situations.

Test environment and details

These results are from a V5.4 Process Commander system installed on a Windows XP workstation with Tomcat 5.5.25. The PegaRULES database, hosted by Microsoft SQL Server 2005, was collocated on the same server.

The server was idle except for test activities and ordinary background processing. The tester accessed this system from a separate workstation's Internet Explorer session, logging in and running each 10-repeat driver activity separately.

Statistics are from the Performance tool.