The Second Chapter
=============

Configuring Pier to work with Magma

Step 1. Add WAMagmaConfiguration to your pier app
   - In /seaside/config application, click on the 'configure' link next
to your pier application.
   - From the drop down menu named 'Add Ancestor', select
'WAMagmaConfiguration' and click the 'Add' button.
   - (optional step) to be tidy, click the '(remove)' link next to
'WARenderLoopConfiguration', since WAMagmaConfiguration includes this
anyway.

Step 2. Set the session class to 'WAMagmaSharedSession'
   - In the general config section, in the line entitled 'Session
Class' click the 'overide' link.
   - From the drop down menu which appears next to 'Session Class'
select 'WAMagmaSharedSession'.

Step 3. (optionally) Set the location of the magma repository.
   - The default is set to use a directory named 'magma' in the image
default directory.
   - overriding this setting to choose an alternative directory, or a
remote magma server.

Step 4.  Save Changes and Close.
   - click the 'Save' button at the bottom of the configuration page.
   - click the 'Close' button to return to the dispatcher editor.

Notice the appearance of a link next to the 'pier' application, 'magma'!

Step 5. Create the magma repository for pier.

Enter the control panel for magma using the 'magma' link next to your
pier app.

The top panel should report an error, (i.e. there is no database yet)
*    Repository path setting: *magma
*    Error: /media/hda1/squeak/pr_gsoc/magma/objects not found.*

At present this magma control panel is application agnostic, it doesnt
know anything about pier, hence you have to explicitly choose what class
of root object the database should be created with. (Some magma-seaside
users e.g. Gjallar, just have the app initialize the database
automatically when it is not found)

- To create a repository for pier in the directory specified, choose the
class of the desired repository, in this case a 'PRMagmaRepository',
click the 'create' button.

On returning you will see something like this.
Repository Path Setting: magma (delete)
Persisted Objects Count: 569
Session Id: 2
Cached Object Count: 670
ReadStrategy: a WAMagmaReadStrategyDefault
Root Object: a PRMagmaRepository (explore)
 
The 'delete' link will delete the repository and start again.
The 'explore' link, is similar to the seaside 'debug' link, it opens an
explorer in squeak on the root db object.

Step 6.
 
Returning to the seaside/config app, click the 'pier' link to obtain the pier persistency manager. There you will find a ui for changing which kernel is served* and its persistency scheme.
 
*the 'serve all kernels' option needs the class PRMainAllKernels which is not loaded

Switching from PRNullPersistency to PRMagmaPersistency is all that is required.
Then click the 'migrate' button, and later 'commit' the change.