Locate and select
The property provides two read methods in order to access instances in a collection. Locate functions usually read the index only and are much faster than select functions. Select functions read the complete instance including shared base instances.
Locate functions are used in order to check, whether en instance exists in a collection or to read the key value for the instance. Locate functions allow identifying an instance, i.e. providing the LOID for the instance, but do not read data for the instance.
When a locate function has terminated successfully, the property handle state located is true. When instance filters are defined, locate functions also try to read the instance in order to check the filter condition. In this case, the instance will be selected in the property handle after successfully locating it. Locate functions do not accept instances, which do not fulfill the filter condition.
Locate functions allow locating an instance in a collection by:
- index - locateIndex()
- key - locateKey()
- LOID - locateLoid()
Other locate functions are iterator functions first(), next(), previous() and last() when being called without read option.
Locate functions are a good mean to avoid exceptions, i.e. one may call a locate function in order to check whether an instance exists or not before reading the instance. After locating in instance, in can be read calling get() without any parameter.
... fragment ( Property &person ) {
person.changeAccessKey("sk_name");
if ( person.locateKey("Miller|Paul") ) // instance exists?
person.get();
}
In order to access instance attributes, an instance has to be selected in a property handle. Instances selected in a property handle might be new instances or instances stored already in the database.
When going to create a new instance, an initialized (not yet stored) instance can be selected in the property handle by calling initializeInstance(). After selecting an initialized instance, attributes can be be access, i.e. attribute values might be set. When unselecting the new instance in the property handle, it will be stored automatically. In order to avoid storing the instance, the selection has to be canceled (cancel()).
In order to store the instance properly in the database, at least key component attributes should be initialized properly. In order to store an instance in the database, save() should be called. When save is not called explicitly, the instance will be stored with the next request to change the selection in the property handle.
In order to create new instances in the database you may also call insert() or append() with the appropriate access key value. In this case a new instance is created and stored in the database before being selected in the property handle. In this case you cannot avoid creating the instance unless you run creating the instance in a transaction.
// create new instance
... fragment ( Property &person ) {
person.initializeInstance();
person.value("name") = "Miller";
person.value("first_name") = "Mary";
person.value("pid") = "P007";
person.value("birth_date") = "2010-05-31";
person.save(); // creates new instance in the database
}
In order to select an instance from the database, usually get() is called. The function locates the instance in the database and reads after being located successfully. Since get() throws an exception when no instance could be located, one may call tryGet() instead.
Another way of selecting instances has been provided with iterator functionsfirst(), next(), previous() and last() when being called with read option. In contrast to get() iterator functions will skip instances, not fulfilling the filter condition, which might have been set for the collection.