Formalisation of fetch models

[homedirectory]

Description

The concept of fetch models in TG is fairly sophisticated, requiring a thorough analysis of the source code to be understood.
The goal of this issue is to create a specification for fetch models, so that they can be understood more easily by both platform and application developers.

• Document each fetch model category (ua.com.fielden.platform.entity.query.fluent.fetch.FetchCategory).
• Document any special cases that may occur during fetch model processing.

Expected outcome

Fetch models are properly documented, facilitating informal reasoning for developers.

Technical details

There are 3 core abstractions related to fetch models:

• ua.com.fielden.platform.entity.query.fluent.fetch - used to specify a fetch model for an EQL query;
• ua.com.fielden.platform.entity.fetch.IFetchProvider - primarily used by entity companions and Web UI; ultimately gets converted to a fetch via method fetchModel(); was introduced by Entity Fetch Strategy #120 with a goal to have a developer-friendly API;
• ua.com.fielden.platform.entity.query.IRetrievalModel - implementation-side representation of fetch models, used by the EQL engine.

To maximise visibilty of documentation, it is proposed to attach it to the fetch class, which can be referred to by IFetchProvider. IRetrievalModel is located in a different module, in platform-dao, and can't be referenced by the other two, which are located in platform-pojo-bl, but that is not a problem since IRetrievalModel is not directly visible to developers anyway.

Change overview

• Documentation for retrieval models (IRetrievalModel and its implementations).
• Documentation of EQL-specific metadata (QuerySourceInfoProvider).
• Retrieval model construction now has access to QuerySourceInfoProvider, which enables it to determine whether property id (any property, in general) should be included for any given synthetic entity type. This simplifies the implementation by using a proper abstraction (QuerySourceInfoProvider) instead of having to handle each property by hand.
• Properties id, key and version are assigned plain nature when generating metadata for synthetic entities. Previously, they could be assigned persistent nature, which doesn't make sense for synthetic entities.
• Additonal method signature: fetch.with(CharSequence, CharSequence...) for convenience of specifying multiple properties (equivalent change was made for method without).
• Improved string representation for fetch and EntityRetrievalModel.
• Removed IRetrievalModel.containsOnlyTotals, since property id doesn't need special handling during yield enhancement in synthetic entities.
• Introduced utilities for immutable collections (ImmutableCollectionUtil) and maps (ImmutableMapUtils).
• Documentation for fetch categories (in TG Wiki and javadoc).
• Stricter validation of synthetic models: it is an error if there is a yield that uses a non-existent property as an alias.
• Enabled the use of a source query which models its result as EntityAggregates and uses yieldAll. Such queries had not been expected and thus had been unsupported.

Required changes in TG applications

• Identify and correct synthetic models that yield into non-existing properties.