org.lacibus.backingstore

Class FileBackingStore

java.lang.Object

org.lacibus.backingstore.FileBackingStore

All Implemented Interfaces:

java.io.Serializable

public class FileBackingStore
extends java.lang.Object
implements java.io.Serializable

A backing store implemented by files on disc that maintains transactional record integrity on system re-start.

When a record is stored on disc, a reference is returned that enables the consuming application to retrieve the record.

Records on disc are not over-written. To change a record, the old copy is marked as deleted, a new copy is written, and a new reference is returned.

A transaction identity is stored with each record copy, and details are kept of which transactions have been completed.

When the system is re-started, the records and their references are read by the consuming application, to enable subsequent record retrieval. Only records written by transactions that have completed are supplied.

Note that if two threads use the same transaction then it may not be possible for the consuming application to determine whether a write made by one thread occurred before or after the other thread closed the transaction.

The store performs regular maintenance tasks to remove notes of old transactions and re-allocate disc areas whose records were deleted long enough ago for re-use to be safe. This is done concurrently with store read and write operations by a separate instance of the BackingStoreMaintainer class.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	FileBackingStore.ItemSegmentRecord An instance of this class describes a segment containing an item
class	FileBackingStore.Segment An instance of this class represents a segment used to store a record or a record summary
class	FileBackingStore.SegmentRecord An instance of this class describes a segment
class	FileBackingStore.TripleSegmentRecord An instance of this class describes a segment containing a triple

Field Summary

Fields

Modifier and Type	Field and Description
static int	VALIDITY_ERROR The record is not valid
static int	VALIDITY_INVALID_NOREINSTATE The record is invalid and should not be reinstated if the last transaction to touch it does not complete (used when marking as invalid a record created by the same transaction and when loading a deleted record)
static int	VALIDITY_INVALID_REINSTATE The record is invalid but should be reinstated if the last transaction to touch it does not complete (used when marking as invalid a record created by a different transaction)
static int	VALIDITY_NO_INFO The record is valid but there is no information on whether it should be re-instated
static int	VALIDITY_VALID_NOREINSTATE The record is valid but should not be reinstated if the last transaction to touch it does not complete (used when creating a record)
static int	VALIDITY_VALID_REINSTATE The record is valid and should be reinstated if the last transaction to touch it does not complete (used when reinstating a record)

Constructor Summary

Constructors

Constructor and Description
FileBackingStore(org.lacibus.backingstore.BackingStoreSourceConnector connector, java.io.File directory, Logger logger) Construct a new file backingStore

Method Summary

Modifier and Type	Method and Description
int	addItem(long itemNr, long onlyReadLevelSourceNr, long onlyReadLevelItemNr, long readOrWriteLevelSourceNr, long readOrWriteLevelItemNr, Transaction trans) Add an item
org.lacibus.backingstore.RefAndSummary	addTriple(long tripleNr, long subjectItemNr, long verbSourceNr, long verbItemNr, Datum object, Transaction trans) Add a triple
void	close() Close the backing backingStore
java.lang.String	findTransactionRecords(long firstSeq, long lastSeq) Find the records of transactions with sequence numbers in a given range.
java.lang.String	findTripleRecords(long tripleIdNr) Find the records of actions on a particular triple.
java.lang.Exception	getBackingStoreTerminator() Return an exception that caused backing store operation to abort.
java.io.File	getBigFileDirectory()
Datum	getBinaryTripleObject(int storeRef) Get a stored binary triple's object
long	getHighestLoadedTransactionNr()
java.util.Map<java.lang.Long,java.util.List<FileBackingStore.ItemSegmentRecord>>	getItemRecords() Get the item segment records, grouped by item
Datum	getTextTripleObject(int storeRef) Get a stored text triple's object
java.util.Map<java.lang.Long,java.util.List<FileBackingStore.TripleSegmentRecord>>	getTripleRecords() Get the triple segment records, grouped by triple
void	initialise(boolean clear) Initialise the store
static boolean	isBigTripleRecordType(short type) Determine whether a record type is the type of a triple record with a big object.
void	load(org.lacibus.backingstore.BackingStoreClient client, TransactionsStatus status) Load the stored items and triples
java.lang.String	printRecordValidity(int validity) Print the record validity indicator as a descriptive string
void	removeItem(int storeRef, Transaction trans) Remove an item from the backingStore
void	removeTriple(int storeRef, Transaction trans) Remove a triple from the backingStore.
void	simulateIoError() Simulate an I/O error for testing purposes
void	transactionComplete(Transaction t) End a transaction.
void	transactionStarted(Transaction t) Note that a transaction is started

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VALIDITY_ERROR

