Developers Manual 1.20
|
|
|
2. Persistency
2.1 Creating, Updating and Deleting Objects
Before proceeding with this section, it is worth mentioning that the example code fragments used are illustrative - in order to be used practically they would need to be executed within a transaction. Transactions are discussed in full within the next section. For now, if you wish to try any of the code fragments you should wrap them in a transaction as follows:
aReStore evaluateAsTransaction: [<code fragment>]
Creating a Persistent Object
Once you have created an object, you may very simply make it persistent (store it in the database) by sending it the message storeIn:Person new
surname: 'Smith';
firstName: 'John';
storeIn: aReStore
Updating a Persistent Object
Updating a persistent object is even more straightforward - no special actions are required, since ReStore is able to detect all changes to a persistent object and translate these into database updates. All that is needed is to update the object as required:alreadyPersistentPerson surname: 'Smythe'
Scope of Persistency
When you make an object persistent, any other new model objects held by the object will also be made persistent; e.g.Person new
surname: 'Jones';
firstName: 'David';
homeAddress: (Address firstLine: '4a Camden Square' postcode: 'NW3 2XZ');
children:
(OrderedCollection with:
(Person new surname: 'Jones'; firstName: 'Lucy'; yourself));
storeIn: aReStore
In this example, the new Address object, plus all members of the children collection will also be made persistent. These rules also apply when updating an existing persistent object, i.e.
alreadyPersistentPerson
workAddress: (Address firstLine: '129d New Oxford Street' postcode: 'W1 1AB')In this case, the new Address object assigned to workAddress will automatically be made persistent.
Deleting a Persistent Object
Before detailing how to delete an object, it is worthwhile considering what this means. When writing regular Smalltalk code, 'deleting' an object is not a concept that a developer needs to consider - you create an object, use it and when you have finished with it (no longer retain any references to it), the object will be automatically removed from memory by the Garbage Collector.This remains true when working with persistent objects - however once you have made an object persistent, it will remain in the database even when it has been garbage-collected from memory. Hence you need to explicitly tell a persistent object that it should be deleted from the database. This is done very simply with the message unstore:
alreadyPersistentPerson unstore
Responding to Deletions
When an object is deleted from the database, it is possible that a number of 'cleanup' operations will need to be performed. The bulk of these will fall into the category of deleting dependent objects - providing these dependencies have been detailed correctly in the class specification method, then this will be done automatically. However there are other activities that may need also to be done. To allow for such actions, ReStore sends the message onAboutToUnstore to every object immediately prior to processing the unstore message.An example of both dependent relationships and the use of onAboutToUnstore can be seen in the EntertainmentShop example application. The class Order has a dependent relationship with its collection of OrderItems - thus when an Order is sent the message unstore, its associated OrderItems are also sent unstore. In turn, OrderItem implements onAboutToUnstore to release any StockItems allocated to it:
"The receiver is about to be unstored - release any allocated stock"onAboutToUnstore
self isStockAllocated ifTrue: [self deallocateStock]
2.1 Creating, Updating and Deleting Objects