eu.fbk.knowledgestore.Session Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ks-core Show documentation

The Core module (ks-core) contains core abstractions and basic functionalities shared by the KnowledgeStore Frontend Server and the Java Client. It also defines the Java version of the KnowledgeStore API.

There is a newer version: 1.7.1

Show newest version

package eu.fbk.knowledgestore;

import java.io.Closeable;
import java.util.Map;

import javax.annotation.Nullable;

import org.openrdf.model.URI;

import eu.fbk.knowledgestore.Operation.Count;
import eu.fbk.knowledgestore.Operation.Create;
import eu.fbk.knowledgestore.Operation.Delete;
import eu.fbk.knowledgestore.Operation.Download;
import eu.fbk.knowledgestore.Operation.Match;
import eu.fbk.knowledgestore.Operation.Merge;
import eu.fbk.knowledgestore.Operation.Retrieve;
import eu.fbk.knowledgestore.Operation.Sparql;
import eu.fbk.knowledgestore.Operation.Update;
import eu.fbk.knowledgestore.Operation.Upload;
import eu.fbk.knowledgestore.data.Criteria;
import eu.fbk.knowledgestore.data.Data;
import eu.fbk.knowledgestore.data.XPath;
import eu.fbk.knowledgestore.vocabulary.KS;

/**
 * A KnowledgeStore user session.
 * 
 * Interaction with the KnowledgeStore through its Java API occurs within a {@code Session}, which
 * encapsulates user-specific configuration and, if authenticated, user credentials. A
 * {@code Session} can be obtained via {@link KnowledgeStore#newSession()} (for anonymous user) or
 * {@link KnowledgeStore#newSession(URI, String)} (authenticated user) and must be released with
 * {@link #close()} to freed resources possibly allocated to the session.
 * 
 * 
 * The identifier of the session's user, if any, is provided by method {@link #getUser()}, while
 * the configured password is available using {@link #getPassword()}. Method
 * {@link #getNamespaces()} returns a session-specific, modifiable prefix-to-namespace map that
 * can be used for interacting with the KnowledgeStore; this map is initially filled with mappings
 * from {@link Data#getNamespaceMap()}. Namespace mappings play a relevant role in the interaction
 * with the KnowledgeStore, as they are used for encoding and decoding {@link XPath} expressions,
 * merge {@link Criteria}s and SPARQL queries.
 * 
 * 
 * Operations of the KnowledgeStore API can be invoked starting from a {@code Session} object and
 * using operation objects. Every operation has its own {@link Operation} sub-class, an
 * instance of which can be obtained by calling a method in {@code Session}; after an operation
 * object is created, a number of common and operation-specific parameters can be set on this
 * object to specify and control the execution of the operation, which is triggered by calling one
 * of the {@code exec()} / {@code execXXX()} methods on the operation objects. More in details,
 * the API operations in the following table are offered:
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * 
 * {@code Session} method {@code Operation} sub-class Type Endpoint Description
{@link #download()} {@link Download} read-only CRUD Downloads one or more resource representations.
{@link #upload()} {@link Upload} read-write CRUD Uploads one or more resource representations.
{@link #count(URI)} {@link Count} read-only CRUD Count the number of resources / mentions / entities / axioms that match an optional
 * condition.
{@link #retrieve(URI)} {@link Retrieve} read-only CRUD Retrieves selected properties of resources / mentions / entities / axioms that match an
 * optional condition
{@link #create(URI)} {@link Create} read-write CRUD Creates one or more new resources / mentions / entities / axioms.
{@link #merge(URI)} {@link Merge} read-write CRUD Merges local record descriptions of resources / mentions / entities / axioms with
 * descriptions stored in the KnowledgeStore, applying supplied merge criteria.
{@link #update(URI)} {@link Update} read-write CRUD Updates one or more properties of all the resources / mentions / entities / axioms that
 * match an optional condition.
{@link #delete(URI)} {@link Delete} read-write CRUD Deletes all the resources / mentions / entities / axioms matching an optional condition.
{@link #match()} {@link Match} read-only CRUD Returns all the <resource, mention, entity, axioms> combinations matching optional
 * condition where the mention refers to the resource and entity and the axioms have been
 * extracted from the mention.
{@link #sparql(String, Object...)} {@link Sparql} read-only SPARQL Evaluates a SPARQL select / construct / describe / ask query on crystallized axiom data.
 * 
 * 
 * Note that operation marked as read-write may be forbidden to anonymous or non-privileged users,
 * based on the security configuration of the KnowledgeStore. {@code Session} objects are thread
 * safe. Object equality is used for comparing {@code Session} instances.
 * 
 */
public interface Session extends Closeable {

