Loading a multidimensional entity array

The ArrayLoader class allows you to load a multidimensional array with at most a single pull from the PolicyCenter database.

Assuming no data is stored in cache, when you load a multidimensional array manually, you must query the PolicyCenter database for each array element. Thus, for manual array loading, you must query the database N*M times. Here, N is the number of array elements in the first dimension array, and M is the number of array elements in each of the N second dimension arrays.

This number of queries arises from the fact that a multidimensional array is really an array of pointers. The array is not a data structure where all of the array elements are combined in the same location. Hence, manual array loading degrades performance due to the overhead bandwidth requirement for the N*M queries and due to contention with other database queries.

The ArrayLoader class eliminates this challenge by combining the N*M queries into at most single query. The special case where all of the required data is stored in cache requires no database queries. Thus, the ArrayLoader class reduces the overhead bandwidth requirement and the risk of database contention for loading a multidimensional array.

The primary methods in the ArrayLoader class are three overloaded constructors. The first constructor has the following signature:

public ArrayLoader(IArrayPropertyInfo arrayPropertyInfo, Iterable<P> parents)

The arrayPropertyInfo parameter contains metadata about the entity type to be loaded into an array. This metadata includes primarily the table name and the column name for the entity type to be queried. The parents parameter includes the entity instances from the table.

For example, a desired multidimensional array might contain a collection of policies and the coverables for those policies. The arrayPropertyInfo parameter would instruct the database to pull the coverables for the policies in the collection. The parents parameter contains the collection of policies

The second constructor has the following signature:

public ArrayLoader(IArrayPropertyInfo arrayPropertyInfo, P[] parents)

This constructor is logically equivalent to the first constructor. The only difference is that the second constructor represents the parents parameter in array form as opposed to an Iterable form.

The signature for the third constructor is as follows:

public ArrayLoader(IArrayPropertyInfo arrayPropertyInfo, Iterable<Key> parentIds, Bundle bundle)

For this constructor the parents parameter contains parent keys as opposed to complete entity instances. All three constructors use only the key from the entity instances. The third constructor takes the parent keys directly from the method invocation as opposed to the collection of entity instances. The bundle parameter is the ultimate destination for the children in the second dimension of the multidimensional array.