com.indexdata.torus2.rw

Interface RealmReaderWriter

All Known Implementing Classes:

CachingReaderWriter, ProxyReaderWriter, RealmFileRW

public interface RealmReaderWriter

Represents low-level realm data access. General contract for this interface requires that a call to either 'open' or 'create' is made BEFORE any data access is attempted. Failure to fulfill this contract may result in an IllegalStateException being thrown during subsequent operations, but in practice may differ for specific implementations.

Author:

jakub

Method Summary

Modifier and Type	Method and Description
boolean	create(RealmDefinition rd) Creates a new new realm store.
void	deleteCachedAsOriginal(String id)
void	deleteMasterRecord(String id)
void	deleteOverrideRecord(String id)
void	deleteParentRealm(String prId)
void	deleteWorldRecordsByParentId(String prId)
RealmDefinition	describe() Retrieves RealmDefinition for the given realm.
void	destroy() Destroys the underlying record store;
boolean	isCachedAsParent() In case the realm serves as parent to other realms within the same torus installation, the following function allows for fast propagation of changes to child realms.
List<RealmDefinition>	listRealms() List all realms available within the torus.
boolean	open() Attempts to open the realm store pointed to by this instance.
Record.Layer	readMasterRecord(String id)
List<Record.Layer>	readMasterRecords()
Record.Layer	readOverrideRecord(String id) Retrieve override record by id.
List<Record.Layer>	readOverrideRecords() Retrieve a list of override records within this realm, the query parameter is used ONLY to early filter out false matches, that is records that CONTAIN a given query field but the value DOES NOT match.
ParentRealm	readParentRealm(String prId)
List<ParentRealm>	readParentRealms()
Record.Layer	readWorldRecord(String realmUniqueId) Retrieve world (within a set of parents) record by id.
Pair<List<Record.Layer>,Date>	readWorldRecordsForParent(String prId) Retrieve a time-stamped list of records for a parent specified within this realm,
boolean	update(RealmDefinition rd) Updates realm meta-data.
Record.Layer	updateCachedAsOriginal(Record.Layer original)
Record.Layer	writeMasterRecord(Record.Layer record)
Record.Layer	writeMasterRecord(String id, Record.Layer record)
Record.Layer	writeOverrideRecord(Record.Layer over) The method is to write new record to the record store.
Record.Layer	writeOverrideRecord(String id, Record.Layer over) Write data to the existing record.
ParentRealm	writeParentRealm(ParentRealm pr)
ParentRealm	writeParentRealm(String prId, ParentRealm pr)
List<Record.Layer>	writeWorldRecordsForParent(List<Record.Layer> recs, String prId) Stores parent records for the given parent, updates each world record with an ID unique to this realm (so world records can be looked up without specifying parent)
List<Record.Layer>	writeWorldRecordsForParent(List<Record.Layer> recs, String prId, Date timestamp)

Method Detail

create

boolean create(RealmDefinition rd)
        throws InternalIOException

Creates a new new realm store. Returns true if the realm store has been properly created or false if the realm store already exists.

Throws:

InternalIOException - when creation failed

open

boolean open()
      throws InternalIOException

Attempts to open the realm store pointed to by this instance. Returns true if the realm has been properly opened or false if the realm has already been opened (e.g on consecutive calls)

Returns:

Throws:

InternalIOException

update

boolean update(RealmDefinition rd)
        throws InternalIOException

Updates realm meta-data. Returns false when the realm does not exist.

Returns:

Throws:

InternalIOException

describe

RealmDefinition describe()

Retrieves RealmDefinition for the given realm.

Returns:

Throws:

InternalIOException

destroy

void destroy()
      throws InternalIOException

Destroys the underlying record store;

Throws:

InternalIOException

readOverrideRecords

List<Record.Layer> readOverrideRecords()
                                throws InternalIOException

Retrieve a list of override records within this realm, the query parameter is used ONLY to early filter out false matches, that is records that CONTAIN a given query field but the value DOES NOT match.

Parameters:

query - early filtering query, can be null

Returns:

list (possibly empty e.g when realm contains no records) of records

Throws:

InternalIOException - when experiencing problems reading/parsing records

NotFoundException - when records are missing RATHER than returning 'null'

readOverrideRecord

Record.Layer readOverrideRecord(String id)
                         throws InternalIOException

Retrieve override record by id.

Parameters:

id - override record id

Returns:

found record

Throws:

InternalIOException - when experiencing problems reading/parsing records

