com.endeca.itl.recordstore
Interface RecordStore

public interface RecordStore

Main interface for interacting with a Record Store instance.

Method Summary

void	clean() Cleans records from the Record Store that are not in use by a read operation, that are not part of a generation that has been marked as "last read" by a client, and are beyond the generation retention time.
void	commitTransaction(TransactionId transactionId) Commits all changes made by the given transaction.
void	endRead(ReadCursorId readCursorId) Frees up any resources held by the given read cursor.
RecordStoreConfiguration	getConfiguration(Boolean isNormalized) Returns the configuration of the Record Store.
GenerationId	getLastCommittedGenerationId(TransactionId transactionId) Returns the id of the last committed generation visible to the given transaction.
GenerationId	getLastReadGenerationId(TransactionId transactionId, ClientId clientId) Returns the id of the generation last read by the given client.
GenerationId	getWriteGenerationId(TransactionId transactionId) Returns the id of the generation the given READ_WRITE transaction is writing.
List<TransactionInfo>	listActiveTransactions() Returns information about all active transactions.
List<ClientStateInfo>	listClientStates(TransactionId transactionId) Returns the read states of all clients including the client id and last read generation.
List<GenerationInfo>	listGenerations() Returns a list of generations currently stored in the Record Store.
List<Record>	readRecords(ReadCursorId readCursorId, Integer numRecords) Reads a specified number of records from the read cursor and advances the position of the cursor in the result set.
List<Record>	readRecordsById(TransactionId transactionId, GenerationId generationId, List<RecordId> recordIds) Reads a set of Records corresponding to the given ids in the given generation.
void	rollbackTransaction(TransactionId transactionId) Rolls back the given transaction.
ConfigurationWarnings	setConfiguration(RecordStoreConfiguration config) Sets the configuration of the Record Store and returns any warning from setting the configuration.
void	setLastReadGenerationId(TransactionId transactionId, ClientId clientId, GenerationId generationId) Sets the last read generation for the given client.
ReadCursorId	startBaselineRead(TransactionId transactionId, GenerationId generationId) Starts a baseline read of the given generation.
ReadCursorId	startDeltaRead(TransactionId transactionId, GenerationId startGenerationId, GenerationId endGenerationId) Starts a read of the changes between the given generations.
TransactionId	startTransaction(TransactionType transactionType) Starts a transaction of the given type and returns its id.
int	writeRecords(TransactionId transactionId, List<Record> records) Writes a batch of records to the Record Store in the scope of the given transaction.

Method Detail

getLastReadGenerationId

GenerationId getLastReadGenerationId(TransactionId transactionId,
                                     ClientId clientId)
                                     throws RecordStoreException,
                                            TransactionStateException,
                                            ConcurrentClientStateModificationException,
                                            TransactionNotFoundException

Returns the id of the generation last read by the given client. Returns null if the client has not read any generations. If the last read generation id for the given client has been changed in the given transaction, this will return the uncommitted value.

Parameters:

transactionId - the id of the transaction

clientId - the id of the client

Returns:

the id of the generation last read by the given client

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

ConcurrentClientStateModificationException - if the last read generation of the given client has been modified by a more recent transaction

setLastReadGenerationId

void setLastReadGenerationId(TransactionId transactionId,
                             ClientId clientId,
                             GenerationId generationId)
                             throws RecordStoreException,
                                    TransactionStateException,
                                    ConcurrentClientStateModificationException,
                                    TransactionNotFoundException,
                                    InvalidGenerationException

Sets the last read generation for the given client. This change will not be committed until the given transaction is committed.

Parameters:

transactionId - the id of the transaction

clientId - the id of the client

generationId - the id of the generation last read by the given client or null to clear the last read generation for the given client

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active

ConcurrentClientStateModificationException - if the last read generation of the given client has been modified by a more recent transaction

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

InvalidGenerationException - if the specified generationId refers to a generation that has been cleaned or never existed.

listClientStates

@ResponseWrapper(className="com.endeca.itl.recordstore.ListClientStatesResponse")
List<ClientStateInfo> listClientStates(TransactionId transactionId)
                                       throws RecordStoreException,
                                              TransactionNotFoundException,
                                              TransactionStateException

Returns the read states of all clients including the client id and last read generation.

Parameters:

transactionId - the id of the transaction

Returns:

the read states of all clients.

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

listGenerations

@ResponseWrapper(className="com.endeca.itl.recordstore.ListGenerationsResponse")
List<GenerationInfo> listGenerations()
                                     throws RecordStoreException

Returns a list of generations currently stored in the Record Store. This will not include generations that have been cleaned.

Returns:

a list of generations currently stored in the Record Store

Throws:

RecordStoreException - if there is unexpected error while performing this method.

startBaselineRead

