Reading and writing objects - activa/iridium GitHub Wiki

There are 4 methods available to store an object in the database:

• Insert(T obj, bool saveRelations = false)
• Update(T obj, bool saveRelations = false)
• InsertOrUpdate(T obj, bool saveRelations = false)
• Save(T obj, bool saveRelations = false, bool create = null)

All those methods are defined on the DataSet class and on the StorageContext class. It makes no difference which one you use (except when you use the same object class in more than one context).

• Insert() will create a new record in the database.
• Update() will update an existing record.
• InsertOrUpdate() will create a new record in the database if needed, but only if there is a primary key with auto-increment enabled. If so, a new record will be created if the primary key field is null or 0. If there's no auto-increment primary key (for example a string primary key), InsertOrUpdate() will fail.
• Save() can behave like any of the previous methods, depending on the value of the create parameter:
  • create: null behaves like InsertOrUpdate()
  • create: true behaves like 'Insert()`
  • create: false behaves like Update().

The following methods are available to read a single object from the database:

• T Read(object key)
• T Read(...condition...)
• T Load(T obj, object key)
• T Load(...condition..., object key)

All those methods are defined on the DataSet class and on the StorageContext class. It makes no difference which one you use (except when you use the same object class in more than one context). If you use Read() on the StorageContext class, you need to specify the type of object to read: Read<T>(key).

Read() will read a single object with the given primary key(s) or the first object that matches the given condition. If the object isn't found, null will be returned. Load() will load data from the database for the given primary key(s) or the first object that matches the given condition and store it in the object. This is generally not used very often, except in case you have fields in the object that are not mapped to database fields.

Examples:

// Read a new object:
Customer customer = dbContext.Read<Customer>(customerId);
// or
Customer customer = dbContext.Read<Customer>(c => c.Name = "John Doe");

// Read data into an existing object:
Customer customer = new Customer();

customer.Load(customer, customerId);
// or
customer.Load(customer, c => c.Name == "John Doe");

######Composite keys

To read an object with a composite key, an anonymous object should be passed instead of the primary key, where the properties of the object are the names of the keys, as in Read(new { Key1=value1, Key2=value2 }. The property names should match the field names of the primary keys.

Example:

ClassAssignment assignment = dbContext.Read<ClassAssignment>(new { 
                                                              ClassID = classId, 
                                                              StudentID = studentId 
                                                             });

(to be completed)

To make it easier to work with the methods discussed above, you can use extension methods to read, save and delete objects:

Customer customer = new Customer() { ... };

customer.Save(); // is equivalent to dbContext.Save(customer)

customer.Delete(); // is equivalent to dbContext.Delete(customer)

To be able to use those extension methods, your object classes should implement the IEntity interface. The interface doesn't have any methods as it is just a marker to tell Iridium that it should add extension methods to your classes.

These methods only work when you have just one active StorageContext. When the first StorageContext instance is created in your application, the static property StorageContext.Instance will be set to that instance.