eu.fbk.knowledgestore.datastore

Interface DataTransaction

All Known Implementing Classes:

DataTransactionElastic, ForwardingDataTransaction, HBaseDataTransaction, MySQLDataStore.MySQLTransaction, SolrDataStore.SolrTransaction

public interface DataTransaction

A DataStore transaction.

A DataTransaction is a unit of work over the contents of a DataStore that provides atomicity (i.e., changes are either completely stored or discarded), isolation (i.e., other transaction do not see the modifications of this transaction) and durability (i.e., changes are persisted across different program runs) guarantees.

A DataTransaction supports the following features:

• Lookup of records by ID, via method lookup(URI, Set, Set);
• Matching of records based on type and optional condition, consisting either in the retrieval of (selected properties of) matching records (method retrieve(URI, XPath, Set)) or of their count (method count(URI, XPath));
• Matching of record combinations (method match(Map, Map, Map));
• Storing and deletion of single records (methods store(URI, Record), delete(URI, URI)).

Note that the latter modification methods are not available for read-only transactions (an IllegalStateException is thrown in that case); moreover, they can return to the caller even if the operation has not yet completed (e.g., due to buffering), in which case it is however guaranteed that following read operation will be able to see newly written data. For all methods accepting a type URI parameter, that parameter can only be one of the supported record types listed in DataStore.SUPPORTED_TYPES.

