Getting started with Magma


	links to this page:

Last updated at 11:43 pm UTC on 8 March 2009

Getting Started

To use Magma, first download and install the code. Then you may decide in what mode would your magma be running and follow these steps:

If Running in Server/Client Mode

create a repository
start the server
open a session

If Running in Single-user Mode

create a repository
open a session, in a different way(see: Single-user mode below)

Creating a repository

To create a repository, you must provide two things:

a path to the directory magma may use to keep and maintain its files
the root object of the repository

Magma maintains a single directory on the filesystem for each repository. When creating or opening Magma repositories, you specify the fully-qualified directory in which it may create its various files.

You should also provide the root object of the repository. This is the root of your domain object in the domain is referenced.

The code, thus:

  MagmaRepositoryController
    create: 'c:\myMagmaFolder'
    root: Dictionary new

Starting the server

Magma utilizes TCP/IP for its network communications. To enable multi-user access to a Magma repository, you may start the Magma server in its own image and inspect the following:

  MagmaServerConsole new
    open: 'c:\myMagmaFolder' ;
    processOn: 51001

Be sure to inspect this so you will have access to console commands, such as #shutdown.

Open a MagmaSession

Once the server is running, a MagmaSession can be connected from the same or another image to gain access and change objects in the repository. Connecting a session requires the following information:

a name to identify your session. When someone tries to overlay changes you've made to objects, they will be notified that those objects were changed by your session, identified by the name you provide.
the IP address of the machine hosting the Magma repository, and the port it is listening on.

  | mySession |
  mySession := MagmaSession
    host: 'localhost'
    port: 51001.
  mySession connectAs: 'chris'

If you run this from a Workspace, be sure to inspect the result so you will be able to properly disconnect from the server.

Once connected, changes to the persistent model are committed through transactions.

  mySession commit: 
    [ mySession root
      at: 'persons'
      put: (OrderedCollection with: (Person name: 'Paula')) ]

While your session is connected, you may force a refresh of your view of the persistent domain model with the #refresh message:

  mySession refresh

With #refresh, your own changes are kept although you may discover an object you are working on has already been changed by someone else. To refresh all objects to the repository state, including your own changes, the #abort message instead.

You can access the root of the repository later and navigate from there.

  mySession root at: 'persons'

To minimize concurrency it is recommended that transactions begin just before you make changes, and commit immediately after. A refresh just before a commit may be helpful as well. But CommitConflicts will occur nonetheless.

Once you're done using the session, you should disconnect it:

  mySession disconnect

Single-user mode

If you know will be operating in a single-user environment, starting a second image to run the server may not always be convenient. Thankfully, Magma supports a "direct-connect" single-user mode, where a single Magma session connects directly to the repository in one image.

To run in single-user mode, you do not need to use MagmaServerConsole.

Instead, you must specify the name of the object file when opening a MagmaSession instead of the IP and port.

  myMagmaSession := MagmaSession openLocal: 'c:\myMagmaFolder\myRepository.magma'.
  myMagmaSession connectAs: 'chris'

Additionally, when you're ready to disconnect your last session, you also should close the repository:

  myMagmaSession disconnect; closeRepository

The repository can then be opened again in single or multi-user mode.

Objects are persisted by reachability

With object databases, there is no notion of, "inserting objects into the database". Instead, you merely attach new objects to persistent ones and commit. All directly or indirectly referenced objects from any persistent object are automatically detected and saved into the database.