Normally, when a repository item is loaded from the database, properties in each table are loaded at the same time. By default, all primary table properties of a repository item are loaded when getItem is called for the first time on the item.

You might need to modify this default property fetching behavior. For some applications, the database activity required to load all primary table properties can adversely affect performance unnecessarily. For example, an application may want the SQL repository to load a large GIF property only if it is specifically asked for. This is known as lazy evaluation. On the other end of the spectrum, you might need to load properties from different tables immediately. For example, an application may want to always load a user’s last name whenever a profile is read from the database. This is known as prefetching. Finally, some applications want to group properties so when one value is requested, all values in this group are loaded—for example, loading a zip code and state code whenever a street address is loaded.

You can achieve a finer level of control over property loading by using cache groups in your repository definition. By default, the cache group of a property is the same name as the table that the property is defined in. You can set the cache group of a property with the group attribute in the property’s definition in the repository definition file. All properties with the same group attribute are fetched whenever any member of the group is fetched. Only those properties that are in the same cache group as the repository ID (or, if there is no ID property, all the properties in the primary table) are loaded when getItem is called for the first time on an item. While generally you define a cache group with the group attribute in the property’s definition in the repository definition file, you can also define a cache group with the setGroup method of atg.adapter.gsa.GSAPropertyDescriptor.

For example, an address might be composed of several properties, like this:

<property name="address1" group="address"/>
<property name="city" group="address"/>
<property name="state" group="address"/>
<property name="zip" group="address"/>

The group="address" attribute ensures that the whole address is loaded whenever one element of the address is accessed, even if the properties are stored on different database tables. So, if you call getPropertyValue for the city property, the address1, state, and zip properties are also loaded.

If you want to assure that only the repository ID is returned and none of the repository item’s other properties, you can isolate the repository ID in its own cache group:

<item-descriptor name="user" default="true">
    <table name="usr_tbl" type="primary" id-column-names="id">
      <property name="id" data-type="string" group="id"/>
      <property name="name" data-type="string" group="info"/>
      <property name="age" data-type="int" group="info"/>
    </table>
</item-descriptor>