1   package eu.fbk.knowledgestore.triplestore;
2   
3   import java.io.IOException;
4   
5   import eu.fbk.knowledgestore.runtime.Component;
6   import eu.fbk.knowledgestore.runtime.DataCorruptedException;
7   
8   /**
9    * A storage for triples, supporting named graphs, SPARQL queries, inference and transactions.
10   * <p>
11   * A <tt>TripleStore</tt> object abstracts the access to a triple store service, which efficiently
12   * stores a bunch of triples organized in named graphs, providing support for inference of derived
13   * triples, SPARQL queries and transactions. Access to those functionalities and to a
14   * <tt>TripleStore</tt> contents can occur only in the scope of a transaction, which can either be
15   * read-only or read/write, identifies a unit of work and provides atomicity, isolation and
16   * durability guarantees. Note that a {@code TripleStore} obeys the general contract and lifecycle
17   * of {@link Component}.
18   * </p>
19   * <p>
20   * As a special kind of <tt>IOException</tt>, implementations of this interface may throw a
21   * {@link DataCorruptedException} in case a data corruption situation is detected, caused either
22   * by any or all of the triple store files / external resources being non-existent or corrupted
23   * for whatever reason. Throwing a <tt>DataCorruptedException</tt> when such a situation is
24   * detected is important, as it allows external code to attempt a recovery procedure by calling
25   * the {@link #reset()} function, which allows wiping out the content of the triple store, that
26   * can then be re-populated again.
27   * </p>
28   */
29  public interface TripleStore extends Component {
30  
31      /**
32       * Begins a new read-only / read-write triple store transaction. All the accesses to a triple
33       * store must occur in the scope of a transaction, that must be ended (possibly committing the
34       * 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       *            triple store (this allows for optimizing the access to the triple store).
39       * @return the created transaction
40       * @throws DataCorruptedException
41       *             in case a transaction cannot be started due to triple store files being damaged
42       *             or non-existing; a {@link #reset()} call followed by a full triple store
43       *             re-population should be attempted to recover this situation
44       * @throws IOException
45       *             if another IO error occurs while starting the transaction, not implying a data
46       *             corruption situation
47       */
48      TripleTransaction begin(boolean readOnly) throws DataCorruptedException, IOException;
49  
50      /**
51       * Resets the triple store contents, possibly recreating or reinitializing the external
52       * services / files this triple store is based on. This method is expected to be called either
53       * to initialize the triple store if it does not exist, or to recover a data corruption
54       * situation. On success, the triple store is left in an empty status. It is a task of the
55       * user code to re-populate it, if necessary.
56       * 
57       * @throws IOException
58       *             if an IO error occurs while resetting the triple store (this situation is not
59       *             expected to be recovered automatically via code).
60       */
61      void reset() throws IOException;
62  
63  }