public static final int VALIDITY_ERROR

The record is not valid

See Also:

Constant Field Values

VALIDITY_NO_INFO

public static final int VALIDITY_NO_INFO

The record is valid but there is no information on whether it should be re-instated

See Also:

Constant Field Values

VALIDITY_VALID_NOREINSTATE

public static final int VALIDITY_VALID_NOREINSTATE

The record is valid but should not be reinstated if the last transaction to touch it does not complete (used when creating a record)

See Also:

Constant Field Values

VALIDITY_VALID_REINSTATE

public static final int VALIDITY_VALID_REINSTATE

The record is valid and should be reinstated if the last transaction to touch it does not complete (used when reinstating a record)

See Also:

Constant Field Values

VALIDITY_INVALID_REINSTATE

public static final int VALIDITY_INVALID_REINSTATE

The record is invalid but should be reinstated if the last transaction to touch it does not complete (used when marking as invalid a record created by a different transaction)

See Also:

Constant Field Values

VALIDITY_INVALID_NOREINSTATE

public static final int VALIDITY_INVALID_NOREINSTATE

The record is invalid and should not be reinstated if the last transaction to touch it does not complete (used when marking as invalid a record created by the same transaction and when loading a deleted record)

See Also:

Constant Field Values

Constructor Detail

FileBackingStore

public FileBackingStore(org.lacibus.backingstore.BackingStoreSourceConnector connector,
                        java.io.File directory,
                        Logger logger)

Construct a new file backingStore

Parameters:

directory - the directory containing the files where the data is stored

Method Detail

getBigFileDirectory

public java.io.File getBigFileDirectory()

Returns:

the directory that contains the files that hold the triple objects that are too large to fit in segments.

printRecordValidity

public java.lang.String printRecordValidity(int validity)

Print the record validity indicator as a descriptive string

Parameters:

validity - a validity indicator

Returns:

a string describing the indicated validity

isBigTripleRecordType

public static boolean isBigTripleRecordType(short type)

Determine whether a record type is the type of a triple record with a big object. (A big object is stored in a file.)

Parameters:

type - a record type

Returns:

whether the given type is the type of a triple record with a big object

initialise

public void initialise(boolean clear)
                throws org.lacibus.backingstore.BackingStoreException

Initialise the store

This method must be invoked before any other after the backingStore has been created

Parameters:

clear - whether the store is to be cleared of all content

Throws:

BackingStoreException

close

public void close()

Close the backing backingStore

getBackingStoreTerminator

public java.lang.Exception getBackingStoreTerminator()

Return an exception that caused backing store operation to abort.

If an exception is thrown in the course of background processing by the backing store then operation of the backing store is aborted and the exception is stored.

Returns:

the Exception that aborted operation

transactionStarted

public void transactionStarted(Transaction t)

Note that a transaction is started

Parameters:

t - a transaction

Throws:

BackingStoreException

transactionComplete

public void transactionComplete(Transaction t)
                         throws org.lacibus.backingstore.BackingStoreException

End a transaction.

All data written by the transaction is stored on disc, and the transaction is noted as completed.

No check is made that the transaction is not already complete. The results of invoking this method twice for the same transaction are indeterminate.

Parameters:

t - a completed transaction

Throws:

BackingStoreException

load

public void load(org.lacibus.backingstore.BackingStoreClient client,
                 TransactionsStatus status)
          throws org.lacibus.backingstore.BackingStoreException

Load the stored items and triples

NOTE that the items are loaded first, because they are referenced by the triples.

Parameters:

client - the client into which the items and triples are to be loaded

status - the transactions that have completed prior to the load operation

Throws:

BackingStoreException

BackingStoreClientException

getHighestLoadedTransactionNr

public long getHighestLoadedTransactionNr()

Returns:

the highest transaction sequence number encountered

addItem

public int addItem(long itemNr,
                   long onlyReadLevelSourceNr,
                   long onlyReadLevelItemNr,
                   long readOrWriteLevelSourceNr,
                   long readOrWriteLevelItemNr,
                   Transaction trans)
            throws org.lacibus.backingstore.BackingStoreException

Add an item

Parameters:

itemNr - the numeric identifier of the item in its source

