Query Change Listeners

Add change listeners to a query and automatically retrieve real-time query updates. When registering a Query Change Listener you can know when your object graph has been updated and use it to indicate when to refresh your UI without having to execute another query.

You can download the code for this example here:

OnyxDevTools/onyx-database-samples/query-change-listener.

1. Define a Query with criteria.
2. Define a Change Listener on the query.
   Notes:

   Infer the entity type by applying a generic type to the Change Listener. The type must match the Query entityType or a Map if you query attribute selections.
3. Execute the query.

   Query Change Listeners are registered automatically when invoking either the executeQuery or executeLazyQuery API methods within the Persistence Manager API.

   Notes:

   The listeners are fairly light weight. Of course it depends on how you use them. After the first execution of the query, it stores the references of the results in memory. This leverages the same technique as the query caching. The only difference is that it stores a strong reference to the query results.

   If you were to register a large quantity of unique queries, insertion, update, and delete speed may be impacted. There is a real-time filter to see if an entity matches any of the queries. So, if insertion speed is most important within your application, there is a trade off with using this feature.

   A Query Change Listener will not be registered when invoking the executeDelete or executeUpdate API methods.
4. Save, Delete, or Update an Entity matching the Query Criteria
5. Remove the Query Change Listener when finished

   Whenever using a listener pattern it is always a good idea to clean up listeners in order to prevent bugs and optimize performance.

   Notes:

   If you neglect to un-register the Query Change Listeners, performance will start to degrade over time. In order to offer this feature Onyx requires a cache to be setup for each of the unique queries. If you fail to remove the listeners the cache will not expire.

   The remote database is capable of expiring the Query Listener if it detects the client is no longer connected.
6. Query Entities