jdbm.recman

## Class BaseRecordManager

- java.lang.Object
- - jdbm.recman.BaseRecordManager

All Implemented Interfaces:
  RecordManager

    public final class BaseRecordManager
    extends Object
    implements RecordManager

This class manages records, which are uninterpreted blobs of data. The set of operations is simple and straightforward: you communicate with the class using long "rowids" and byte[] data blocks. Rowids are returned on inserts and you can stash them away someplace safe to be able to get back to them. Data blocks can be as long as you wish, and may have lengths different from the original when updating.

Operations are synchronized, so that only one of them will happen concurrently even if you hammer away from multiple threads. Operations are made atomic by keeping a transaction log which is recovered after a crash, so the operations specified by this interface all have ACID properties.

You identify a file by just the name. The package attaches `.db` for the database file, and `.lg` for the transaction log. The transaction log is synchronized regularly and then restarted, so don't worry if you see the size going up and down.

Author:
  Alex Boisvert, Cees de Groot

### Field Summary

Fields
`static boolean` `DEBUG` Static debugging flag
`static int` `NAME_DIRECTORY_ROOT` Reserved slot for name directory.

### Constructor Summary

Constructors
Constructor and Description
`BaseRecordManager(String filename)` Creates a record manager for the indicated file

### Method Summary

Methods
`void` `close()` Closes the record manager.
`void` `commit()` Commit (make persistent) all changes since beginning of transaction.
`void` `delete(long recid)` Deletes a record.
`void` `disableTransactions()` Switches off transactions for the record manager.
`Object` `fetch(long recid)` Fetches a record using standard java object serialization.
`Object` `fetch(long recid, Serializer serializer)` Fetches a record using a custom serializer.
`long` `getNamedObject(String name)` Obtain the record id of a named object.
`long` `getRoot(int id)` Returns the indicated root rowid.
`int` `getRootCount()` Returns the number of slots available for "root" rowids.
`TransactionManager` `getTransactionManager()` Get the underlying Transaction Manager
`long` `insert(Object obj)` Inserts a new record using standard java object serialization.
`long` `insert(Object obj, Serializer serializer)` Inserts a new record using a custom serializer.
`void` `rollback()` Rollback (cancel) all changes since beginning of transaction.
`void` `setNamedObject(String name, long recid)` Set the record id of a named object.
`void` `setRoot(int id, long rowid)` Sets the indicated root rowid.
`void` `update(long recid, Object obj)` Updates a record using standard java object serialization.
`void` `update(long recid, Object obj, Serializer serializer)` Updates a record using a custom serializer.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### NAME_DIRECTORY_ROOT

    public static final int NAME_DIRECTORY_ROOT

Reserved slot for name directory.

See Also:
  Constant Field Values

#### DEBUG

    public static final boolean DEBUG

Static debugging flag

See Also:
  Constant Field Values

### Constructor Detail

#### BaseRecordManager

    public BaseRecordManager(String filename)
                      throws IOException

Creates a record manager for the indicated file

Throws:
  `IOException` - when the file cannot be opened or is not a valid file content-wise.

### Method Detail

#### getTransactionManager

    public TransactionManager getTransactionManager()
                                             throws IOException

Get the underlying Transaction Manager

Throws:
  `IOException`

#### disableTransactions

    public void disableTransactions()

Switches off transactions for the record manager. This means that a) a transaction log is not kept, and b) writes aren't synch'ed after every update. This is useful when batch inserting into a new database.

Only call this method directly after opening the file, otherwise the results will be undefined.

#### close

    public void close()
               throws IOException

Closes the record manager.

Specified by:
  `close` in interface `RecordManager`
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### insert

    public long insert(Object obj)
                throws IOException

Inserts a new record using standard java object serialization.

Specified by:
  `insert` in interface `RecordManager`
Parameters:
  `obj` - the object for the new record.
Returns:
  the rowid for the new record.
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### insert

    public long insert(Object obj,
              Serializer serializer)
                throws IOException

Inserts a new record using a custom serializer.

Specified by:
  `insert` in interface `RecordManager`
Parameters:
  `obj` - the object for the new record.
  `serializer` - a custom serializer
Returns:
  the rowid for the new record.
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### delete

    public void delete(long recid)
                throws IOException

Deletes a record.

Specified by:
  `delete` in interface `RecordManager`
Parameters:
  `recid` - the rowid for the record that should be deleted.
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### update

    public void update(long recid,
              Object obj)
                throws IOException

Updates a record using standard java object serialization.

Specified by:
  `update` in interface `RecordManager`
Parameters:
  `recid` - the recid for the record that is to be updated.
  `obj` - the new object for the record.
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### update

    public void update(long recid,
              Object obj,
              Serializer serializer)
                throws IOException

Updates a record using a custom serializer.

Specified by:
  `update` in interface `RecordManager`
Parameters:
  `recid` - the recid for the record that is to be updated.
  `obj` - the new object for the record.
  `serializer` - a custom serializer
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### fetch

    public Object fetch(long recid)
                 throws IOException

Fetches a record using standard java object serialization.

Specified by:
  `fetch` in interface `RecordManager`
Parameters:
  `recid` - the recid for the record that must be fetched.
Returns:
  the object contained in the record.
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### fetch

    public Object fetch(long recid,
               Serializer serializer)
                 throws IOException

Fetches a record using a custom serializer.

Specified by:
  `fetch` in interface `RecordManager`
Parameters:
  `recid` - the recid for the record that must be fetched.
  `serializer` - a custom serializer
Returns:
  the object contained in the record.
Throws:
  `IOException` - when one of the underlying I/O operations fails.

#### getRootCount

    public int getRootCount()

Returns the number of slots available for "root" rowids. These slots can be used to store special rowids, like rowids that point to other rowids. Root rowids are useful for bootstrapping access to a set of data.

Specified by:
  `getRootCount` in interface `RecordManager`

#### getRoot

    public long getRoot(int id)
                 throws IOException

Returns the indicated root rowid.

Specified by:
  `getRoot` in interface `RecordManager`
Throws:
  `IOException`
See Also:
  `getRootCount()`

#### setRoot

    public void setRoot(int id,
               long rowid)
                 throws IOException

Sets the indicated root rowid.

Specified by:
  `setRoot` in interface `RecordManager`
Throws:
  `IOException`
See Also:
  `getRootCount()`

#### getNamedObject

    public long getNamedObject(String name)
                        throws IOException

Obtain the record id of a named object. Returns 0 if named object doesn't exist.

Specified by:
  `getNamedObject` in interface `RecordManager`
Throws:
  `IOException`

#### setNamedObject

    public void setNamedObject(String name,
                      long recid)
                        throws IOException

Set the record id of a named object.

Specified by:
  `setNamedObject` in interface `RecordManager`
Throws:
  `IOException`

#### commit

    public void commit()
                throws IOException

Commit (make persistent) all changes since beginning of transaction.

Specified by:
  `commit` in interface `RecordManager`
Throws:
  `IOException`

#### rollback

    public void rollback()
                  throws IOException

Rollback (cancel) all changes since beginning of transaction.

Specified by:
  `rollback` in interface `RecordManager`
Throws:
  `IOException`