Entity arrays

In the data model definition of an entity type, you can define a property that is an array of read-only entity instances of another specific type.

By default, array fields on entities are unordered indexed arrays in Gosu. An indexed entity array acts like a typical array in that you can get an object by using a numeric index offset from the beginning. For example, myArray[2]. Because the items are unordered, do not rely on the meaning or long term position of a specific element. However, use numeric ordering to loop across the array with looping syntax, such as a for loop.

Gosu defines other enhancement methods and properties on arrays, such as each, firstWhere, HasElements, and map. Use enhancement methods and properties to write concise powerful Gosu code. However, be aware that bringing many entities into memory can be resource intensive if the entity array size is large.

For example, in PolicyCenter, on a User entity type definition file in user.eti, the property Roles is an array of role objects that relate to a user:

<array arrayentity="UserRole" name="Roles" ... />

Gosu adds an addTo… method and a removeFrom… method to the containing entity type to help manage the elements of each associative array defined on the entity. In the preceding example, Gosu adds the methods addToRoles and removeFromRoles to the entity type User.

Optionally, entity arrays support an associative syntax like a map.

Entity array addTo… methods

An addTo… method, such as the addToRoles method described in the example above, sets a foreign key on each element in an entity array that points back to the entity that owns the array. You must call the addTo… method on newly created array elements in order for the Rule Engine to commit them to the database. As a best practice, Guidewire strongly recommends that you always call the appropriate addTo… method to relate new array elements to the entity that owns the array.

Important: Entity arrays are inherently unordered with a non-deterministic order each time they are generated. For example, the order in which an addTo… method adds elements to its entity array is not necessarily the order in which a for loop retrieves them.

Entity array removeFrom… methods

The removeFrom… method behaves differently depending on whether the elements of an entity array are a retireable type:

  • If the element type of the array is retireable, the removeFrom… method retires the element.
  • If the element type of the array is not retireable, the removeFrom… method deletes the element.

The following example removes elements in an array in which the primary contributing factor was driver error.

for (factor in claim.ContributingFactors) { 
  if (factor.Primary == "Driver Factors") { 
    claim.removeFromContributingFactors(factor) 
  } 
}
In this next example, the Modifiers entity is an array of objects that relate to a payment plan:
<array name="Modifiers"
  arrayentity="Modifier"
  owner="true">
  <link-association>
    <typelist-map field="BillingInstructionType"/>
  </link-association>
</array>
If you have created an array of Modifier objects called paymentPlan, the method removeFromModifiers removes the specified element from that array:
paymentPlan.removeFromModifiers(aModifier)
Note: If the paymentPlan array already has a Modifier element for a particular BillingInstructionType, adding a new element for that same BillingInstructionType does not retire the old modifier, but rather appends the object to the array. To retire a modifier you must call its removeFromModifiers method.

To remove an element from all arrays containing it, call that element's remove method.

Optional associative entity arrays

By default, entity arrays are unordered indexed arrays. Optionally, you can define an entity array to support associative array syntax. An associative array acts like a container with key-value mapping similar to java.util.HashMap. Get items from an associative array by providing a key instead of a numeric index. For example, myArray["en_US"]. In the data model definition files, you can make associative arrays by adding the <array-association> subelement to the <array> element.

The modified array field still behaves as an indexed array but you can optionally get items by using associative array syntax.

See also