XPCollection Concepts
- 3 minutes to read
A collection of persistent objects is represented by an XPCollection class. An XPCollection implements delayed loading, it’s populated when its items are accessed for the first time. Individual objects can be accessed via the XPCollection.Object property.
Creating an XPCollection
The first thing to do when creating a collection of persistent objects is to specify the type of object to store in the collection. At runtime, the type is specified in the constructor. At design time, use the XPCollection.ObjectClassInfo property. This property returns an XPClassInfo object which provides metadata information that describes the type of objects stored in the collection. Do not change this property manually in your code as it provides design-time support for the component.
The second thing to do is to specify a session that represents a data store where persistent objects are stored. If a collection is created at runtime, the session that the collection will work with must be initialized in the collection’s constructor. At design time, use the XPBaseCollection.Session property. If the session isn’t specified, the collection works with the default session (Session.DefaultSession).
For more information on creating XPCollection, please refer to Creating an XPCollection.
Binding an XPCollection to a Control
An XPCollection implements the IBindingList and ITypedList interfaces, so it can serve as a data source for a visual data-aware control. For instance, when a collection is bound to a grid control (for instance, the XtraGrid), the collection’s objects would be represented as editable records in the grid and object properties would be represented by grid columns (see the image below).
In this instance, the XPBaseCollection.BindingBehavior property allows you to specify whether adding new items to and/or removing existing items from the collection is allowed by the grid. The XPBaseCollection.DisplayableProperties provides a list of the object properties that are available for binding at design time.
Note
The XPCollection‘s implementation of the ITypedList interface limits the number of nesting levels in the object’s hierarchy to four levels at design time. This is done on purpose, because in some situations, Visual Studio attempts to retrieve the full hierarchy. This leads to Visual Studio hanging if the business model has self-referencing associations.
At runtime, there is no limitation for the nesting level, and you can bind controls to any property at runtime, even if it isn’t visible in the designer. Also, the end-user designer doesn’t inherit this problem, and the entire hierarchy will be retrieved.
Filtering an XPCollection
The XPCollection can be filtered when retrieving objects from a data store. To filter objects on the data store side, use the XPBaseCollection.Criteria property. Alternatively, to filter objects on the client side, use the XPBaseCollection.Filter property. For detailed information, see the topics in the Querying a Data Store section.