ReadCursorId startBaselineRead(TransactionId transactionId,
                               GenerationId generationId)
                               throws RecordStoreException,
                                      TransactionStateException,
                                      TransactionNotFoundException,
                                      InvalidGenerationException

Starts a baseline read of the given generation. This method returns a ReadCursorId that can be passed to subsequent calls to readRecords() to page through the records. Clients should call endRead() when they are finished with a read cursor to proactively free up Record Store resources. When a transaction is committed or rolled back all open read cursors will automatically be closed.

Parameters:

transactionId - the id of the transaction

generationId - the id of the generation to read from. A null value defaults to the last committed generation visible to the transaction.

Returns:

a ReadCursorId for the read cursor over the baseline records

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

InvalidGenerationException - if the specified generationId refers to a generation that has been cleaned or never existed.

startDeltaRead

ReadCursorId startDeltaRead(TransactionId transactionId,
                            GenerationId startGenerationId,
                            GenerationId endGenerationId)
                            throws RecordStoreException,
                                   TransactionStateException,
                                   TransactionNotFoundException,
                                   InvalidGenerationException

Starts a read of the changes between the given generations. This method returns a ReadCursorId that can be passed to subsequent calls to readRecords() to page through the records. Clients should call endRead() when they are finished with a read cursor to proactively free up Record Store resources. When a transaction is committed or rolled back all open read cursors will automatically be closed.

Parameters:

transactionId - the id of the transaction

startGenerationId - specifies the first generation to consider in the delta read. A null value defaults to the initial empty generation and is equivalent to performing a baseline read of the endGenerationId.

endGenerationId - specifies the last generation to consider in the delta read. A null value defaults to the last committed. generation visible to the transaction

Returns:

a ReadCursorId for the read cursor over the delta records

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

InvalidGenerationException - if the specified startGenerationId or endGenerationId refers to a generation that has been cleaned or never existed.

readRecords

@ResponseWrapper(className="com.endeca.itl.recordstore.ReadRecordsResponse")
List<Record> readRecords(ReadCursorId readCursorId,
                                                  Integer numRecords)
                         throws RecordStoreException,
                                TransactionStateException,
                                ReadCursorNotFoundException,
                                TransactionNotFoundException

Reads a specified number of records from the read cursor and advances the position of the cursor in the result set.

Parameters:

readCursorId - the ReadCursorId returned by either a startBaselineRead() or startDeltaRead() method

numRecords - the number of records to read from the read cursor. The call will return fewer records if a fewer number of records remain in the read cursor.

Returns:

the records read from the read cursor.

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the read cursor is owned by a transaction that is no longer active.

ReadCursorNotFoundException - if the read cursor specified by readCursorId does not exist or has already been closed.

TransactionNotFoundException - if the reader cursor is owned by a transaction that no longer exists.

endRead

void endRead(ReadCursorId readCursorId)
             throws RecordStoreException,
                    TransactionStateException,
                    ReadCursorNotFoundException,
                    TransactionNotFoundException

Frees up any resources held by the given read cursor. This includes releasing locks on the generations being read that will prevent them from being cleaned even if they are beyond the maximum retention time. All read cursors owned by a transaction will be automatically closed when the transaction is committed or rolled back.

Parameters:

readCursorId - the ReadCursorId returned by either a startBaselineRead() or startDeltaRead() method

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the read cursor is owned by a transaction that is no longer active.

ReadCursorNotFoundException - the read cursor specified by readCursorId does not exist or has already been closed.

TransactionNotFoundException - if the reader cursor is owned by a transaction that no longer exists.

readRecordsById

@ResponseWrapper(className="com.endeca.itl.recordstore.ReadRecordsByIdResponse")
List<Record> readRecordsById(TransactionId transactionId,
                                                      GenerationId generationId,
                                                      List<RecordId> recordIds)
                             throws RecordStoreException,
                                    TransactionStateException,
                                    TransactionNotFoundException,
                                    InvalidGenerationException

Reads a set of Records corresponding to the given ids in the given generation. Ids corresponding to records that do not exist will be ignored.

Parameters:

transactionId - the id of the transaction

generationId - the id of the generation to read from. A null value defaults to the last committed generation visible to the transaction.

recordIds - the ids of the records to read

Returns:

the records in the given generation corresponding to the given ids.

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

InvalidGenerationException - if the specified generationId refers to a generation that has been cleaned or never existed.

writeRecords

int writeRecords(TransactionId transactionId,
                 List<Record> records)
                 throws RecordStoreException,
                        TransactionStateException,
                        TransactionNotFoundException,
                        InvalidRecordException,
                        WriteNotAllowedException

Writes a batch of records to the Record Store in the scope of the given transaction. The processing performed on individual records is determined by the record's Endeca.Action property value:

