1   package eu.fbk.knowledgestore.datastore;
2   
3   import java.io.IOException;
4   import java.util.Set;
5   
6   import com.google.common.collect.ImmutableSet;
7   
8   import org.openrdf.model.URI;
9   
10  import eu.fbk.knowledgestore.runtime.Component;
11  import eu.fbk.knowledgestore.runtime.DataCorruptedException;
12  import eu.fbk.knowledgestore.vocabulary.KS;
13  
14  /**
15   * A persistent storage component for resource, mention, entity, axiom and context records.
16   * <p>
17   * A {@code DataStore} component abstracts the access to a storage system for resources, mentions,
18   * entities and contexts (the types listed in {@link #SUPPORTED_TYPES}). Access to such a storage
19   * system can occur only in the scope of a transaction, which can either be read-only or
20   * read/write, identifies a unit of work and provides atomicity, isolation and durability
21   * guarantees. Note that a {@code DataStore} obeys the general contract and lifecycle of
22   * {@link Component}. In particular, note that a {@code DataStore} must be thread safe, even if
23   * the produced {@code DataTransaction} are not required to be so.
24   * </p>
25   */
26  public interface DataStore extends Component {
27  
28      /** The types of records that can be stored in a {@code DataStore}. */
29      Set<URI> SUPPORTED_TYPES = ImmutableSet.of(KS.RESOURCE, KS.MENTION, KS.ENTITY, KS.CONTEXT);
30  
31      /**
32       * Begins a new read-only / read-write {@code DataStore} transaction. All the accesses to a
33       * {@code DataStore} must occur in the scope of a transaction, that must be ended (possibly
34       * committing the modifications done) as soon as possible to allow improving throughput.
35       * 
36       * @param readOnly
37       *            <tt>true</tt> if the transaction is not allowed to modify the contents of the
38       *            {@code DataStore} (this allows for optimizing accesses).
39       * @return the created transaction
40       * @throws DataCorruptedException
41       *             in case a transaction cannot be started due to the {@code DataStore} persistent
42       *             data being damaged or non-existing (this may trigger some external recovery
43       *             procedure)
44       * @throws IOException
45       *             if another IO error occurs while starting the transaction
46       * @throws IllegalStateException
47       *             if the {@code DataStore} object has been already closed
48       */
49      DataTransaction begin(boolean readOnly) throws DataCorruptedException, IOException,
50              IllegalStateException;
51      
52  }