Collection-level behaviors

Collections have a unique set of behaviors. Commands on a collection can include sorting and filtering on specific properties, and command responses can differ based on the caller’s access permissions to the resource. Each of these behaviors can be impacted by the collection type.

There are three collection types: query-backed, stream-backed, and dual-backed. The type of collection determines how you extend the collection resource through schema files and resource files, and can also determine which resources and properties are returned when using additional accessible fields filters.

Collection types

Collections can be query-backed, stream-backed, or both (dual-backed).

Query-backed collections

A query-backed collection returns results from the database one page at a time. Depending on the size of the dataset, you might not ever have all the results in memory at once. For performance reasons, this type of collection can be useful when working with large datasets.

Stream-backed collections

A stream-backed collection reads in everything at once and stores it all in memory. This allows for in-memory processing of complete datasets, which can enhance resource access capabilities. However, stream-backed collections could have negative impacts on performance when working with large datasets.

Dual-backed collections

A dual-backed collection has the functionality to perform both stream-backed and query-backed operations.

Determining the collection type

You can determine the type of the collection by looking at the class the resource collection class extends.

  • Query-backed collections extend RestQueryCollectionResource.
  • Stream-backed collections extend RestStreamCollectionResource.
  • Resources that have both stream-backed and query-backed functionality extend RestDualCollectionResource.

For example, the Users collection class, through a series of other classes, extends RestQueryCollectionResource, making it a query-backed collection. You can follow the extension path like this:

UsersExtResource > UsersCoreResource > RootKeyableBeanRestCollectionResource > KeyableBeanRestQueryCollectionResource > RestQueryCollectionResource

Determining which collection type to use in a dual-backed collection

Because dual-backed collections have both query- and stream-backed functionality, a determination needs to be made as to which one to use. That determination is made based on a combination of a configuration default and custom overrides.

The PolicyCenter base configuration defaults to using either query-backed or stream-backed for dual-backed collections. The default can differ based on the PolicyCenter version, whether the version was installed as an upgrade or as a new install, or configuration preferences.

You can override the default for a specific dual-backed collection resource type or for an instance of a resource type.

  • To set the type to be used for a particular dual-backed collection resource, modify the collection’s resource settings in the shared_ext-1.0.apiconfig.yaml file.

  • The type can also be set based on a particular instance of the collection resource. This is done through custom logic that overrides the getCollectionBacking method of the RestDualCollectionResource.

Important:

If your configuration defaults to stream-backed data retrieval for dual-backed collections, Guidewire highly recommends overriding collections with large datasets to use query-backed.

Extending sorting and filtering

It’s important to know what type of collection you’re working with when you want to extend the collection resource sorting and filtering behaviors.

Specifying a property as sortable gives callers the ability to sort the collection based on that property. You can extend the schema or resource file to make properties on a collection sortable. For more information, see Making properties sortable.

Specifying a property as filterable gives callers the ability to filter the collection based on that property. You can extend the schema or resource file to make properties on a collection filterable. For more information, see Making properties filterable.

Resource access

When additional accessible fields filters are in place, a sortable or filterable field may not always be available to the caller. See “Sorting and filtering on accessible fields” in Resource access files: additional accessible fields filters for more information.

REST endpoint generator collection types

The REST endpoint generator supports the creation of only query-backed or stream-backed collections. It does not support dual-backed collections.