Adding entity instances to bundles

A set of entity instances that a query retrieve from the database is not writable. You must add an entity instance to a writable bundle to make the instance writable.

Making an entity instance writable by adding to a bundle

It is common to query the database for specific entity instances and then make changes to the data. The direct results of a database query are in a temporary read-only bundle. You must copy objects to a writable bundle to change objects or delete objects.

To add an entity instance to a bundle, pass the object reference to the bundle.add(obj) method and save the return result. It is extremely important to save the return value of this method. The return result of the add method is a copy of the object that exists inside the new bundle. Only use that return result, not what you passed to the add method. Never modify the original entity reference. Avoid keeping any references to the original entity instance.

The recommended pattern is to set a variable with the original entity reference, and then set its value to the result of the add method. For example:

obj = bundle.add(obj)
Important: You must save the return result of the add method and use the result for any changes. Carefully avoid keeping any references to the original entity instance.

The following example gets the current bundle and moves an entity instance to it

uses gw.transaction.Transaction

var bundle = Transaction.getCurrent()   // Get the current bundle

obj = bundle.add(obj)                   // Move the object to the new bundle and save the result

You can choose to modify the object:

obj.Prop1 = "NewValue"

You can choose to delete the object from the database. Take care to avoid dangling references to the deleted object if you perform this action:

bundle.delete(obj)

In most programming contexts, it is critical to not explicitly commit the bundle after your changes. For example, in typical Rules and PCF contexts, it is dangerous and unsupported to explicitly commit the bundle. Let PolicyCenter perform its default bundle commit behavior.

See also

Moving a writable entity instance to a new writable bundle

You can add a read-only entity instance to a writable bundle. You can also add an entity instance to a writable bundle even if the original entity instance is in a writable bundle already. For this action to succeed, the original entity instance must be unmodified. The entity instance must not be newly added, changed, or deleted in its existing bundle.

If you try to add a modified entity instance to a new bundle, Gosu throws the exception IllegalBundleTransferException. To avoid this exception, be careful not to modify the entity in more than one bundle.

Be aware that even if the entity instance is unmodified at the time you copy it to the new bundle, problems can occur later. Only one bundle can try to commit a change to the same entity instance based on the same revision of the database row. If an entity instance was modified in more than one bundle and both bundles commit, the second commit fails with a concurrent data change exception.

The failed commit attempt might be in code other than your code, such as PCF user interface code that is editing the same object.

Gosu attempts to avoid this problem by preventing adding an already-modified entity to a new bundle. In some cases, user interface code internally refreshes an entity instance, such as when switching from view mode to edit mode. Refreshing an entity is an internal process that discards a cached version and gets the latest version from the database. This process reduces the likelihood of concurrent data change exceptions. Gosu does not provide public API to refresh entity instances.

See also