The Storage Layer

Abstract

The Storage layer is a set of classes that provide a transparent interface for MMBase to store and retrieve data.


The storage classes will be included in the MMBase core, so no additional software need be installed.

You will, however, need to tell the MMBase system that you intend to use the (new) storage layer. In the default configuration, the system already uses the new storage layer. When upgrading older systems, you need to make changes as outlined below.

The following steps need to be taken:

We now need to set up how the storage layer accesses the database. There are two ways of doing this.

The first, and obviously easiest way for older systems, is to use the JDBC module. If you use this method, you do not need to change anything in your setup. See the configuration document for how to configure the JDBC module.

The second method is to leave database access and maintenance of such elements as connection pools to the application server.

This is a more elegant way of accessing the database, but requires some knowledge of how to set up an application server's data-sources (a class that provides a database connection). Information on setting up data sources can be found in the documentation of your application server. See the configuration document for an example.

After setting up the data source, you need to specify a JNDI pointer to it. This pointer is an identifier equal to one of the 'location' identifiers specified for the data source. We recommend using the 'ejb-location' identifier ('dbc/HsqldbDS' in the example), as that will provide connection pooling, which speeds up the storage layer.

The data source is once again a property set in the mmbaseroot.xml file:

<property name="datasource">jdbc/HsqldbDS</property>

Note

If you use this method, you need to turn off the JDBC Module (by setting it's status to inactive).

The storage layer will now be able to connect tot the database.

In order to get access to a storage (for querying, updating objects, or obtaining configuration data), you first need to obtain the factory. You can obtain this by requesting it from a static method in the StorageManagerFactory class (an abstract class in the org.mmbase.storage package), by passing the MMBase module as a reference. This will look like:

StorageManagerFactory storageFactory = StorageManagerFactory.getInstance(this);

The code can then obtain or change configuration data, or obtain access to the storage by requesting a StorageManager object:

StorageManager storage = storageFactory.getStorageManager();

The StorageManager now grants access to the actual storage. You can call methods on the instance that query data, add, update, or remove methods, or which change storage collections (nodemanagers or builders). You may also start a Transaction allowing you to rollback changes when errors occur (provided the implementation allows for it). The actual methods available to you will be detailed in the next chapters.

The StorageManager instance should be treated as granting access for one session only - do not keep it as a static or otherwise longterm member of a class. An instance that starts a transaction may get invalidated if the transaction takes too long.

The StorageManagerFactory also allows you to retrieve (or change) options and properties (attributes) of a layer. Possible options include database schemes (which allow you to tweak SQL statements for performance), setting prohibited field names, turning storage-altering commands on or off, or specifying directories for storing data such as binary files. There are also attributes for plugging in filters in the retrieval and setting of strings to and from the database.

These options may be specific for certain implementations and not available in all cases.


This is part of the MMBase documentation.

For questions and remarks about this documentation mail to: documentation@mmbase.org