onlyReadLevelSourceNr - the numeric identifier of the source of the item representing the only-read level

onlyReadLevelItemNr - the numeric identifier in its source of the item representing the only-read level

readOrWriteLevelSourceNr - the numeric identifier of the source of the item representing the read-or-write level

readOrWriteLevelItemNr - the numeric identifier in its source of the item representing the read-or-write level

trans - the transaction of which this operation is part

Returns:

a reference to the item in store

Throws:

BackingStoreException

removeItem

public void removeItem(int storeRef,
                       Transaction trans)
                throws org.lacibus.backingstore.BackingStoreException,
                       org.lacibus.backingstore.BackingStoreClientException

Remove an item from the backingStore

Parameters:

storeRef - the reference to the item in store.

trans - the transaction of which this operation is part

Throws:

BackingStoreException

BackingStoreClientException

addTriple

public org.lacibus.backingstore.RefAndSummary addTriple(long tripleNr,
                                                        long subjectItemNr,
                                                        long verbSourceNr,
                                                        long verbItemNr,
                                                        Datum object,
                                                        Transaction trans)
                                                 throws org.lacibus.backingstore.BackingStoreException,
                                                        TripleStoreNonFatalException

Add a triple

Parameters:

tripleNr - the numeric identifier of the triple in its source

subjectItemNr - the numeric identifier of the subject in its source

verbSourceNr - the numeric identifier of the source of the verb

verbItemNr - the numeric identifier of the verb in its source

object - the triple's object

trans - the transaction of which this operation is part

Returns:

a reference to the triple in store with the object's summary value

Throws:

BackingStoreException

TripleStoreNonFatalException

removeTriple

public void removeTriple(int storeRef,
                         Transaction trans)
                  throws org.lacibus.backingstore.BackingStoreException,
                         org.lacibus.backingstore.BackingStoreClientException

Remove a triple from the backingStore.

Parameters:

storeRef - the reference to the triple in store

trans - the transaction of which this operation is a part

Throws:

BackingStoreException

BackingStoreClientException

getTextTripleObject

public Datum getTextTripleObject(int storeRef)
                          throws org.lacibus.backingstore.BackingStoreException,
                                 org.lacibus.backingstore.BackingStoreClosedException,
                                 TripleStoreNonFatalException

Get a stored text triple's object

Parameters:

storeRef - the reference to the triple in store

Returns:

the triple's object as a StringDatum or a TextFileDatum. This method never returns a TextSourceConnectorDatum

Throws:

BackingStoreException

BackingStoreClosedException

TripleStoreNonFatalException

getBinaryTripleObject

public Datum getBinaryTripleObject(int storeRef)
                            throws org.lacibus.backingstore.BackingStoreException,
                                   TripleStoreNonFatalException

Get a stored binary triple's object

Parameters:

storeRef - the reference to the triple in store

Returns:

the triple's object

Throws:

BackingStoreException

TripleStoreNonFatalException

simulateIoError

public void simulateIoError()

Simulate an I/O error for testing purposes

getItemRecords

public java.util.Map<java.lang.Long,java.util.List<FileBackingStore.ItemSegmentRecord>> getItemRecords()
                                                                                                throws java.lang.Exception

Get the item segment records, grouped by item

Returns:

A map from item numbers to lists of segment records for the numbered items. Used for maintenance and diagnostic purposes.

Throws:

java.lang.Exception

getTripleRecords

public java.util.Map<java.lang.Long,java.util.List<FileBackingStore.TripleSegmentRecord>> getTripleRecords()
                                                                                                    throws java.lang.Exception

Get the triple segment records, grouped by triple

Returns:

A map from triple numbers to lists of segment records for the numbered triples. Used for maintenance and diagnostic purposes.

Throws:

java.lang.Exception

findTransactionRecords

public java.lang.String findTransactionRecords(long firstSeq,
                                               long lastSeq)

Find the records of transactions with sequence numbers in a given range. Used for management and diagnostic purposes.

Parameters:

firstSeq - the first sequence number in the range

lastSeq - the last sequence number in the range

Returns:

a printout of the records of transactions in the range that were found. Note that a transaction may appear in more than one record.

findTripleRecords

public java.lang.String findTripleRecords(long tripleIdNr)

Find the records of actions on a particular triple. Used for management and diagnostic purposes.

Parameters:

tripleNr - the identifying number of the triple

Returns:

a printout of the records of actions on the triple that were found.