Squeak
  links to this page:    
View this PageEdit this PageUploads to this PageHistory of this PageTop of the SwikiRecent ChangesSearch the SwikiHelp Guide
Getting started with Magma
Last updated at 12:01 am UTC on 17 January 2006

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

  1. create a repository
  2. start the server
  3. open a session

If Running in Single-user Mode

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

Creating a repository

To create a repository, you must provide two things:


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 persistent object model from which every other object in the repository will be directly or indirectly referenced. A Dictionary is suggested so that you may dynamically partition the repository into multiple, named sub-roots.

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: 1010

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:


  | mySession |
  mySession := MagmaSession
    hostAddress: #(192 168 1 13) asByteArray
    port: 1010.
  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, it is recommended you keep up-to-date every 30 seconds or so changes made by other users will be reflected in the objects you visit. If you know there are very few users then this less important, but your session may eventually get booted if you wait too long. You can do this simply by aborting, even if you don't have a transaction:

  mySession abort

This will allow you to see changes to the persistent model that were made by others.

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.

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.