• A missing Endeca.Action value or an Endeca.Action value of UPSERT will update the record if it already exists or insert a new record if it does not exist.
• An Endeca.Action value of DELETE with no other record properties will delete all records. This is typically done at the beginning of a baseline write.
• An Endeca.Action value of DELETE will delete the record specified by the record's id property.

Parameters:

transactionId - the id of the transaction

records - the records to write

Returns:

the number of records actually written this will be less than records.size() if the Record Store is configured to ignore invalid records

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

InvalidRecordException - if a record has an invalid value for Endeca.Action or if the record has an Endeca.Action of UPSERT but no id property. This exception will not be thrown if the Record Store is configured to ignore invalid records.

WriteNotAllowedException - if the specified transaction is not a READ_WRITE transaction

getLastCommittedGenerationId

GenerationId getLastCommittedGenerationId(TransactionId transactionId)
                                          throws RecordStoreException,
                                                 TransactionStateException,
                                                 TransactionNotFoundException

Returns the id of the last committed generation visible to the given transaction. Generations created after the transaction was started will not be visible in the scope of the transaction.

Parameters:

transactionId - the id of the transaction

Returns:

the last committed generation visible to the given transaction

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

getWriteGenerationId

GenerationId getWriteGenerationId(TransactionId transactionId)
                                  throws RecordStoreException,
                                         TransactionStateException,
                                         TransactionNotFoundException,
                                         WriteNotAllowedException

Returns the id of the generation the given READ_WRITE transaction is writing.

Parameters:

transactionId - the id of the READ_WRITE transaction

Returns:

the id of the generation the given READ_WRITE transaction is writing.

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

WriteNotAllowedException - if the specified transaction is not a READ_WRITE transaction

startTransaction

TransactionId startTransaction(TransactionType transactionType)
                               throws RecordStoreException,
                                      ConcurrentWriteException

Starts a transaction of the given type and returns its id. Concurrent READ_WRITE transactions are not allowed by the Record Store.

Parameters:

transactionType -

Returns:

the id of the transaction that was started

Throws:

RecordStoreException - if there is unexpected error while performing this method.

ConcurrentWriteException - if starting a READ_WRITE transaction and there is already an active READ_WRITE transaction

commitTransaction

void commitTransaction(TransactionId transactionId)
                       throws RecordStoreException,
                              TransactionStateException,
                              TransactionNotFoundException

Commits all changes made by the given transaction. This includes changes to records and client read state.

Parameters:

transactionId - the id of the transaction to commit

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

rollbackTransaction

void rollbackTransaction(TransactionId transactionId)
                         throws RecordStoreException,
                                TransactionStateException,
                                TransactionNotFoundException

Rolls back the given transaction. All changes made by the transaction will be reverted including changes to records and client read state.

Parameters:

transactionId - the id of the transaction to rollback

Throws:

RecordStoreException - if there is unexpected error while performing this method.

TransactionStateException - if the specified transactionId refers to a transaction that is no longer active.

TransactionNotFoundException - if a transaction corresponding to the specified transactionId does not exist.

listActiveTransactions

@ResponseWrapper(className="com.endeca.itl.recordstore.ListActiveTransactionsResponse")
List<TransactionInfo> listActiveTransactions()
                                             throws RecordStoreException

Returns information about all active transactions.

Returns:

information about all active transactions.

Throws:

RecordStoreException - if there is unexpected error while performing this method.

setConfiguration

ConfigurationWarnings setConfiguration(RecordStoreConfiguration config)
                                       throws RecordStoreException,
                                              RecordStoreConfigurationException

Sets the configuration of the Record Store and returns any warning from setting the configuration. Changes to any of the following Record Store configuration settings will clear all records from the Record Store:

• btreePageSize
• changePropertyNames
• idPropertyName
• jdbmSettings
• recordCompressionEnabled

Parameters:

config - the configuration of the Record Store

Returns:

any warnings caused by setting the Record Store configuration

Throws:

RecordStoreException - if there is unexpected error while performing this method.

RecordStoreConfigurationException - if the configuration is invalid

getConfiguration

RecordStoreConfiguration getConfiguration(Boolean isNormalized)

Returns the configuration of the Record Store.

Parameters:

isNormalized - if true, the returned configuration will have defaults filled in and relative paths converted to absolute paths. A null value defaults to false.

Returns:

the configuration of the Record Store.

clean

void clean()
           throws RecordStoreException

Cleans records from the Record Store that are not in use by a read operation, that are not part of a generation that has been marked as "last read" by a client, and are beyond the generation retention time. Cleans will be automatically performed according the Record Store's cleaner interval configuration setting. A cleaner interval of 0 disables automatic cleaning.

Throws:

RecordStoreException - if there is unexpected error while performing this method.