Transactions are terminated via end(boolean), whose parameter specifies whether changes should be committed or not (this doesn't matter for read-only transactions). Method end() has always the effect of terminating the transaction: if it throws an exception a rollback must be assumed, even if a commit was asked. In case the JVM is abruptly shutdown during a transaction, the effects of the transaction should be the same as if a rollback was performed. As a particular case of IOException, method end() may throw a DataCorruptedException in case neither a commit or rollback were possible and the DataStore is left in some unpredictable state with no possibility of automatic recovery.

DataTransaction objects are not required to be thread safe. Access by at most one thread at a time is guaranteed externally. However, it must be allowed for operations to be issued while streams from previous operations are still open; if a stream is open and a write operations is performed that affects one of the objects still to be returned by the stream (or made an object returnable/not returnable by the stream), then it is allowed for the stream both to return the previous state of the object or to return the new state.

Method Summary

Modifier and Type	Method and Description
long	count(org.openrdf.model.URI type, XPath condition) Counts the records having the type and matching the optional condition specified.
void	delete(org.openrdf.model.URI type, org.openrdf.model.URI id) Deletes the record stored in the DataStore with the ID specified.A record may or may not be stored for the specified ID; in case it exists, it is deleted by the operation.
void	end(boolean commit) Ends the transaction, either committing or rolling back its changes (if any).
Stream<Record>	lookup(org.openrdf.model.URI type, Set<? extends org.openrdf.model.URI> ids, Set<? extends org.openrdf.model.URI> properties) Returns a stream of records having the type and IDs specified.
Stream<Record>	match(Map<org.openrdf.model.URI,XPath> conditions, Map<org.openrdf.model.URI,Set<org.openrdf.model.URI>> ids, Map<org.openrdf.model.URI,Set<org.openrdf.model.URI>> properties) Evaluates a match request with the parameters supplied.
Stream<Record>	retrieve(org.openrdf.model.URI type, XPath condition, Set<? extends org.openrdf.model.URI> properties) Returns a stream of records having the type and matching the optional condition specified.
void	store(org.openrdf.model.URI type, Record record) Stores a record in the DataStore.

Method Detail

lookup

Stream<Record> lookup(org.openrdf.model.URI type,
                      Set<? extends org.openrdf.model.URI> ids,
                      @Nullable
                      Set<? extends org.openrdf.model.URI> properties)
               throws IOException,
                      IllegalArgumentException,
                      IllegalStateException

Returns a stream of records having the type and IDs specified.

Parameters:

type - the URI of the type of records to return

ids - a set with the IDs of the records to return, not to be modified by the method

properties - a set with the properties to return for matching records, not modified by the method; if null, all the available properties must be returned

Returns:

a stream with the records matching the IDs and type specified, possibly empty and in no particular order

Throws:

IOException - in case some IO error occurs

IllegalArgumentException - in case the type specified is not supported

IllegalStateException - if the DataTransaction has been already ended

retrieve

Stream<Record> retrieve(org.openrdf.model.URI type,
                        @Nullable
                        XPath condition,
                        @Nullable
                        Set<? extends org.openrdf.model.URI> properties)
                 throws IOException,
                        IllegalArgumentException,
                        IllegalStateException

Returns a stream of records having the type and matching the optional condition specified.

Parameters:

type - the URI of the type of records to return

condition - an optional condition to be satisfied by matching records; if null, no condition must be checked

properties - a set with the properties to return for matching records, not modified by the method; if null, all the available properties must be returned

Returns:

a stream over the records matching the condition and type specified, possibly empty and in no particular order

Throws:

IOException - in case some IO error occurs

IllegalArgumentException - in case the type specified is not supported

IllegalStateException - if the DataTransaction has been already ended

count

long count(org.openrdf.model.URI type,
           @Nullable
           XPath condition)
    throws IOException,
           IllegalArgumentException,
           IllegalStateException

Counts the records having the type and matching the optional condition specified. This method performs similarly to retrieve(URI, XPath, Set), but returns only the number of matching instances instead of retrieving the corresponding Record objects.

Parameters:

type - the URI of the type of records to return

condition - an optional condition to be satisfied by matching records; if null, no condition must be checked

Returns:

the number of records matching the optional condition and type specified

Throws:

IOException - in case some IO error occurs

IllegalArgumentException - in case the type specified is not supported

IllegalStateException - if the DataTransaction has been already ended

match

Stream<Record> match(Map<org.openrdf.model.URI,XPath> conditions,
                     Map<org.openrdf.model.URI,Set<org.openrdf.model.URI>> ids,
                     Map<org.openrdf.model.URI,Set<org.openrdf.model.URI>> properties)
              throws IOException,
                     IllegalStateException

Evaluates a match request with the parameters supplied. The operation:

1. Considers all the combinations <resource, mention, entity, axiom> such that
   • mention KS.MENTION_OF resource;
   • mention KS.REFERS_TO entity (optional if no condition or projection on entities);
   • mention KS.EXPRESSES axiom (optional if no condition or projection on axioms).
2. Filters the combinations so that optional conditions / ids selections on resource, mention, entity and axiom components are satisfied.
3. Perform projection with duplicate removal of filtered combinations, keeping only the components occurring in properties.keySet(), returning for each component the subset of properties of properties.get(component_type_URI).

In the maps supplied as parameters, components are identified by their type URI, that is KS.RESOURCE, KS.MENTION, KS.ENTITY and KS.AXIOM.

Parameters:

conditions - a non-null map with optional component conditions, indexed by the component type URI; note the map may be possibly empty or contain conditions only for a subset of components

ids - a non-null map with optional ID selections for different components, indexed by the component type URI; note the map may be possibly empty or contain selections only for a subset of components

properties - a non-null, non-empty map with the properties to return for different components, indexed by the component type URI; if the set of property URIs mapped to a component is null or empty, then all the properties of the component should be returned; if a component is not referenced in the map, then it must not be returned

Returns:

a Stream of combination records

Throws:

IOException - in case some IO error occurs

IllegalStateException - if the DataTransaction has been already ended

store

void store(org.openrdf.model.URI type,
           Record record)
    throws IOException,
           IllegalStateException

Stores a record in the DataStore. A record may or may not exist for the same ID; in case it exists, it is replaced by the newly specified record. In case the method call returns successfully, there is no guarantee that the write operation completed (e.g., because of internal buffering); however, it is guaranteed (e.g., via internal flushing) that read operations called subsequently will see the result of the modification. In case the method call fails with an IOException, there is no guarantee that the DataStore is left in the same state it was at the time of calling.

Parameters:

type - the URI of the type of record to store, not null

record - the record to store, not null

Throws:

IOException - in case the operation failed, with no guarantee that the DataStore is left in the same state if was when the method was called; note that this exception may trigger a rollback on the caller side

IllegalStateException - if the DataTransaction has been already ended, or if it is read-only

delete

void delete(org.openrdf.model.URI type,
            org.openrdf.model.URI id)
     throws IOException,
            IllegalStateException

Deletes the record stored in the DataStore with the ID specified.A record may or may not be stored for the specified ID; in case it exists, it is deleted by the operation. In case the method call returns successfully, there is no guarantee that the write operation completed (e.g., because of internal buffering); however, it is guaranteed (e.g., via internal flushing) that read operations called subsequently will see the result of the modification. In case the method call fails with an IOException, there is no guarantee that the DataStore is left in the same state it was at the time of calling.

Parameters:

type - the URI of the type of record to store, not null

id - the ID of the record to delete, not null

Throws:

IOException - in case the operation failed, with no guarantee that the DataStore is left in the same state if was when the method was called; note that this exception may trigger a rollback on the caller side

IllegalStateException - if the DataTransaction has been already ended, or if it is read-only

end

void end(boolean commit)
  throws DataCorruptedException,
         IOException,
         IllegalStateException

Ends the transaction, either committing or rolling back its changes (if any). This method always tries to terminate the transaction: if commit is requested but fails, a rollback is forced by the method and an IOException is thrown. If it is not possible either to commit or rollback, then the DataStore is possibly left in an unknown state and a DataCorruptedException is thrown to signal a data corruption situation that cannot be automatically recovered.

Parameters:

commit - true in case changes made by the transaction should be committed

Throws:

IOException - in case some IO error occurs or the commit request cannot be satisfied for any reason; it is however guaranteed that a forced rollback has been performed

DataCorruptedException - in case it was not possible either to commit or rollback, which implies the state of the DataStore is unknown and automatic recovery is not possible (hence, data is corrupted)

IllegalStateException - if the DataTransaction has been already ended