public interface Session extends Closeable
Interaction with the KnowledgeStore through its Java API occurs within a Session
, which
encapsulates user-specific configuration and, if authenticated, user credentials. A
Session
can be obtained via KnowledgeStore.newSession()
(for anonymous user) or
KnowledgeStore#newSession(URI, String)
(authenticated user) and must be released with
close()
to freed resources possibly allocated to the session.
The identifier of the session's user, if any, is provided by method #getUser()
, while
the configured password is available using getPassword()
. Method
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 Data.getNamespaceMap()
. Namespace mappings play a relevant role in the interaction
with the KnowledgeStore, as they are used for encoding and decoding XPath
expressions,
merge Criteria
s and SPARQL queries.
Operations of the KnowledgeStore API can be invoked starting from a Session
object and
using operation objects. Every operation has its own Operation
sub-class, an
instance of which can be obtained by calling a method in 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 exec()
/ execXXX()
methods on the operation objects. More in details,
the API operations in the following table are offered:
Session
methodOperation
sub-classType Endpoint Description #download()
Operation.Download
read-only CRUD Downloads one or more resource representations. #upload()
Operation.Upload
read-write CRUD Uploads one or more resource representations. count(URI)
Operation.Count
read-only CRUD Count the number of resources / mentions / entities / axioms that match an optional condition. retrieve(URI)
Operation.Retrieve
read-only CRUD Retrieves selected properties of resources / mentions / entities / axioms that match an optional condition create(URI)
Operation.Create
read-write CRUD Creates one or more new resources / mentions / entities / axioms. merge(URI)
Operation.Merge
read-write CRUD Merges local record descriptions of resources / mentions / entities / axioms with descriptions stored in the KnowledgeStore, applying supplied merge criteria. update(URI)
Operation.Update
read-write CRUD Updates one or more properties of all the resources / mentions / entities / axioms that match an optional condition. delete(URI)
Operation.Delete
read-write CRUD Deletes all the resources / mentions / entities / axioms matching an optional condition. match()
Operation.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. sparql(String, Object...)
Operation.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. Session
objects are thread
safe. Object equality is used for comparing Session
instances.
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes the
Session instance, releasing any resource possibly
allocated. |
Operation.Count |
count(org.openrdf.model.URI type)
Creates a new
Count operation object for counting records of the type specified. |
Operation.Create |
create(org.openrdf.model.URI type)
Creates a new
Create operation object for storing new records of the type
specified. |
Operation.Delete |
delete(org.openrdf.model.URI type)
Creates a new
Delete operation object for deleting records of the type specified. |
Operation.Download |
download(org.openrdf.model.URI resourceID)
Creates a new
Download operation object. |
Map<String,String> |
getNamespaces()
Returns the modifiable namespace map of this
Session . |
String |
getPassword()
Returns the user password, if any.
|
String |
getUsername()
Returns the username associated to this
Session , if any. |
boolean |
isClosed()
Tests whether this
Session instance has been closed. |
Operation.Match |
match()
Creates a new
Match operation object for matching <resource, mention, entity,
axioms> 4-tuples matching specific conditions. |
Operation.Merge |
merge(org.openrdf.model.URI type)
Creates a new
Merge operation object for merging local record description of the
type specified with descriptions stored in the KnowledgeStore. |
Operation.Retrieve |
retrieve(org.openrdf.model.URI type)
Creates a new
Retrieve operation object for retrieving records of the type
specified. |
Operation.Sparql |
sparql(String expression,
Object... arguments)
Creates a new
Sparql operation object for evaluating a SPARQL query on crystallized
axiom data. |
Operation.SparqlDelete |
sparqldelete() |
Operation.SparqlUpdate |
sparqlupdate() |
Operation.Update |
update(org.openrdf.model.URI type)
Creates a new
Update operation object for updating one or more properties of
records of the type specified. |
Operation.Upload |
upload(org.openrdf.model.URI resourceID)
Creates a new
Upload operation object. |
@Nullable String getUsername() throws IllegalStateException
Session
, if any.Session
is anonymousIllegalStateException
- if the Session
has been closed@Nullable String getPassword() throws IllegalStateException
IllegalStateException
- if the Session
has been closedMap<String,String> getNamespaces() throws IllegalStateException
Session
. The map is backed by the
default mappings of Data#getNamespaceMap()
. New mappings are stored in the
Session
map and may override the default mappings. Removal of mappings is performed
on the Session
map, and may reactivate the default mapping as a consequence.Session
IllegalStateException
- if the Session
has been closedOperation.Download download(org.openrdf.model.URI resourceID) throws IllegalStateException
Download
operation object.resourceID
- the ID of the resource whose representation should be downloadedDownload
operation objectIllegalStateException
- if the Session
has been closedOperation.Upload upload(org.openrdf.model.URI resourceID) throws IllegalStateException
Upload
operation object.resourceID
- the ID of the resource whose representation should be updatedUpload
operation objectIllegalStateException
- if the Session
has been closedOperation.Count count(org.openrdf.model.URI type) throws IllegalStateException
Count
operation object for counting records of the type specified.type
- the URI of the type of record to count, either KS.RESOURCE
,
KS.MENTION
, KS.ENTITY
or KS.AXIOM
Count
operation objectIllegalStateException
- if the Session
has been closedOperation.Retrieve retrieve(org.openrdf.model.URI type) throws IllegalStateException
Retrieve
operation object for retrieving records of the type
specified.type
- the URI of the type of record to retrieve, either KS.RESOURCE
,
KS.MENTION
, KS.ENTITY
or KS.AXIOM
Retrieve
operation objectIllegalStateException
- if the Session
has been closedOperation.Create create(org.openrdf.model.URI type) throws IllegalStateException
Create
operation object for storing new records of the type
specified.type
- the URI of the type of record to create, either KS.RESOURCE
,
KS.MENTION
, KS.ENTITY
or KS.AXIOM
Create
operation objectIllegalStateException
- if the Session
has been closedOperation.Merge merge(org.openrdf.model.URI type) throws IllegalStateException
Merge
operation object for merging local record description of the
type specified with descriptions stored in the KnowledgeStore.type
- the URI of the type of record to merge, either KS.RESOURCE
,
KS.MENTION
, KS.ENTITY
or KS.AXIOM
Merge
operation objectIllegalStateException
- if the Session
has been closedOperation.Update update(org.openrdf.model.URI type) throws IllegalStateException
Update
operation object for updating one or more properties of
records of the type specified.type
- the URI of the type of record to update, either KS.RESOURCE
,
KS.MENTION
, KS.ENTITY
or KS.AXIOM
Update
operation objectIllegalStateException
- if the Session
has been closedOperation.Delete delete(org.openrdf.model.URI type) throws IllegalStateException
Delete
operation object for deleting records of the type specified.type
- the URI of the type of record to delete, either KS.RESOURCE
,
KS.MENTION
, KS.ENTITY
or KS.AXIOM
Delete
operation objectIllegalStateException
- if the Session
has been closedOperation.Match match() throws IllegalStateException
Match
operation object for matching <resource, mention, entity,
axioms> 4-tuples matching specific conditions.Match
operation objectIllegalStateException
- if the Session
has been closedOperation.Sparql sparql(String expression, Object... arguments) throws IllegalStateException
Sparql
operation object for evaluating a SPARQL query on crystallized
axiom data.expression
- the SPARQL query expression, not nullarguments
- arguments to be injected in $$
placeholders in the query expression; can
be URI
s, Literal
s or scalar values that can be converted to
Literal
s (e.g., strings, integers)Sparql
operation objectIllegalStateException
- if the Session
has been closedOperation.SparqlUpdate sparqlupdate() throws IllegalStateException
IllegalStateException
Operation.SparqlDelete sparqldelete() throws IllegalStateException
IllegalStateException
boolean isClosed()
Session
instance has been closed.Session
instance has been closedvoid close()
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 Session
interface will result in
IllegalStateException
s to be thrown.close
in interface AutoCloseable
close
in interface Closeable
Copyright © 2015–2016 FBK-irst. All rights reserved.