    /**
     * Returns the username associated to this {@code Session}, if any.
     * 
     * @return the username, null if the {@code Session} is anonymous
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    @Nullable
    String getUsername() throws IllegalStateException;

    /**
     * Returns the user password, if any.
     * 
     * @return the password
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    @Nullable
    String getPassword() throws IllegalStateException;

    /**
     * Returns the modifiable namespace map of this {@code Session}. The map is backed by the
     * default mappings of {@code Data#getNamespaceMap()}. New mappings are stored in the
     * {@code Session} map and may override the default mappings. Removal of mappings is performed
     * on the {@code Session} map, and may reactivate the default mapping as a consequence.
     * 
     * @return the modifiable namespace map of this {@code Session}
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Map getNamespaces() throws IllegalStateException;

    /**
     * Creates a new {@code Download} operation object.
     * 
     * @param resourceID
     *            the ID of the resource whose representation should be downloaded
     * @return the created {@code Download} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Download download(URI resourceID) throws IllegalStateException;

    /**
     * Creates a new {@code Upload} operation object.
     * 
     * @param resourceID
     *            the ID of the resource whose representation should be updated
     * @return the created {@code Upload} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Upload upload(URI resourceID) throws IllegalStateException;

    /**
     * Creates a new {@code Count} operation object for counting records of the type specified.
     * 
     * @param type
     *            the URI of the type of record to count, either {@link KS#RESOURCE},
     *            {@link KS#MENTION}, {@link KS#ENTITY} or {@link KS#AXIOM}
     * @return the created {@code Count} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Count count(URI type) throws IllegalStateException;

    /**
     * Creates a new {@code Retrieve} operation object for retrieving records of the type
     * specified.
     * 
     * @param type
     *            the URI of the type of record to retrieve, either {@link KS#RESOURCE},
     *            {@link KS#MENTION}, {@link KS#ENTITY} or {@link KS#AXIOM}
     * @return the created {@code Retrieve} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Retrieve retrieve(URI type) throws IllegalStateException;

    /**
     * Creates a new {@code Create} operation object for storing new records of the type
     * specified.
     * 
     * @param type
     *            the URI of the type of record to create, either {@link KS#RESOURCE},
     *            {@link KS#MENTION}, {@link KS#ENTITY} or {@link KS#AXIOM}
     * @return the created {@code Create} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Create create(URI type) throws IllegalStateException;

    /**
     * Creates a new {@code Merge} operation object for merging local record description of the
     * type specified with descriptions stored in the KnowledgeStore.
     * 
     * @param type
     *            the URI of the type of record to merge, either {@link KS#RESOURCE},
     *            {@link KS#MENTION}, {@link KS#ENTITY} or {@link KS#AXIOM}
     * @return the created {@code Merge} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Merge merge(URI type) throws IllegalStateException;

    /**
     * Creates a new {@code Update} operation object for updating one or more properties of
     * records of the type specified.
     * 
     * @param type
     *            the URI of the type of record to update, either {@link KS#RESOURCE},
     *            {@link KS#MENTION}, {@link KS#ENTITY} or {@link KS#AXIOM}
     * @return the created {@code Update} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Update update(URI type) throws IllegalStateException;

    /**
     * Creates a new {@code Delete} operation object for deleting records of the type specified.
     * 
     * @param type
     *            the URI of the type of record to delete, either {@link KS#RESOURCE},
     *            {@link KS#MENTION}, {@link KS#ENTITY} or {@link KS#AXIOM}
     * @return the created {@code Delete} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Delete delete(URI type) throws IllegalStateException;

    /**
     * Creates a new {@code Match} operation object for matching <resource, mention, entity,
     * axioms> 4-tuples matching specific conditions.
     * 
     * @return the created {@code Match} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Match match() throws IllegalStateException;

    /**
     * Creates a new {@code Sparql} operation object for evaluating a SPARQL query on crystallized
     * axiom data.
     * 
     * @param expression
     *            the SPARQL query expression, not null
     * @param arguments
     *            arguments to be injected in {@code $$} placeholders in the query expression; can
     *            be {@code URI}s, {@code Literal}s or scalar values that can be converted to
     *            {@code Literal}s (e.g., strings, integers)
     * @return the created {@code Sparql} operation object
     * @throws IllegalStateException
     *             if the {@code Session} has been closed
     */
    Sparql sparql(String expression, Object... arguments) throws IllegalStateException;

    /**
     * Tests whether this {@code Session} instance has been closed.
     * 
     * @return true, if this {@code Session} instance has been closed
     */
    boolean isClosed();

    /**
     * {@inheritDoc} Closes the {@code Session} instance, releasing any resource possibly
     * allocated. Calling this method additional times has no effect. After this method is called,
     * calls to other method of the {@code Session} interface will result in
     * {@link IllegalStateException}s to be thrown.
     */
    @Override
    void close();

}

{@code Session} method	{@code Operation} sub-class	Type	Endpoint	Description
{@link #download()}	{@link Download}	read-only	CRUD	Downloads one or more resource representations.
{@link #upload()}	{@link Upload}	read-write	CRUD	Uploads one or more resource representations.
{@link #count(URI)}	{@link Count}	read-only	CRUD	Count the number of resources / mentions / entities / axioms that match an optional * condition.
{@link #retrieve(URI)}	{@link Retrieve}	read-only	CRUD	Retrieves selected properties of resources / mentions / entities / axioms that match an * optional condition
{@link #create(URI)}	{@link Create}	read-write	CRUD	Creates one or more new resources / mentions / entities / axioms.
{@link #merge(URI)}	{@link Merge}	read-write	CRUD	Merges local record descriptions of resources / mentions / entities / axioms with * descriptions stored in the KnowledgeStore, applying supplied merge criteria.
{@link #update(URI)}	{@link Update}	read-write	CRUD	Updates one or more properties of all the resources / mentions / entities / axioms that * match an optional condition.
{@link #delete(URI)}	{@link Delete}	read-write	CRUD	Deletes all the resources / mentions / entities / axioms matching an optional condition.
{@link #match()}	{@link Match}	read-only	CRUD	Returns all the <resource, mention, entity, axioms> combinations matching optional * condition where the mention refers to the resource and entity and the axioms have been * extracted from the mention.
{@link #sparql(String, Object...)}	{@link Sparql}	read-only	SPARQL	Evaluates a SPARQL select / construct / describe / ask query on crystallized axiom data.