Overview of associative arrays

An associative array provides a mapping between a set of keys and values that the keys represent. A common example of such a mapping is a telephone book. A telephone book maps names of people in a jurisdiction to telephone numbers. Another common example is a dictionary. A dictionary maps terms to their definitions.

To expand on this concept, a telephone book contains a set of names. Each name in the set is a key, and each associated telephone number is a value. Using array-like notation, you can write:

telephonebook[peter]  = 555-123-1234
telephonebook[shelly] = 555-234-2345
...

Note: When you modify an array such that it is an associative array, the array continues to exhibit its original properties as an indexed array. You can use an associative array just as you would an indexed array. For example, you can use an associative array in for loops.

PolicyCenter uses associate arrays to expose array values as a type-safe map within Gosu code. The following example uses a typekey from a State typelist as a mapping index for an associative array of state capitals:

State typekey index	Maps to...
`Capital[State.TC_AL]`	`Montgomery`
`Capital[State.TC_AK]`	`Juneau`
`Capital[State.TC_AZ]`	`Phoenix`
`Capital[State.TC_AR]`	`Little Rock`

Two tasks are required to work with an associative array in Gosu:

Exposing the key set to the type system
Calculating the value from the key

This topic includes the following:

Associative array mapping types

An associative array must have a key that maps to a value. The mapping type describes what PolicyCenter uses as the key and what value that key returns.

Mapping type	Key	Value	More information
Subtype mapping	Entity subtype	Implicit subtype field on an entity	Subtype mapping associative arrays
Typelist mapping	Typelist	Typekey field on the entity	Typelist mapping associative arrays

To implement an associative array, add one of the following elements to an <array> element in the data type definition file. The number of results that each returns—the cardinality of the result set—depends on the element type.

`<link-association>`	Returns at most one element. The return type is an object of the type of the array.
`<array-association>`	Returns an array of results that match the value. The number of results can be zero, one, or more.

Each <array> element in a data type definition file can have zero or one of each of these elements.

As an example, in the ClaimCenter Claim definition file (configuration > config > Metadata > Entity > Claim.eti), you see the following XML (simplified for clarity):

<entity xmlns="http://guidewire.com/datamodel"
        entity="Claim"
        table="claim"
        type="retireable">
  ...
  <array arrayentity="ClaimMetric"
         desc="Metrics related to this claim."
         exportable="false"
         ignoreforevents="true"
         name="ClaimMetrics"
         triggersValidation="false">
    <link-association>
      <subtype-map/>
    </link-association>
    <array-association>
      <typelist-map field="ClaimMetricCategory"/>
    </array-association>
  </array>
  ...
</entity>

Scriptability and associative arrays

It is possible to set the following attributes on each <link-association> and <array-association> element:

hasGetter
hasSetter

For example:

<link-association hasGetter="true" hasSetter="true"> 
  <typelist-map field="TAccountType"/> 
</link-association>

For these attributes:

If hasGetter is true, you can read the property.
If hasSetter is true, you can update the property.

Note: If you do not specify either of these attributes, PolicyCenter defaults to hasGetter="true".

Setting array member values

There are several restrictions on setting associative array member values, including:

You can use a query builder expression to retrieve a specific entity instance. However, the result of the query is read-only. You must add the retrieved entity to a bundle to be able to manipulate its fields. To work with bundles, use one of the following:
```
var bundle = gw.transaction.Transaction.getCurrent()
gw.transaction.Transaction.runWithNewBundle(\ bundle -> ) //Use this version in the Gosu tester
```
You can set array values only on fields that are database-backed fields, not on fields that are derived properties. To determine which fields are derived, consult the PolicyCenter Data Dictionary.