Introduction
Entity Graphs is an important cross cutting concept that has an influence on
validation, serialization,
change tracking, and
corruptness support.
It's worth taking a look in a centralized point, like this page, to fully understand it.
Entity Graphs support
A
directed graph is a mathematical structure where a set of nodes can be arbitrarily connected to any other, so they can contain cycles.
Graph > Acyclic graph > Tree
Signum Framework allows full graph saving and retrieving, and this is important because then you can easily send self-consistent sets of objects to the client machine and save all of them when they come back.
There is however a different kind of relationship between entities, so you can consider different kinds of graphs that play different roles in Signum Framework.
Entity Graph Types
As you saw in
BaseEntities, every entity-related object that can some how be saved in the database inherits from Modifiable. There are four common Modifiables for you to use:
Of these previous four classes, only the objects inheriting IdentifiableEntity can be saved by their own, while the others are saved as part of some IdentifiableEntity. An IdentifiableEntity and all of it's belonging Modifiables form the
Identifiable Graph.
All the reachable objects, no matter if they are IdentifiableEntities or just a Modifiable, form the
Full Graph.
And finally, we can consider every modifiable (and identifiable) as a degenerated graph of just one node.
Let's clarify this with the following picture:
Here we have five IdentifiableEntities, each of them with some Modifiable that belongs to them. Some things to notice:
- There's a cycle containing three identifiables, Signum Engine will handle that without problems.
- Identifiables and Embeddeds can point to both Identifiables and Embeddeds, but Lites objects always have to point to an Identifiable (embedded have no ID).
- You can make MList of Identifiables, Embeddeds and Lites, this is very convinient and also favours orthogonality.
- It's structurally impossible to make a cycle in the database using just embeddeds, for the same reason you can't make a cycle using only structs.
Isolated Modifiable
Change Tracking: The property SelfModified tells you about a particular Modifiable being changed.
Isolated ModifiableEntity
Validation: You can make an IntegrityCheck over any Modifiable and it will take into account only the errors of this modifiable alone.
i.e: In a ShipmentAddressDN entity, you can validate that your Country entity mustn't be null, you can even validate that the country has to be the US, but it's not a good idea to validate recursively for the consistence of ContryDN entity if you want to avoid duplication of errors since the validation infrastructure is going to call the ContryDN IntegrityCheck anyway. This is applicable if CountryDN is an EnbeddedEntity of an IdentifiableEntity.
The Identifiable Graph
Validation: You can call IdentifiableIntegrityCheck over any identifiable and you will get an string with all the errors of the entity and all of the owned Modifiables. It walks the Identifiable Graph for you.
Change Tracking: Just before saving, Signum Engine propagates the value of SelfModified property backwards by turning on Modified property in the Identifiable container, and then the whole entity is saved.
Corruptness support: The ability to make a corrupt entity (an entity that skips some validations) is grained at the Identifiable Graph level, so in order to turn it on you have to override IdentifiableIntegrityCheck. Then the entity and all the owned modifiable will have
Corruption.Allowed on saving.
The Full Graph
Validation: You can call FullIntegrityCheck over any
ModifiableEntity and you will get an string with all the errors of all the reacheable entities from the root modifiable. It walks the Full Graph for you.
Generally, try to avoid walking Lite relationships on validation, since you don't know if the lazy is going to be fat or thin on the client side.
Serialization: The full graph is just the graph of all the reachable entities by walking the relationships in memory. As usual, this graph is the one which will be serialized using standard .Net BinaryFormatter or SoapFormatter. Nothing new here.
Lites play a role here too. By design Lite objects affect Database retrieving, but not serialization, so you have to be careful about the state of your lazys (fat or thin) before serializing / sending entities.