package eu.fbk.knowledgestore;
import java.util.Arrays;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import javax.annotation.Nullable;
import com.google.common.base.MoreObjects;
import com.google.common.base.Preconditions;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableSet;
import com.google.common.collect.Iterables;
import com.google.common.collect.Lists;
import com.google.common.collect.Maps;
import com.google.common.collect.Sets;
import org.openrdf.model.Statement;
import org.openrdf.model.URI;
import org.openrdf.query.BindingSet;
import eu.fbk.knowledgestore.Outcome.Status;
import eu.fbk.knowledgestore.data.Criteria;
import eu.fbk.knowledgestore.data.Data;
import eu.fbk.knowledgestore.data.Handler;
import eu.fbk.knowledgestore.data.ParseException;
import eu.fbk.knowledgestore.data.Record;
import eu.fbk.knowledgestore.data.Representation;
import eu.fbk.knowledgestore.data.Stream;
import eu.fbk.knowledgestore.data.XPath;
import eu.fbk.knowledgestore.vocabulary.KS;
// best effort basis: will interrupt thread, then it is up to the implementation to
// decide what to do
// for read operations, HTTP connection can be interrupted; for create / merge
// operations, no more data should be sent; delete / update will make the connection
// fail
// properties for which there is no criteria are not modified
public abstract class Operation {
private final Map<String, String> inheritedNamespaces;
Map<String, String> namespaces;
Long timeout;
Operation(@Nullable final Map<String, String> inheritedNamespaces) {
this.inheritedNamespaces = inheritedNamespaces != null ? inheritedNamespaces
: ImmutableMap.<String, String>of();
this.namespaces = this.inheritedNamespaces;
this.timeout = null;
}
/**
* Sets the optional timeout for this operation in milliseconds. Passing null or a
* non-positive value will remove any timeout previously set.
*
* @param timeout
* the timeout; null or non-positive to reset
* @return this operation object for call chaining
*/
public synchronized Operation timeout(@Nullable final Long timeout) {
this.timeout = timeout == null || timeout > 0 ? timeout : null;
return this;
}
/**
* Sets the optional namespaces for this operation. Supplied namespaces overrides the
* namespaces inherited from the {@code Session}. Passing null will remove any namespace map
* previously set on the operation.
*
* @param namespaces
* the namespace map overriding session namespaces; null to reset
* @return this operation object for call chaining
*/
public synchronized Operation namespaces(@Nullable final Map<String, String> namespaces) {
this.namespaces = namespaces == null ? this.inheritedNamespaces : Data.newNamespaceMap(
namespaces, this.inheritedNamespaces);
return this;
}
// UTILITY METHODS
static URI checkType(final URI type) {
Preconditions.checkNotNull(type, "No type specified");
if (!type.equals(KS.RESOURCE) && !type.equals(KS.MENTION) && !type.equals(KS.ENTITY)
&& !type.equals(KS.AXIOM)) {
throw new IllegalArgumentException("Invalid type: " + type);
}
return type;
}
static XPath conditionFor(final URI property, final Object... allowedValues) {
final String namespace = property.getNamespace();
final String prefix = MoreObjects.firstNonNull(//
Data.namespaceToPrefix(namespace, Data.getNamespaceMap()), "ns");
return XPath.parse(
String.format("with %s: <%s> : %s:%s = {}", prefix, namespace, prefix,
property.getLocalName()), allowedValues);
}
static <T> Handler<T> handlerFor(@Nullable final Collection<? super T> collection) {
if (collection == null) {
return null;
} else {
return new Handler<T>() {
@Override
public void handle(final T element) {
if (element != null) {
collection.add(element);
}
}
};
}
}
@Nullable
static XPath merge(final Iterable<XPath> conditions) {
return conditions == null || Iterables.isEmpty(conditions) ? null : XPath.compose("and",
(Object[]) Iterables.toArray(conditions, XPath.class));
}
static <T> List<T> add(@Nullable final List<T> list, final T element) {
if (list == null) {
return ImmutableList.of(element);
} else {
final List<T> tmp = Lists.newArrayList(list);
tmp.add(element);
return ImmutableList.copyOf(tmp);
}
}
static <T> Set<T> add(@Nullable final Set<T> set, final T element) {
if (set == null) {
return ImmutableSet.of(element);
} else {
final List<T> tmp = Lists.newArrayList(set);
tmp.add(element);
return ImmutableSet.copyOf(tmp);
}
}
/**
* Download operation.
* <p>
* This operation attempts at fetching the representation associated to a resource with the ID
* specified. The operation is controlled by two optional parameters:
* {@link #caching(boolean)} enables or disables the use of intermediate caches, if available,
* while {@link #accept(String...)} / {@link #accept(Iterable)} require the returned
* representation to have a certain MIME type (if it is not the case, the invocation fails).
* </p>
*/
public abstract static class Download extends Operation {
private final URI resourceID;
@Nullable
private Set<String> mimeTypes;
private boolean caching;
/**
* Creates a new {@code Download} operation instance.
*
* @param inheritedNamespaces
* an <b>immutable</b> map of inherited namespaces, possibly null
* @param resourceID
* the ID of the resource whose representation should be retrieved
*/
protected Download(@Nullable final Map<String, String> inheritedNamespaces,
final URI resourceID) {
super(inheritedNamespaces);
this.resourceID = Preconditions.checkNotNull(resourceID, "Null resource ID");
this.mimeTypes = null;
this.caching = true;
}
@Override
public Download timeout(@Nullable final Long timeout) {
return (Download) super.timeout(timeout);
}
@Override
public Download namespaces(@Nullable final Map<String, String> namespaces) {
return (Download) super.namespaces(namespaces);
}
/**
* Sets the acceptable MIME type (default: accept everything). Supplied values override
* previously configured MIME types; passing null will drop the constraint.
*
* @param mimeTypes
* the acceptable MIME types; null (default) to drop any constraint
* @return this operation object, for call chaining
*/
public final synchronized Download accept(@Nullable final String... mimeTypes) {
return accept(mimeTypes == null ? null : Arrays.asList(mimeTypes));
}
/**
* Sets the acceptable MIME types (default: accept everything). Supplied values override
* previously configured MIME types; passing null will drop the constraint.
*
* @param mimeTypes
* the acceptable MIME types; null (default) to drop any constraint
* @return this operation object, for call chaining
*/
public final synchronized Download accept(
@Nullable final Iterable<? extends String> mimeTypes) {
this.mimeTypes = mimeTypes == null ? null : Sets.newLinkedHashSet(mimeTypes);
return this;
}
/**
* Sets whether the representation can be retrieved from caches (default true).
*
* @param caching
* true, if the representation can be retrieved from caches
* @return this operation object, for call chaining
*/
public final synchronized Download caching(final boolean caching) {
this.caching = caching;
return this;
}
/**
* Executes the operation, returning the requested representation or null, if it does not
* exist. Note that returned representations MUST be closed after use.
*
* @return the requested representation, or null if it does not exist
* @throws OperationException
* in case of failure (see possible outcome status codes)
*/
public final synchronized Representation exec() throws OperationException {
return doExec(this.timeout, this.resourceID, this.mimeTypes, this.caching);
}
/**
* Implementation method responsible of executing the download operation.
*
* @param timeout
* the optional timeout for the operation; null if there is no timeout
* @param resourceID
* the ID of the resource whose representation must be returned
* @param mimeTypes
* the acceptable MIME types; null if there is no constraint
* @param caching
* true, if the representation can be retrieved from a cache
* @return the resource representation, if exists, otherwise null
* @throws OperationException
* in case of failure (see possible outcome status codes)
*/
@Nullable
protected abstract Representation doExec(@Nullable Long timeout, URI resourceID,
@Nullable Set<String> mimeTypes, boolean caching) throws OperationException;
}
/**
* Upload operation.
* <p>
* The operation outcome may assume one among the following {@code Status} codes:
* </p>
* <table border="1">
* <tr>
* <th>Status</th>
* <th>Explanation</th>
* <th>Reported as</td>
* </tr>
* <tr>
* <td>{@link Status#OK_CREATED}</td>
* <td>the file was successfully uploaded without replacing an existing file for the same
* resource</td>
* <td>{@code exec()} return value</td>
* </tr>
* <tr>
* <td>{@link Status#OK_MODIFIED}</td>
* <td>the file was successfully uploaded and replaced an existing file bound to the same
* resource</td>
* <td>{@code exec()} return value</td>
* </tr>
* <tr>
* <td>{@link Status#OK_DELETED}</td>
* <td>the file was successfully deleted</td>
* <td>{@code exec()} return value</td>
* </tr>
* <tr>
* <td>{@link Status#ERROR_INVALID_INPUT}</td>
* <td>in case the supplied URI is not valid or a problem is detected in the uploaded file</td>
* <td>{@code OperationException}</td>
* </tr>
* <tr>
* <td>{@link Status#ERROR_OBJECT_NOT_FOUND}</td>
* <td>the file cannot be deleted because it does not exist (the associated resource may or
* may not exist)</td>
* <td>{@code OperationException}</td>
* </tr>
* <tr>
* <td>{@link Status#ERROR_DEPENDENCY_NOT_FOUND}</td>
* <td>supplied file cannot be stored because the referenced resource does not exist</td>
* <td>{@code OperationException}</td>
* </tr>
* <tr>
* <td>{@link Status#ERROR_UNEXPECTED}</td>
* <td>an unexpected error occurred preventing the successful execution of the operation</td>
* <td>{@code OperationException}</td>
* </tr>
* <tr>
* <td>{@link Status#ERROR_UNKNOWN}</td>
* <td>a connectivity problem caused the interruption of the operation whose outcome is
* unknown</td>
* <td>{@code OperationException}</td>
* </tr>
* </table>
*/
public abstract static class Upload extends Operation {
private final URI resourceID;
@Nullable
private Representation representation;
protected Upload(final Map<String, String> inheritedNamespaces, final URI id) {
super(inheritedNamespaces);
this.resourceID = Preconditions.checkNotNull(id, "Null resource ID");
this.representation = null;
}
@Override
public Upload timeout(@Nullable final Long timeout) {
return (Upload) super.timeout(timeout);
}
@Override
public Upload namespaces(@Nullable final Map<String, String> namespaces) {
return (Upload) super.namespaces(namespaces);
}
/**
* Sets the representation to upload, if any. Setting null will cause any previously
* stored representation to be dropped.
*
* @param representation
* the representation to upload, if any
* @return this operation object, for call chaining
*/
public final synchronized Upload representation(
@Nullable final Representation representation) {
this.representation = representation;
return this;
}
/**
* Executes the operation, returning its outcome.
*
* @return the outcome of the operation
* @throws OperationException
* in case of failure (see possible outcome status codes)
*/
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.resourceID, this.representation);
}
protected abstract Outcome doExec(@Nullable Long timeout, URI resourceID,
@Nullable Representation representation) throws OperationException;
}
public abstract static class Count extends Operation {
private final URI type;
@Nullable
private List<XPath> conditions;
@Nullable
private Set<URI> ids;
protected Count(final Map<String, String> namespaces, final URI type) {
super(namespaces);
this.type = checkType(type);
this.conditions = null;
this.ids = null;
}
@Override
public Count timeout(@Nullable final Long timeout) {
return (Count) super.timeout(timeout);
}
@Override
public Count namespaces(@Nullable final Map<String, String> namespaces) {
return (Count) super.namespaces(namespaces);
}
public final synchronized Count conditions(@Nullable final XPath... conditions) {
return conditions(conditions == null ? null : Arrays.asList(conditions));
}
public final synchronized Count conditions(
@Nullable final Iterable<? extends XPath> conditions) {
this.conditions = conditions == null ? null : ImmutableList.copyOf(conditions);
return this;
}
public final synchronized Count condition(final String condition,
final Object... arguments) throws ParseException {
this.conditions = add(this.conditions,
XPath.parse(this.namespaces, condition, arguments));
return this;
}
public final synchronized Count condition(final URI property,
final Object... allowedValues) {
this.conditions = add(this.conditions, conditionFor(property, allowedValues));
return this;
}
public final synchronized Count ids(@Nullable final URI... ids) {
return ids(ids == null ? null : Arrays.asList(ids));
}
public final synchronized Count ids(@Nullable final Iterable<? extends URI> ids) {
this.ids = ids == null ? null : ImmutableSet.copyOf(ids);
return this;
}
public final synchronized long exec() throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids);
}
protected abstract long doExec(@Nullable Long timeout, URI type,
@Nullable XPath condition, @Nullable Set<URI> ids) throws OperationException;
}
public abstract static class Retrieve extends Operation {
private final URI type;
@Nullable
private List<XPath> conditions;
@Nullable
private Set<URI> ids;
@Nullable
private Set<URI> properties;
@Nullable
private Long offset;
@Nullable
private Long limit;
protected Retrieve(final Map<String, String> namespaces, final URI type) {
super(namespaces);
this.type = checkType(type);
this.conditions = null;
this.ids = null;
this.properties = null;
this.offset = null;
this.limit = null;
}
@Override
public Retrieve timeout(@Nullable final Long timeout) {
return (Retrieve) super.timeout(timeout);
}
@Override
public Retrieve namespaces(@Nullable final Map<String, String> namespaces) {
return (Retrieve) super.namespaces(namespaces);
}
public final synchronized Retrieve conditions(@Nullable final XPath... conditions) {
return conditions(conditions == null ? null : Arrays.asList(conditions));
}
public final synchronized Retrieve conditions(
@Nullable final Iterable<? extends XPath> conditions) {
this.conditions = conditions == null ? null : ImmutableList.copyOf(conditions);
return this;
}
public final synchronized Retrieve condition(final String condition,
final Object... arguments) throws ParseException {
this.conditions = add(this.conditions,
XPath.parse(this.namespaces, condition, arguments));
return this;
}
public final synchronized Retrieve condition(final URI property,
final Object... allowedValues) {
this.conditions = add(this.conditions, conditionFor(property, allowedValues));
return this;
}
public final synchronized Retrieve ids(@Nullable final URI... ids) {
return ids(ids == null ? null : Arrays.asList(ids));
}
public final synchronized Retrieve ids(@Nullable final Iterable<? extends URI> ids) {
this.ids = ids == null ? null : ImmutableSet.copyOf(ids);
return this;
}
// no call or empty = all properties
public final synchronized Retrieve properties(@Nullable final URI... properties) {
return properties(properties == null ? null : Arrays.asList(properties));
}
public final synchronized Retrieve properties(
@Nullable final Iterable<? extends URI> properties) {
this.properties = properties == null ? null : ImmutableSet.copyOf(properties);
return this;
}
public final synchronized Retrieve offset(@Nullable final Long offset) {
this.offset = offset == null || offset <= 0 ? null : offset;
return this;
}
public final synchronized Retrieve limit(@Nullable final Long limit) {
this.limit = limit == null || limit <= 0 ? null : limit;
return this;
}
public final synchronized Stream<Record> exec() throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids,
this.properties, this.offset, this.limit);
}
protected abstract Stream<Record> doExec(@Nullable final Long timeout, final URI type,
@Nullable final XPath condition, @Nullable final Set<URI> ids,
@Nullable final Set<URI> properties, @Nullable Long offset, @Nullable Long limit)
throws OperationException;
}
public abstract static class Create extends Operation {
private final URI type;
@Nullable
private Stream<? extends Record> records;
protected Create(final Map<String, String> namespaces, final URI type) {
super(namespaces);
this.type = checkType(type);
this.records = null;
}
@Override
public Create timeout(@Nullable final Long timeout) {
return (Create) super.timeout(timeout);
}
@Override
public Create namespaces(@Nullable final Map<String, String> namespaces) {
return (Create) super.namespaces(namespaces);
}
public final synchronized Create records(@Nullable final Record... records) {
this.records = records == null ? null : Stream.create(records);
return this;
}
public final synchronized Create records(//
@Nullable final Iterable<? extends Record> records) {
this.records = records == null ? null : Stream.create(records);
return this;
}
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.type, this.records, null);
}
// TODO: errors from the handlers are logged and cause the invocation to be interrupted
// eventually; still, the handler will be notified of all the outcomes until the
// invocation ends
public final synchronized Outcome exec(@Nullable final Handler<? super Outcome> handler)
throws OperationException {
return doExec(this.timeout, this.type, this.records, handler);
}
public final synchronized Outcome exec(
@Nullable final Collection<? super Outcome> collection) throws OperationException {
return doExec(this.timeout, this.type, this.records, handlerFor(collection));
}
protected abstract Outcome doExec(@Nullable Long timeout, final URI type,
@Nullable final Stream<? extends Record> records,
@Nullable final Handler<? super Outcome> handler) throws OperationException;
}
public abstract static class Merge extends Operation {
private final URI type;
@Nullable
private Stream<? extends Record> records;
@Nullable
private Criteria criteria;
protected Merge(final Map<String, String> namespaces, final URI type) {
super(namespaces);
this.type = checkType(type);
this.records = null;
this.criteria = null;
}
@Override
public Merge timeout(@Nullable final Long timeout) {
return (Merge) super.timeout(timeout);
}
@Override
public Merge namespaces(@Nullable final Map<String, String> namespaces) {
return (Merge) super.namespaces(namespaces);
}
public final synchronized Merge records(@Nullable final Record... records) {
this.records = records == null ? null : Stream.create(records);
return this;
}
public final synchronized Merge records(//
@Nullable final Iterable<? extends Record> records) {
this.records = records == null ? null : Stream.create(records);
return this;
}
public final synchronized Merge criteria(@Nullable final Criteria... criteria) {
return criteria(criteria == null ? null : Arrays.asList(criteria));
}
public final synchronized Merge criteria(
@Nullable final Iterable<? extends Criteria> criteria) {
this.criteria = criteria == null || Iterables.isEmpty(criteria) ? null : Criteria
.compose(Iterables.toArray(criteria, Criteria.class));
return this;
}
public final synchronized Merge criteria(@Nullable final String criteria)
throws ParseException {
this.criteria = criteria == null ? null : Criteria.parse(criteria, this.namespaces);
return this;
}
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.type, this.records, this.criteria, null);
}
public final synchronized Outcome exec(@Nullable final Handler<? super Outcome> handler)
throws OperationException {
return doExec(this.timeout, this.type, this.records, this.criteria, handler);
}
public final synchronized Outcome exec(
@Nullable final Collection<? super Outcome> collection) throws OperationException {
return doExec(this.timeout, this.type, this.records, this.criteria,
handlerFor(collection));
}
protected abstract Outcome doExec(@Nullable Long timeout, URI type,
@Nullable Stream<? extends Record> stream, @Nullable Criteria criteria,
@Nullable Handler<? super Outcome> handler) throws OperationException;
}
public abstract static class Update extends Operation {
private final URI type;
@Nullable
private List<XPath> conditions;
@Nullable
private Set<URI> ids;
@Nullable
private Record record;
@Nullable
private Criteria criteria;
protected Update(final Map<String, String> namespaces, final URI type) {
super(namespaces);
this.type = checkType(type);
this.conditions = null;
this.ids = null;
this.record = null;
this.criteria = null;
}
@Override
public Update timeout(@Nullable final Long timeout) {
return (Update) super.timeout(timeout);
}
@Override
public Update namespaces(@Nullable final Map<String, String> namespaces) {
return (Update) super.namespaces(namespaces);
}
public final synchronized Update conditions(@Nullable final XPath... conditions) {
return conditions(conditions == null ? null : Arrays.asList(conditions));
}
public final synchronized Update conditions(
@Nullable final Iterable<? extends XPath> conditions) {
this.conditions = conditions == null ? null : ImmutableList.copyOf(conditions);
return this;
}
public final synchronized Update condition(final String condition,
final Object... arguments) throws ParseException {
this.conditions = add(this.conditions,
XPath.parse(this.namespaces, condition, arguments));
return this;
}
public final synchronized Update condition(final URI property,
final Object... allowedValues) {
this.conditions = add(this.conditions, conditionFor(property, allowedValues));
return this;
}
public final synchronized Update ids(@Nullable final URI... ids) {
return ids(ids == null ? null : Arrays.asList(ids));
}
public final synchronized Update ids(@Nullable final Iterable<? extends URI> ids) {
this.ids = ids == null ? null : ImmutableSet.copyOf(ids);
return this;
}
public final synchronized Update record(@Nullable final Record record) {
this.record = record;
return this;
}
public final synchronized Update criteria(@Nullable final Criteria... criteria) {
return criteria(criteria == null ? null : Arrays.asList(criteria));
}
public final synchronized Update criteria(
@Nullable final Iterable<? extends Criteria> criteria) {
this.criteria = criteria == null || Iterables.isEmpty(criteria) ? null : Criteria
.compose(Iterables.toArray(criteria, Criteria.class));
return this;
}
public final synchronized Update criteria(@Nullable final String criteria)
throws ParseException {
this.criteria = criteria == null ? null : Criteria.parse(criteria, this.namespaces);
return this;
}
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids, this.record,
this.criteria, null);
}
public final synchronized Outcome exec(@Nullable final Handler<? super Outcome> handler)
throws OperationException {
final Record record = this.record != null ? this.record : Record.create();
return doExec(this.timeout, this.type, merge(this.conditions), this.ids, record,
this.criteria, handler);
}
public final synchronized Outcome exec(
@Nullable final Collection<? super Outcome> collection) throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids, this.record,
this.criteria, handlerFor(collection));
}
protected abstract Outcome doExec(@Nullable Long timeout, URI type,
@Nullable XPath condition, @Nullable Set<URI> ids, @Nullable Record record,
@Nullable Criteria criteria, @Nullable Handler<? super Outcome> handler)
throws OperationException;
}
public abstract static class Delete extends Operation {
private final URI type;
@Nullable
private List<XPath> conditions;
@Nullable
private Set<URI> ids;
protected Delete(final Map<String, String> namespaces, final URI type) {
super(namespaces);
this.type = checkType(type);
this.conditions = null;
this.ids = null;
}
@Override
public Delete timeout(@Nullable final Long timeout) {
return (Delete) super.timeout(timeout);
}
@Override
public Delete namespaces(@Nullable final Map<String, String> namespaces) {
return (Delete) super.namespaces(namespaces);
}
public final synchronized Delete conditions(@Nullable final XPath... conditions) {
return conditions(conditions == null ? null : Arrays.asList(conditions));
}
public final synchronized Delete conditions(
@Nullable final Iterable<? extends XPath> conditions) {
this.conditions = conditions == null ? null : ImmutableList.copyOf(conditions);
return this;
}
public final synchronized Delete condition(final String condition,
final Object... arguments) throws ParseException {
this.conditions = add(this.conditions,
XPath.parse(this.namespaces, condition, arguments));
return this;
}
public final synchronized Delete condition(final URI property,
final Object... allowedValues) {
this.conditions = add(this.conditions, conditionFor(property, allowedValues));
return this;
}
public final synchronized Delete ids(@Nullable final URI... ids) {
return ids(ids == null ? null : Arrays.asList(ids));
}
public final synchronized Delete ids(@Nullable final Iterable<? extends URI> ids) {
this.ids = ids == null ? null : ImmutableSet.copyOf(ids);
return this;
}
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids, null);
}
public final synchronized Outcome exec(@Nullable final Handler<? super Outcome> handler)
throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids, handler);
}
public final synchronized Outcome exec(
@Nullable final Collection<? super Outcome> collection) throws OperationException {
return doExec(this.timeout, this.type, merge(this.conditions), this.ids,
handlerFor(collection));
}
protected abstract Outcome doExec(@Nullable Long timeout, URI type,
@Nullable XPath condition, @Nullable Set<URI> ids,
@Nullable Handler<? super Outcome> handler) throws OperationException;
}
public abstract static class Match extends Operation {
private static final Map<URI, URI> COMPONENT_NORMALIZATION_MAP = //
ImmutableMap.<URI, URI>builder().put(KS.RESOURCE, KS.RESOURCE)
.put(KS.MATCHED_RESOURCE, KS.RESOURCE).put(KS.MENTION, KS.MENTION)
.put(KS.MATCHED_MENTION, KS.MENTION).put(KS.ENTITY, KS.ENTITY)
.put(KS.MATCHED_ENTITY, KS.ENTITY).build();
private final Map<URI, Set<XPath>> conditions;
private final Map<URI, Set<URI>> ids;
private final Map<URI, Set<URI>> properties;
protected Match(final Map<String, String> namespaces) {
super(namespaces);
this.conditions = Maps.newHashMap();
this.ids = Maps.newHashMap();
this.properties = Maps.newHashMap();
}
@Override
public Match timeout(@Nullable final Long timeout) {
return (Match) super.timeout(timeout);
}
@Override
public Match namespaces(@Nullable final Map<String, String> namespaces) {
return (Match) super.namespaces(namespaces);
}
public final synchronized Match conditions(@Nullable final URI component,
@Nullable final XPath... conditions) {
return conditions(component, conditions == null ? null : Arrays.asList(conditions));
}
public final synchronized Match conditions(@Nullable final URI component,
@Nullable final Iterable<? extends XPath> conditions) {
if (component == null) {
this.conditions.clear();
} else {
this.conditions.put(checkComponent(component), conditions == null ? null
: ImmutableSet.copyOf(conditions));
}
return this;
}
public final synchronized Match condition(final URI component, final String condition,
final Object... arguments) throws ParseException {
final URI comp = checkComponent(component);
final XPath cond = XPath.parse(this.namespaces, condition, arguments);
this.conditions.put(comp, add(this.conditions.get(comp), cond));
return this;
}
public final synchronized Match condition(final URI component, final URI property,
final Object... allowedValues) {
final URI comp = checkComponent(component);
final XPath cond = conditionFor(property, allowedValues);
this.conditions.put(comp, add(this.conditions.get(comp), cond));
return this;
}
public final synchronized Match ids(@Nullable final URI component,
@Nullable final URI... ids) {
return ids(component, ids == null ? null : Arrays.asList(ids));
}
public final synchronized Match ids(@Nullable final URI component,
@Nullable final Iterable<? extends URI> ids) {
if (component == null) {
this.ids.clear();
} else {
this.ids.put(checkComponent(component),
ids == null ? null : ImmutableSet.copyOf(ids));
}
return this;
}
// no call = exclude class; empty = all properties
public final synchronized Match properties(@Nullable final URI component,
@Nullable final URI... properties) {
return properties(component, properties == null ? null : Arrays.asList(properties));
}
public final synchronized Match properties(@Nullable final URI component,
@Nullable final Iterable<? extends URI> properties) {
if (component == null) {
this.properties.clear();
} else {
this.properties.put(checkComponent(component), properties == null ? null
: ImmutableSet.copyOf(properties));
}
return this;
}
public final synchronized Stream<Record> exec() throws OperationException {
final Map<URI, XPath> conditions = Maps.newHashMap();
for (final URI component : this.conditions.keySet()) {
conditions.put(component, merge(this.conditions.get(component)));
}
return doExec(this.timeout, conditions, this.ids, this.properties);
}
protected abstract Stream<Record> doExec(@Nullable final Long timeout,
final Map<URI, XPath> conditions, final Map<URI, Set<URI>> ids,
final Map<URI, Set<URI>> properties) throws OperationException;
private URI checkComponent(final URI component) {
final URI uri = COMPONENT_NORMALIZATION_MAP.get(component);
Preconditions.checkArgument(uri != null, "Invalid match component %s", component);
return uri;
}
}
// TODO: add missing namespaces based on available namespaces
public abstract static class SparqlUpdate extends Operation {
@Nullable
private Stream<? extends Statement> statements;
protected SparqlUpdate(final Map<String, String> namespaces) throws ParseException {
super(namespaces);
}
public final synchronized SparqlUpdate statements(@Nullable final Statement... statements) {
this.statements = statements == null ? null : Stream.create(statements);
return this;
}
public final synchronized SparqlUpdate statements(//
@Nullable final Iterable<? extends Statement> statements) {
this.statements = statements == null ? null : Stream.create(statements);
return this;
}
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.statements);
}
protected abstract Outcome doExec(@Nullable Long timeout,
@Nullable final Stream<? extends Statement> statements) throws OperationException;
}
public abstract static class SparqlDelete extends Operation {
@Nullable
private Stream<? extends Statement> statements;
protected SparqlDelete(final Map<String, String> namespaces) throws ParseException {
super(namespaces);
}
public final synchronized SparqlDelete statements(@Nullable final Statement... statements) {
this.statements = statements == null ? null : Stream.create(statements);
return this;
}
public final synchronized SparqlDelete statements(//
@Nullable final Iterable<? extends Statement> statements) {
this.statements = statements == null ? null : Stream.create(statements);
return this;
}
public final synchronized Outcome exec() throws OperationException {
return doExec(this.timeout, this.statements);
}
protected abstract Outcome doExec(@Nullable Long timeout,
@Nullable final Stream<? extends Statement> statements) throws OperationException;
}
/**
* SPARQL query operation.
* <p>
* This operation evaluates a SPARQL query on the KnowledgeStore SPARQL endpoint. All SPARQL
* query forms are supported:
* <ul>
* <li>SELECT queries return a {@code Stream} of {@code BindingSet}s (call
* {@link Sparql#execTuples()});</li>
* <li>CONSTRUCT and DESCRIBE queries return a {@code Stream} of {@link Statement}s (call
* {@link Sparql#execTriples()});</li>
* <li>ASK queries return a boolean result (call {@link Sparql#execBoolean()}).</li>
* </ul>
* </p>
* <p>
* The operation can be configured, as usual, by specifying a timeout and supplying optional
* namespace bindings to be used for parsing the SPARQL expression. In addition,
* {@link Sparql#defaultGraphs(Iterable) default} and {@link Sparql#namedGraphs(Iterable)
* named} graphs can be specified at the operation level, overriding the corresponding
* declarations in the {@code FROM} and {@code FROM NAMED} clauses of the SPARQL query
* expression.
* </p>
*/
public abstract static class Sparql extends Operation {
private static final Pattern PLACEHOLDER_PATTERN = Pattern
.compile("(?:(?<=\\A|[^\\\\]))([$][$])(?:(?=\\z|.))");
private final String expression;
@Nullable
private Set<URI> defaultGraphs;
@Nullable
private Set<URI> namedGraphs;
/**
* Creates a new {@code Sparql} operation instance (to be used in {@code Session}
* implementations).
*
* @param namespaces
* an <b>immutable</b> map of inherited namespaces, possibly null
* @param expression
* the SPARQL query expression, not null and possibly containing {@code $$}
* placeholders
* @param arguments
* the values to assign to {@code $$} placeholders
* @throws ParseException
* in case the query expression is not valid
*/
protected Sparql(final Map<String, String> namespaces, final String expression,
final Object... arguments) throws ParseException {
super(namespaces);
this.expression = expand(expression, arguments);
this.defaultGraphs = null;
this.namedGraphs = null;
}
@Override
public Sparql timeout(@Nullable final Long timeout) {
return (Sparql) super.timeout(timeout);
}
@Override
public Sparql namespaces(@Nullable final Map<String, String> namespaces) {
return (Sparql) super.namespaces(namespaces);
}
/**
* Sets the optional default graphs for the query, overriding the default graphs specified
* in the <tt>FROM</tt> clause. Passing null will remove any default graph previously set.
*
* @param defaultGraphs
* a vararg array with the non-null URIs of the default graphs, possibly empty;
* pass null to remove any default graph previously set
* @return this operation object for call chaining
*/
public final synchronized Sparql defaultGraphs(@Nullable final URI... defaultGraphs) {
return defaultGraphs(defaultGraphs == null ? null : Arrays.asList(defaultGraphs));
}
/**
* Sets the optional default graphs for the query, overriding default graphs specified in
* the <tt>FROM</tt> clause. Passing null will remove any default graph previously set.
*
* @param defaultGraphs
* an {@code Iterable} with the non-null URIs of the default graphs, possibly
* empty; pass null to remove any default graph previously set
* @return this operation object for call chaining
*/
public final synchronized Sparql defaultGraphs(//
@Nullable final Iterable<URI> defaultGraphs) {
this.defaultGraphs = defaultGraphs == null ? null : ImmutableSet.copyOf(defaultGraphs);
return this;
}
/**
* Sets the optional named graphs for the query, overriding named graphs specified in the
* <tt>FROM NAMED</tt> clause. Passing null will remove any named graph previously set.
*
* @param namedGraphs
* a vararg array with the non-null URIs of the named graphs, possibly empty;
* pass null to remove any named graph previously set
* @return this operation object for call chaining
*/
public final synchronized Sparql namedGraphs(@Nullable final URI... namedGraphs) {
return namedGraphs(namedGraphs == null ? null : Arrays.asList(namedGraphs));
}
/**
* Sets the optional named graphs for the query, overriding named graphs specified in the
* <tt>FROM NAMED</tt> clause. Passing null will remove any named graph previously set.
*
* @param namedGraphs
* an {@code Iterable} with the non-null URIs of the named graphs, possibly
* empty; pass null to remove any named graph previously set
* @return this operation object for call chaining
*/
public final synchronized Sparql namedGraphs(@Nullable final Iterable<URI> namedGraphs) {
this.namedGraphs = namedGraphs == null ? null : ImmutableSet.copyOf(namedGraphs);
return this;
}
/**
* Evaluates the query, returning its boolean result; applicable to ASK queries.
*
* @return the boolean result of the query
* @throws OperationException
* on failure (see possible outcome status codes)
*/
public final synchronized boolean execBoolean() throws OperationException {
return doExec(this.timeout, Boolean.class, this.expression, this.defaultGraphs,
this.namedGraphs).getUnique();
}
/**
* Evaluates the query, returning a {@code Stream} with the resulting {@code Statement}s;
* applicable to CONSTRUCT and DESCRIBE queries.
*
* @return the resulting {@code Stream} of {@code Statement}s
* @throws OperationException
* on failure (see possible outcome status codes)
*/
public final synchronized Stream<Statement> execTriples() throws OperationException {
return doExec(this.timeout, Statement.class, this.expression, this.defaultGraphs,
this.namedGraphs);
}
/**
* Evaluates the query, returning a {@code Stream} with the resulting {@code BindingSet}s;
* applicable to SELECT queries. After access to the returned {@code Stream}, a
* {@code List<String>} with output variables can be obtained by querying the
* {@code Stream} metadata attribute {@code variables}.
*
* @return the resulting {@code Stream} of {@code BindingSet}s
* @throws OperationException
* on failure (see possible outcome status codes)
*/
public final synchronized Stream<BindingSet> execTuples() throws OperationException {
return doExec(this.timeout, BindingSet.class, this.expression, this.defaultGraphs,
this.namedGraphs);
}
/**
* Implementation method responsible of executing the SPARQL operation.
*
* @param timeout
* the optional timeout for the operation; null if there is no timeout
* @param type
* the expected type of elements for the resulting {@code Stream}; either
* {@link Statement}, {@link BindingSet} or {@link Boolean}
* @param expression
* the SPARQL query expression
* @param defaultGraphs
* the optional set of default graphs overriding the ones possibly specified in
* the {@code FROM} query clause; if null, no override should take place
* @param namedGraphs
* the optional set of named graphs overriding the ones possibly specified in
* the {@code FROM NAMED} query clause; if null, no override should take place
* @param <T>
* the type of result elements
* @return a {@code Stream} with the result of the query
* @throws OperationException
* in case of failure (see possible outcome status codes)
*/
protected abstract <T> Stream<T> doExec(@Nullable final Long timeout, final Class<T> type,
final String expression, @Nullable final Set<URI> defaultGraphs,
@Nullable final Set<URI> namedGraphs) throws OperationException;
private String expand(final String expression, final Object... arguments)
throws ParseException {
int expansions = 0;
String result = expression;
final Matcher matcher = PLACEHOLDER_PATTERN.matcher(expression);
try {
if (matcher.find()) {
final StringBuilder builder = new StringBuilder();
int last = 0;
do {
Object arg = arguments[expansions++];
builder.append(expression.substring(last, matcher.start(1)));
builder.append(arg instanceof Number ? arg : Data.toString(arg, null,
false));
last = matcher.end(1);
} while (matcher.find());
builder.append(expression.substring(last, expression.length()));
result = builder.toString();
}
} catch (final IndexOutOfBoundsException ex) {
throw new ParseException(expression, "No argument supplied for placeholder #"
+ expansions);
}
if (expansions != arguments.length) {
throw new ParseException(expression, "Expression string contains " + expansions
+ " placholders, but " + arguments.length + " arguments where supplied");
}
return result;
}
}
}