Creating new persisted objects

To create a new object, you should call the static New() method of the object class. The returned object will be in an uninitialized state (default values for all properties).

For example:

Customer customer = Customer.New();
Order order = Order.New();

Reading single objects

There are three methods for reading a single object from the underlying database:

Read() and ReadSafe() - reading an object by primary key

To read an object using its primary key, you should call the static Read() method of the object's class, like this:

ObjectClass myObject = ObjectClass.Read(5); // throws exception if not found
ObjectClass myObject = ObjectClass.ReadSafe(5); // returns null if not found

This will only work if ObjectClass is declared correctly (derived from CSObject<T,TKey>). The Read() method is type safe because the type of the primary key has been provided in the declaration of the class (see the previous chapter).

The Read() method will throw a CSObjectNotFoundException when the object with the specified primary key does not exist. ReadSafe() will return null if the object is not found.

ReadFirst() - reading an object by expression

When you want to read an object using a query expression, you should use the static ReadFirst() method of the object's class. You should make sure that the query returns exactly one record (or none). If more than one record satisfies the query expression, only the first one will be returned (in no particular order). If no records could be found, null is returned.

ObjectClass myObject = ObjectClass.ReadFirst(expression, parameters);

Query expressions are discussed in the chapter "Query Expressions".

Writing objects to the database

Writing an object to the underlying database is as easy as calling the Save() method on the object. When the object is a new object (created by a call to New()), it will be created. If it is an object which was read earlier, it will be updated in the database.

Only the properties which have been changed are written to the database. CoolStorage keeps track of all changes made to an object, and will minimize the number of fields that are updated. When a new record is created in the database, and the table is configured to generate the primary key automatically, CoolStorage will retrieve the generated key value and store it in the object.

When saving an object, all changes made to related objects will be saved as well. This is a very powerful feature which allows some very elegant data access code. The following example shows what can be done:

Order order = Order.New();

order.Customer = Customer.New();
order.Customer.Name = "XYZ Corporation";

OrderItem orderItem = OrderItem.New();

orderItem.Description = "Personal Computer";
orderItem.Price = 750.0;

order.OrderItems.Add(orderItem);

// This will save the order, including the related customer object and the related order items
// Since the customer and order item were newly created, these objects will be created in the database, and
// all foreign keys will be updated correctly
order.Save();

int orderId = order.OrderID; // The auto-generated primary key can now be retrieved
int customerId = order.Customer.CustomerID // Same here

The Save() methods takes care of updating all foreign keys. This means you never have to worry about foreign keys anymore!