Create a "live" filtered list of entities

The IdeaBlade.EntityModel.EntityListManager<T> class is intended to provide "live-list" management capabilities to any list containing DevForce entities.  The idea of a "live" or "managed" list is that the membership to the list is kept continuously updated based on changes to entities in an EntityManager's entity cache.  Filter expressions are used to determine the rules by which an entity is either included in or excluded from a specific list.

Creating an EntityListManager

Consider the following code:

This code sets up an EntityListManager to watch the cache for changes to Employees, or the insertion of new Employees. If any changed or new Employee is found to be based in London, a reference to that Employee will be added to the _salesReps list. If any Employee that was located in London is moved to another city, that entity will be removed from the list. 

The second parameter to the ManageList call above, indicates whether you want the _employeeEntityListManager to clear the list and then scan the current "entity cache" and repopulate it based on the specified filter. A 'false' value would indicate that you want the list to be monitored from here on, but that you are confident of its initial population.  

The only requirements for the list being managed, in this case: _salesReps, are that it

• implement System.Collections.IList; and
• contain instances of IdeaBlade.EntityModel.Entity.

A single EntityListManager can manage as many different lists as you wish. To put _employeeEntityListManager in charge of additional lists, you would simply invoke its ManageList method again for each desired list:

Of course, it only makes sense to do this when the same inclusion criteria apply to each targeted list.

Note that the EntityListManager is NOT 'watching' the list itself, it is only watching the EntityManager associated with the list and will insure that any changes to any entities within the EntityManager result is the addition or removal of entities from the list based on the specified filter. 

So as a general rule, you should usually avoid modifying a 'managed' list directly, and instead rely on its ability to stay synchronized with its associated EntityManager. The reason that the list does not 'watch' for changes to itself is that the IList interface does not provide any eventing mechanism that would allow an external component, such as the EntityListManager, to perform such a 'watch'. While some implementations of IList do offer such eventing we did not want to restrict the use of the EntityListManager working only with such lists.

EntityListManagers and the NullEntity

One exception to the general rule described above occurs when you want to add a NullEntity to a "managed" list. NullEntities are a special form of "detached" entities and do not reside in the cache, so there is no way that an EntityListManager will ever find one to either add to or be removed from a managed list.  If you want a NullEntity in a managed list, you should manually add it. The ListManager will not remove it.

EntityListManagers and duplicates

The EntityListManager will not eliminate duplicates from a list. It will, however, insure that it does not add the same entity more than once. For example, suppose you direct the following statement against a list, _salesReps, that is already being managed to include Employees based in London:

You will end up with duplicate references to each of the London employees! Again, the general rule is that if you have a managed list, it is best not to attempt to populate it directly. Allow the EntityListManager to handle the work.

EntityListManagers and performance

EntityListManagers do create a certain amount of overhead, so be judicious in their use. It is also possible to narrow their scope of what they must monitor more than we did in our examples above. We instantiated our EntityListManager as follows:

The third argument, which we left null, is an array of EntityProperty objects. By leaving it null, we told the manager to submit any added or modified Employee to the test encoded in the filter Predicate. Suppose that, instead, we pass a list of properties of the Employee to this argument:

Now the EntityListManager will apply its test (about City being equal to London) only to an Employee whose City property, specifically, was modified. If you simply change only the Birthdate of an Employee already in the cache, the rule will not be evaluated. It can, after all, be safely assumed that said Employee would already be in the lists being managed if the value in its City property were “London”.

Coding more involved rules

In some of the examples above we passed an anonymous delegate to the constructor of the Predicate filter. That’s great for simple rules, but you can declare the predicate separately if you need to do something more involved. This also gives you a chance to name the rule, which can make your code more readable. Here’s a simple example: