25.4.2Getting Started
You can install Magma using SqueakSource as indicated from http://wiki.squeak.org/squeak/2657. You basically get three packages, the client, the server and the tests. Typically you will load the server package, since the client package contains the code to connect to a remote server and the server package contains the client and server code.
To start we will work with a local repository. Later we describe the simple steps to do to get a remote server. Note that the difference between the two setups is quite small. We will define a small class to group all the operations to set up and manage a connection as well as accessing the session.
Setting up the Database. The first action is to set up the database using the message #create:root:
. We have to give a file location and a root of the object graph we want to store in this location.
MagmaRepositoryController create: 'todo' root: ToDoList new.
Here the controller will create a repository in the path{/tmp/todo} folder and it takes the singleton of the ToDoList
class since it contains all the items of our application. It is often the case that you specify a dictionary where you can define multiple roots of your application. We will use such code in the class that will manage the storage of our application.
Object subclass: #ToDoDB
instanceVariableNames: 'session'
classVariableNames: 'Default'
poolDictionaries: ''
category: 'ToDo-Model'
We define the class method path
which returns the file location of our repository as well as the method createDB
. Then we create the repository by executing ToDoDB createDB
.
ToDoDB class>>path
^ 'todo'
ToDoDB class>>createDB
MagmaRepositoryController
create: self path
root: ToDoList new.
We define an accessor method for the session and we define a MagmaSession
using the path specified before and connect to the session using the method connectAs:
. Note here that we send the message MagmaSession class>>openLocal:
to the session since we are in local mode.
ToDoDB>>session
^ session
ToDoDB>>connect
session := (MagmaSession openLocal: self class path)
connectAs: 'user'
We make sure that the session will be correctly set in the singleton method by sending the instance message connect
we previously defined.
ToDoDB class>>uniqueInstance
^ Default ifNil: [ Default := self new connect; yourself ]
We also define the method release
which disconnects and closes the session. Note that the method MagmaSession>>disconnectAndClose
deals with the fact that we are in local or remote mode.
ToDoDB class>>release
Default isNil ifFalse: [
Default session disconnectAndClose.
Default := nil ]
The following root
method illustrates how we could access the session root object.
ToDoDB class>>root
^ self uniqueInstance session root
We finally provide a class method to commit changes to the database using the method MagmaSession>>commit:
.
ToDoDB class>>commit: aBlock
self uniqueInstance session commit: aBlock
Now we are ready to test. We will create a repository, add an item to the list and commit the changes and release the connection.
ToDoDB createDB.
ToDoDB commit: [ ToDoDB root add: ToDoItem new ].
ToDoDB release.
Now using these messages we can decide when we will store the data. For example we modify the method ToDoListView>>edit:
and wrap the change of the current item into a commit:
so that the resulting objects get stored.
ToDoListView>>edit: anItem
| result |
result := self call: (ToDoItemView new model: anItem copy).
result isNil ifFalse: [
ToDoDB commit: [
self model items replaceAll: anItem with: result ] ]
Magma will detect the changes from the root object and save them if we wrap the action inside commit:
.
Note that the Magma tutorial available at http://wiki.squeak.org/squeak/2689 proposes ways to avoid modifying the domain objects to make them persistent.