When you define a collection of many objects, Persistate generates a public collection property to access the member objects, along with a private collection field to actually hold the objects.  Like several collections, the type of many collection properties is IndexedList<T>.  However, with many collections, before you can access objects in the collection, you must retrieve the objects you want to work with.  As opposed to several collections, Persistate does not automatically retrieve all the elements of a many collection.

Persistate generates a number of methods which allow you to access subsets of the collection.  These are based on the discriminative and distinctive members of the class of the collection elements.  Once you have retrieved a subset of objects, you can access them in the same way as you do for several collections, as described in Collections of several objects. This includes the use of the string and two parameter indexers.

Retrieving based on distinctive members

The defining point about distinctive members is that the values of such members should be unique in a collection.  Consequently, the method that Persistate generates for retrieving objects in many collections based on distinctive members return a single object of the appropriate class.  This method will be named

<collection singular name>With<member name>

So for example, for the Publications collection of the Library singleton, the method generated for the IsbnNumber member will be called PublicationWithIsbnNumber.  Here is an example of the use of this method, which sets all available stock copies of a publication with a supplied ISBN number as unavailable.  Note that although the method returns  the retrieved Publication object, it is also available in the Library.Publications collection, which always holds the results of the most recent retrieval.

Publication publication = The.Library.PublicationWithIsbnNumber(suppliedIsbn);
foreach (StockCopy stockCopy in publication.StockCopies)
   if (stockCopy.LendStatus == LendStatus.Available)
      stockCopy.LendStatus = LendStatus.Unavailable;

Retrieving based on discriminative members

Remember that defining a member as nominative also marks them as discriminative, so this applies to them also.  Unlike distinctive members, there is no requirement that discriminative members have unique values within collections.  This means that a given value of a discriminative member will select a subset containing zero, one or more of the objects in a collection.  There are two types of method generated for many collections - one type uses a single discriminative member and the other uses all discriminative members..

Retrieving Using One Discriminative Member

For each many collection member in a class, Persistate creates a lookup method for every discriminative member of the class of objects in the collection.  This method will be named

<collection plural name>With<member name>

For example, for the Authors collection in the Library singleton, the generated methods for the surname and forename discriminative members are called AuthorsWithSurname and AuthorsWithForename respectively.  Here are examples of their use.

int smiths = The.Library.AuthorsWithSurname("Smith").Count;

Author[] benjamins = The.Library.AuthorsWithForename("Benjamin").ToArray();

Similarly to the methods using distinctive members, these methods place the retrieved subset in the generated private collection field, which is accessible using the public property.  In the case of the above examples this would be the Authors property of the Library class.  You can use this property to access the last retrieved subset.  Persistate clears the collection on every method call, before retrieving the next subset.

Retrieving Using All Discriminative Members

For each many collection member in a class, Persistate creates a single lookup method using all discriminative members.  This method is used by the lookup forms which Persistate generates for many collections, and it's design is tailored for that purpose, but you can use it in open code too.  The method will be named

<collection plural name>Like

For example, for the Borrowers collection in the Library singleton, the generated method will be called BorrowersLike.  For this method, "all discriminative members" includes discriminative, distinctive and nominative members of one of the text data classes, coming from a number of sources. These sources are the class of the collection itself, any base class or classes that it has, and the class of any object member it has which is marked as discriminative.

For example, in the borrower class, the postal address member is an object member marked as discriminative.,  and its base class person has two discriminative members.  These discriminative members are therefore included as the parameters for the BorrowersLike method, which are Person.Surname, Person.Forename, PostalAddress.Street and PostalAddress.City.

The generated method takes values for these members as parameters.  However, the method does not have discrete parameters for each member, rather it uses params object[] keys as a single parameter and you must supply values in the appropriate order.  (This design stems from the use of these methods in lookup forms.)  The order you supply parameters follows the following rules.

The return value from these methods is a collection of Choice objects.  These have a set of properties called Value1, Value2, etc. which, for each retrieved object, hold the text values of each of the discriminative members supplied as parameters.  The Target property of each Choice will retrieve the object chosen.

When you supply parameter values, if you don't care about the value of a particular member, supply null.  For the values you do supply, you can use wildcards.  The character % matches zero of more characters, and _ matches any single character.  The following example finds the borrowers whose surnames begin with "Nichol" in Inverness, then iterates on the resulting collection.

IndexedList<Choice> choices = The.Library.BorrowersLike("Nichol%", null, null, "Inverness");
foreach (Choice choice in choices) {
   Borrower borrower = (Borrower)choice.Target;
   if (borrower.LentStockCopies.Count > 0)
      return borrower;
}