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.

The newest version!

package eu.fbk.knowledgestore;

import eu.fbk.knowledgestore.Operation.*;
import eu.fbk.knowledgestore.data.Criteria;
import eu.fbk.knowledgestore.data.Data;
import eu.fbk.knowledgestore.data.XPath;
import eu.fbk.knowledgestore.vocabulary.KS;
import org.openrdf.model.URI;

import javax.annotation.Nullable;
import java.io.Closeable;
import java.util.Map;

/**
 * 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;

    SparqlUpdate sparqlupdate() throws IllegalStateException;
    SparqlDelete sparqldelete() 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.