NotFoundException - when record is missing RATHER than returning 'null'

writeOverrideRecord

Record.Layer writeOverrideRecord(String id,
                                 Record.Layer over)
                          throws InternalIOException

Write data to the existing record. This method does not merge anything, it simply override the existing record.

Parameters:

id - id of the records

doc - new contents for the record

Returns:

written contents doc, possibly with additional fields

Throws:

InternalIOException

writeOverrideRecord

Record.Layer writeOverrideRecord(Record.Layer over)
                          throws InternalIOException

The method is to write new record to the record store.

Parameters:

doc - contents of the record to write

Returns:

written contents doc, with additional fields (e.g id)

Throws:

InternalIOException

deleteOverrideRecord

void deleteOverrideRecord(String id)
                   throws InternalIOException

Throws:

InternalIOException

readWorldRecordsForParent

Pair<List<Record.Layer>,Date> readWorldRecordsForParent(String prId)
                                                 throws InternalIOException

Retrieve a time-stamped list of records for a parent specified within this realm,

Returns:

list (possibly empty, e.g when world contains no records) of records

Throws:

InternalIOException - when experiencing problems reading/parsing records

NotFoundException - when records are missing RATHER than returning 'null'

readWorldRecord

Record.Layer readWorldRecord(String realmUniqueId)
                      throws InternalIOException,
                             MalformedInputException

Retrieve world (within a set of parents) record by id.

Parameters:

id - override record id

Returns:

found record

Throws:

InternalIOException - when experiencing problems reading/parsing records

NotFoundException - when record is missing RATHER than returning 'null'

MalformedInputException - when the realmUniqueId is malformed

writeWorldRecordsForParent

List<Record.Layer> writeWorldRecordsForParent(List<Record.Layer> recs,
                                              String prId)
                                       throws InternalIOException

Stores parent records for the given parent, updates each world record with an ID unique to this realm (so world records can be looked up without specifying parent)

Parameters:

recs -

prId -

Returns:

Throws:

InternalIOException

writeWorldRecordsForParent

List<Record.Layer> writeWorldRecordsForParent(List<Record.Layer> recs,
                                              String prId,
                                              Date timestamp)
                                       throws InternalIOException

Throws:

InternalIOException

deleteWorldRecordsByParentId

void deleteWorldRecordsByParentId(String prId)
                           throws InternalIOException

Throws:

InternalIOException

readParentRealm

ParentRealm readParentRealm(String prId)
                     throws InternalIOException

Throws:

InternalIOException

writeParentRealm

ParentRealm writeParentRealm(String prId,
                             ParentRealm pr)
                      throws InternalIOException

Throws:

InternalIOException

writeParentRealm

ParentRealm writeParentRealm(ParentRealm pr)
                      throws InternalIOException

Throws:

InternalIOException

deleteParentRealm

void deleteParentRealm(String prId)
                throws InternalIOException

Throws:

InternalIOException

readParentRealms

List<ParentRealm> readParentRealms()
                            throws InternalIOException

Throws:

InternalIOException

listRealms

List<RealmDefinition> listRealms()
                          throws InternalIOException

List all realms available within the torus. This method feels welted on here, but introducing tree hierarchy would complicate third-party implementations.

Returns:

Throws:

InternalIOException

isCachedAsParent

boolean isCachedAsParent()
                  throws InternalIOException

In case the realm serves as parent to other realms within the same torus installation, the following function allows for fast propagation of changes to child realms.

Throws:

InternalIOException

updateCachedAsOriginal

Record.Layer updateCachedAsOriginal(Record.Layer original)
                             throws InternalIOException

Throws:

InternalIOException

deleteCachedAsOriginal

void deleteCachedAsOriginal(String id)
                     throws InternalIOException

Throws:

InternalIOException

readMasterRecord

Record.Layer readMasterRecord(String id)
                       throws InternalIOException

Throws:

InternalIOException

writeMasterRecord

Record.Layer writeMasterRecord(String id,
                               Record.Layer record)
                        throws InternalIOException

Throws:

InternalIOException

writeMasterRecord

Record.Layer writeMasterRecord(Record.Layer record)
                        throws InternalIOException

Throws:

InternalIOException

readMasterRecords

List<Record.Layer> readMasterRecords()
                              throws InternalIOException

Throws:

InternalIOException

deleteMasterRecord

void deleteMasterRecord(String id)
                 throws InternalIOException

Throws:

InternalIOException