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
- 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 fully-qualified 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 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:
- 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
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.