The heart of the Norman project, as previous posts have alluded to is the POCO object server, or Engine. This is described in the IEngine interface, show below. The default implementation of IEngine, ObviousCode.Norm.Vetinari.Engine, I shall discuss in later posts
public interface IEngine
{
event PersistenceErrorsDetected PersistenceErrorsDetected;
event PersistenceReportRaised<IBrokeredDataObject> PersistenceReportRaised;
string Guid { get; }
T Create<T>() where T : IBrokeredDataObject, new();
T Create<T>(Dictionary<string, object> parameters) where T : IBrokeredDataObject, new();
T Get<T>(string key) where T : IBrokeredDataObject, new();
IDataObjectCollection<T> GetObjects<T>(string filter) where T : IBrokeredDataObject, new();
IDataObjectCollection<T> GetObjects<T>() where T : IBrokeredDataObject, new();
bool CacheContains(IBrokeredDataObject dataObject);
bool CacheContainsKey(string key);
bool Persist();
bool Persist<T>(T dataObject) where T : IBrokeredDataObject;
void Revert(bool deleteCreatedObjects);
void Revert(IBrokeredDataObject objectToRevert, bool deleteCreatedObject);
void ResetCache();
void ResetCache<T>() where T : IBrokeredDataObject;
void ResetCache(string key);
IPersistenceDelta<IBrokeredDataObject> RequestPersistenceDelta();
IPersistenceDelta<IBrokeredDataObject> RequestPersistenceDelta(IBrokeredDataObject dataObject);
IDbDataObjectProvider ObjectDataProvider { get; set; }
ISimpleCache<IBrokeredDataObject> Cache { get; set; }
IModelModifiedBroker ModelModifiedBroker { get; set; }
}
Events
- PersistenceErrorsDetected
I shall hold off talking too deeply about the PersistenceErrorsDetected event, as the functionality to fire it has not yet been implemented. Simply put, it will fire when the engine is in a distributed mode, and, before a Persistence operation is completed, data is detected that may corrupt the lineage of a model.
- PersistenceReportRaised
A 'Persistence Delta' object is generated each time a Persitence operation is requested, or the RequestPersistenceDelta functions are called. This object describes all changes to the model that will be saved during Persistence.
public interface IPersistenceDelta<T> where T : IBrokeredDataObject { IList<ICreatedObjectPersistenceReportItem<T>> CreatedItems { get; set; } IList<IModifiedObjectPersistenceReportItem<T>> ModifiedItems { get; set; } IList<IDeletedObjectPersistenceReportItem<T>> DeletedItems { get; set; } IList<IChangedTablePersistenceReportItem> DataTableItems { get; set; } void Load(IEnumerable<T> values); void Load(T value); }
The interface itself, I feel, is fairly self-explanatory, though it is worth pointing out the the Persistance contract allows for all, a subset, or a single object to be assessed in the Delta, depending on what parameters are passed into the Load function. It is up to the implemented Persistance Delta class to work with these objects, rather than it always working with all the objects loaded in the engine. There is a default Implementation of IPersistenceDelta, PersistenceReport, in the Namespace ObviousCode.Norm.Vetinari.DataObjectPersister that I will talk about in a later post, which may be used, however any implementation of IPersistanceDelta can be sent to the PersistenceReportRaisedEventArgs of this event. The engine, however, currently only supports individual object reports, or assesses all object in the cache.
Functions
- T Create<T>() where T : IBrokeredDataObject, new()
This function is a parameterless request for a new object of type T to be created, hence the new() constraint on T.
- T Create<T>(Dictionary<string, object> parameters) where T : IBrokeredDataObject, new()
This function is a request for a new object of type T to be created, hence the new() constraint on T. Parameters may be passed to this request, stored in the parameters dictionary object.
- T Get<T>(string key) where T : IBrokeredDataObject, new()
This function is a request for an existing object of type T. At present, only string fields can be used as keys for objects, though this may change if it is found to be too limiting in the future. Similarily, combined key fields are not yet supported. The new() constraint on T is required if the engine needs to create the object if it hasn't previously cached it.
- IDataObjectCollection<T> GetObjects<T>(string filter) where T : IBrokeredDataObject, new()
This function is a request for a collection of all objects of type T that meet a filter condition (in the format attribute=value, attribute>value etc). The IDataObjectCollection implements IList<T> with a where T : IBrokeredDataObject, new() constrain.
- IDataObjectCollection<T> GetObjects<T>() where T : IBrokeredDataObject, new()
This function is a request for a collection of all objects of type T. The IDataObjectCollection implements IList<T> with a where T : IBrokeredDataObject, new() constrain.
- bool CacheContains(IBrokeredDataObject dataObject)
This function is a request to confirm whether a given object has already been cached by the engine.
- bool CacheContainsKey(string key)
This function is a request to confirm whether a given object, identified by key, has already been cached by the engine.
- bool Persist()
This function is a request to persist any changes to all objects, in the engine cache, back to the datastore, and return a boolean to indicate success or failure. It will cause a PersistenceReportRaised event to be raised.
- bool Persist<T>(T dataObject) where T : IBrokeredDataObject
This function is a request to persist any changes to the given object back to the datastore, and return a boolean to indicate success or failure. It must cause a PersistenceReportRaised event to be raised.
- bool Revert(bool deleteCreatedObjects)
This function is a request to undo all changes to the objects in the engine cache that have been made since either the objects were last persisted or retrieved from the datastore, and returns a boolean to indicate success or failure. It must cause a ModelReverting event (before reversion) and a ModelReverted (after reversion) event to be raised in the ModelModifiedBroker. The deleteCreatedObjects flag indicates whether newly created objects should be removed from the cache (effectively deleted from the model). If this value is set to false, newly created objects should simply revert to their initial state.
- bool Revert(IBrokeredDataObject objectToRever, bool deleteCreatedObject)
This function is a request to undo all changes to a given object in the engine cache that have been made since it was last persisted or retrieved from the datastore, and returns a boolean to indicate success or failure. It must cause an ObjectReverting event (before reversion) and an ObjectReverted (after reversion) event to be raised in the ModelModifiedBroker. The deleteCreatedObject flag indicates whether newly created objects should be removed from the cache (effectively deleted from the model). If this value is set to false, newly created objects should simply revert to their initial state.
- IPersistenceDelta<IBrokeredDataObject> RequestPersistenceDelta()
This function is a request for the PersistenceDelta report discussed in the PersistenceReportRaised event section above. All objects cached in the engine will be tested for inclusion.
- IPersistenceDelta<IBrokeredDataObject> RequestPersistenceDelta(IBrokeredDataObject brokeredDataObject)
This function is a request for the PersistenceDelta report discussed in the PersistenceReportRaised event section above, based on a given object.
Properties
The three properties will be required for an implemented engine, and will be discussed in greater detail in later posts.
