1   package eu.fbk.knowledgestore;
2   
3   import java.io.Closeable;
4   
5   import javax.annotation.Nullable;
6   
7   import org.openrdf.model.URI;
8   
9   /**
10   * A KnowledgeStore instance.
11   * <p>
12   * This interface represents the entry point of the KnowledgeStore API. Users have to first obtain
13   * an instance of this interface, in a way that depends on whether the KnowledgeStore is running
14   * locally in embedded mode or is accessed via its CRUD and SPARQL endpoints at some base URL
15   * (reported by method {@link #getURL()}). After an instance is obtained, new user sessions can be
16   * created calling methods {@link #newSession()} (for anonymous sessions} or
17   * {@link #newSession(URI, String)} (for authenticated user sessions); the returned
18   * {@link Session} objects allow in turn to issue API calls to the KnowledgeStore. When the
19   * KnowledgeStore instance is no more used, method {@link #close()} should be called to release
20   * the {@code KnowledgeStore} instance and any resource possibly allocated to it.
21   * </p>
22   * <p>
23   * {@code KnowledgeStore} instances are thread safe. Object equality is used for comparing
24   * {@code Store} instances.
25   * </p>
26   */
27  public interface KnowledgeStore extends Closeable {
28  
29      /**
30       * Creates a new anonymous user session. Which operations may be called on the returned
31       * {@code Session} depend on the security settings for anonymous users of the KnowledgeStore
32       * instance.
33       * 
34       * @return the created {@code Session}
35       * @throws IllegalStateException
36       *             in case the {@code KnowledgeStore} instance has been closed
37       */
38      Session newSession() throws IllegalStateException;
39  
40      /**
41       * Creates a new user session, using the optional username and password specified. This method
42       * allows to specify the user the session will be associated to; if the username is null, the
43       * session will be anonymous. Supplying a password is necessary for creating a session on a
44       * remote KS (as user authentication is enforced); it may be optional otherwise. Which
45       * operations may be called on the returned {@code Session} depend on the security settings
46       * for the specific authenticated user of the KnowledgeStore instance.
47       * 
48       * @param username
49       *            the username, possibly null
50       * @param password
51       *            the user password, possibly null
52       * @return the created {@code Session}
53       * @throws IllegalStateException
54       *             in case the {@code KnowledgeStore} instance has been closed
55       */
56      Session newSession(@Nullable String username, @Nullable String password)
57              throws IllegalStateException;
58  
59      /**
60       * Tests whether this {@code KnowledgeStore} instance has been closed.
61       * 
62       * @return true, if this {@code KnowledgeStore} instance has been closed
63       */
64      boolean isClosed();
65  
66      /**
67       * {@inheritDoc} Closes the {@code KnowledgeStore} instance, releasing any resource possibly
68       * allocated. Calling this method additional times has no effect. After this method is called,
69       * calls to other methods of the {@code KnowledgeStore} interface will result in
70       * {@link IllegalStateException}s being thrown.
71       */
72      @Override
73      void close();
74  
75  }