All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.marklogic.client.semantics.SPARQLQueryManager Maven / Gradle / Ivy

/*
 * Copyright 2012-2016 MarkLogic Corporation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.marklogic.client.semantics;

import com.marklogic.client.Transaction;
import com.marklogic.client.DatabaseClient;
import com.marklogic.client.io.JacksonHandle;
import com.marklogic.client.io.marker.JSONReadHandle;
import com.marklogic.client.io.marker.SPARQLResultsReadHandle;
import com.marklogic.client.io.marker.TextWriteHandle;
import com.marklogic.client.io.marker.TriplesReadHandle;
import com.marklogic.client.io.marker.XMLReadHandle;
import com.marklogic.client.semantics.Capability;

/**
 * 

A manager for executing SPARQL queries in MarkLogic Server and retrieving * the results. * *

For example perform a SPARQL SELECT:

* *
    SPARQLQueryManager sparqlMgr = databaseClient.newSPARQLQueryManager();
 *    String sparql = "SELECT * WHERE { ?s ?p ?o } LIMIT 10";
 *    SPARQLQueryDefinition query = sparqlMgr.newQueryDefinition(sparql)
 *        .withBinding("o", "http://example.org/object1");
 *    JacksonHandle handle = new JacksonHandle();
 *    handle.setMimetype(SPARQLMimeTypes.SPARQL_JSON);
 *    JacksonHandle results = sparqlMgr.executeSelect(query, handle);
 *    JsonNode tuples = results.get().path("results").path("bindings");
 *    for ( JsonNode row : tuples ) {
 *        String s = row.path("s").path("value").asText();
 *        String p = row.path("p").path("value").asText();
 *        ...
 *    }
* *

Or perform a SPARQL CONSTRUCT:

* *
    String sparql = "CONSTRUCT { <a> <b> <c> } WHERE { ?s ?p ?o } LIMIT 10";
 *    SPARQLQueryDefinition query = sparqlMgr.newQueryDefinition(sparql);
 *    SPARQLBindings bindings = query.getBindings();
 *    query.setBindings(bindings.bind("o", "http://example.org/object1"));
 *    JacksonHandle handle = new JacksonHandle();
 *    handle.setMimetype(RDFMimeTypes.RDFJSON);
 *    JacksonHandle triples = sparqlMgr.executeConstruct(query, handle);
 *    JsonNode a = triples.get().path("a");
 *    JsonNode b = a.path("b");
 *    JsonNode c = b.get(0).path("value");
* *

Each new instance of SPARQLQueryManager is created by * {@link DatabaseClient#newSPARQLQueryManager}. While these examples use * JacksonHandle, any SPARQLResultsReadHandle may be used--including custom * handles. For executeSelect {@link JSONReadHandle}s will need to use {@link * SPARQLMimeTypes#SPARQL_JSON} mimetype, and {@link XMLReadHandle}s will need * to use {@link SPARQLMimeTypes#SPARQL_XML} mimetype, other {@link * SPARQLResultsReadHandle}s accept any text and can therefore accept results * in any of the SPARQLMimeTypes. For executeDescribe and executeConstruct * {@link JSONReadHandle}s will need to use {@link RDFMimeTypes#RDFJSON} * mimetype, and {@link XMLReadHandle}s will need to use {@link * RDFMimeTypes#RDFXML} mimetype, other {@link TriplesReadHandle}s accept any * text and can therefore accept results in any of the RDFMimeTypes. * *

SPARQLQueryManager is thread-safe other than setPageLength. In other * words the only state maintained by an instance is the page length. Common * usage is to call setPageLength only once then use the instance across many * threads. If you intend to call setPageLength from multiple threads, create * a new SPARQLQueryManager for each thread.

* *

For details about RDF, SPARQL, and semantics in MarkLogic see the * Semantics Developer's Guide. */ public interface SPARQLQueryManager { /** Instantiate a new SPARQLQueryDefinition. * * @return an empty SPARQLQueryDefinition */ public SPARQLQueryDefinition newQueryDefinition(); /** Instantiate a new SPARQLQueryDefinition with provided SPARQL. * * @param sparql a sparql query as text * @return the query as SPARQLQueryDefinition */ public SPARQLQueryDefinition newQueryDefinition(String sparql); /** Instantiate a new SPARQLQueryDefinition with the SPARQL from * the provided TextWriteHandle. * * @param sparql the handle containing a sparql query as text * @return the query as SPARQLQueryDefinition */ public SPARQLQueryDefinition newQueryDefinition(TextWriteHandle sparql); /** Execute a SPARQL "SELECT" query. * @param qdef the query * @param handle the handle capable of reading {@link SPARQLMimeTypes sparql results} * @param the type of SPARQLResultsReadHandle to return * @return the results in the provided SPARQLResultsReadHandle */ public T executeSelect(SPARQLQueryDefinition qdef, T handle); /** Execute a SPARQL "SELECT" query. * @param qdef the query * @param handle the handle capable of reading {@link SPARQLMimeTypes sparql results} * @param tx the transaction context for this operation * @param the type of SPARQLResultsReadHandle to return * @return the results in the provided SPARQLResultsReadHandle */ public T executeSelect(SPARQLQueryDefinition qdef, T handle, Transaction tx); /** Execute a SPARQL "SELECT" query. * @param qdef the query * @param handle the handle capable of reading {@link SPARQLMimeTypes sparql results} * @param start when paging through results, the first result of this page--must be > 0. * Use together with {@link #setPageLength}. * @param the type of SPARQLResultsReadHandle to return * @return the results in the provided SPARQLResultsReadHandle */ public T executeSelect(SPARQLQueryDefinition qdef, T handle, long start); /** Execute a SPARQL "SELECT" query. * @param qdef the query * @param handle the handle capable of reading {@link SPARQLMimeTypes sparql results} * @param start when paging through results, the first result of this page--must be > 0. * Use together with {@link #setPageLength}. * @param tx the transaction context for this operation * @param the type of SPARQLResultsReadHandle to return * @return the results in the provided SPARQLResultsReadHandle */ public T executeSelect(SPARQLQueryDefinition qdef, T handle, long start, Transaction tx); /** @return the currently set pageLength or -1 if no page length has been set */ public long getPageLength(); /** Set a page length for all SPARQL "SELECT" queries sent by this instance. * @param pageLength the non-negative number of results per page */ public void setPageLength(long pageLength); /** Reset this instance to have no page length set. */ public void clearPageLength(); /** Execute a SPARQL "CONSTRUCT" statement. * @param qdef the SPARQL "CONSTRUCT" statement * @param handle the handle capable of reading {@link RDFMimeTypes triples or quads results} * @param the type of TriplesReadHandle to return * @return the results in the provided TriplesReadHandle */ public T executeConstruct(SPARQLQueryDefinition qdef, T handle); /** Execute a SPARQL "CONSTRUCT" statement. * @param qdef the SPARQL "CONSTRUCT" statement * @param handle the handle capable of reading {@link RDFMimeTypes triples or quads results} * @param tx the transaction context for this query * @param the type of TriplesReadHandle to return * @return the results in the provided TriplesReadHandle */ public T executeConstruct(SPARQLQueryDefinition qdef, T handle, Transaction tx); /** Execute a SPARQL "DESCRIBE" query (which implements the Concise Bounded Description specification). * @param qdef the query * @param handle the handle capable of reading {@link RDFMimeTypes triples or quads results} * @param the type of TriplesReadHandle to return * @return the results in the provided TriplesReadHandle */ public T executeDescribe(SPARQLQueryDefinition qdef, T handle); /** Execute a SPARQL "DESCRIBE" query (which implements the Concise Bounded Description specification). * @param qdef the query * @param handle the handle capable of reading {@link RDFMimeTypes triples or quads results} * @param tx the transaction context for this query * @param the type of TriplesReadHandle to return * @return the results in the provided TriplesReadHandle */ public T executeDescribe(SPARQLQueryDefinition qdef, T handle, Transaction tx); /** Execute a SPARQL "ASK" statement. * @param qdef the SPARQL "CONSTRUCT" statement * @return the answer as Boolean */ public Boolean executeAsk(SPARQLQueryDefinition qdef); /** Execute a SPARQL "ASK" statement. * @param qdef the SPARQL "CONSTRUCT" statement * @param tx the transaction context for this query * @return the answer as Boolean */ public Boolean executeAsk(SPARQLQueryDefinition qdef, Transaction tx); /** Execute a SPARQL update statement. For an example of using with * permisisons see {@link #permission}. * * @param qdef the SPARQL update statement */ public void executeUpdate(SPARQLQueryDefinition qdef); /** Execute a SPARQL update statement. For an example of using with * permisisons see {@link #permission}. * * @param qdef the SPARQL update statement * @param tx the transaction context for this operation */ public void executeUpdate(SPARQLQueryDefinition qdef, Transaction tx); /**

For use with SPARQL update, where specified permissions will apply * to any records created by the update. Create a GraphPermissions builder * object with the specified role and capabilities.

* *

For example:

* *
    String sparqlUpdate = "INSERT DATA { <a> <b> <c> }";
     *    SPARQLQueryDefinition qdef = sparqlMgr.newQueryDefinition(sparqlUpdate);
     *    qdef.setUpdatePermissions(sparqlMgr.permission("rest-reader", Capability.UPDATE));
     *    sparqlMgr.executeUpdate(qdef);
* * @param role the name of the role receiving these capabilities * @param capabilities the capabilities (READ, UPDATE, or EXECUTE) granted to this role * @return the new GraphPermissions object with these capabilities set */ public GraphPermissions permission(String role, Capability... capabilities); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy