eu.fbk.knowledgestore.server.http.jaxrs.Sparql Maven / Gradle / Ivy

Go to download

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

The HTTP server module (ks-server-http) implements the Web API of the KnowledgeStore, which includes the two CRUD and SPARQL endpoints. The CRUD Endpoint supports the retrieval and manipulation of semi-structured data about resource, mention, entity and axiom records (encoded in RDF, possibly using JSONLD), and the upload / download of resource representation. The SPARQL Endpoint supports SPARQL SELECT, CONSTRUCT, DESCRIBE and ASK queries according to the W3C SPARQL protocol. The two endpoints are implemented on top of a component implementing the KnowledgeStore Java API (the Store interface), which can be either the the KnowledgeStore frontend (ks-frontend) or the Java Client. The implementation of the module is based on the Jetty Web sever (run in embedded mode) and the Jersey JAX-RS implementation. Reference documentation of the Web API is automatically generated using the Enunciate tool.

There is a newer version: 1.7.1

Show newest version

package eu.fbk.knowledgestore.server.http.jaxrs;

import java.util.List;
import java.util.Set;

import javax.ws.rs.Consumes;
import javax.ws.rs.FormParam;
import javax.ws.rs.GET;
import javax.ws.rs.HttpMethod;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.GenericType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;

import com.google.common.collect.Sets;

import org.codehaus.enunciate.jaxrs.TypeHint;
import org.openrdf.model.URI;

import eu.fbk.knowledgestore.Operation;
import eu.fbk.knowledgestore.OperationException;
import eu.fbk.knowledgestore.Outcome;
import eu.fbk.knowledgestore.data.Data;
import eu.fbk.knowledgestore.data.Stream;
import eu.fbk.knowledgestore.internal.jaxrs.Protocol;
import eu.fbk.knowledgestore.internal.rdf.RDFUtil;

/**
 * Provides the KnowledgeStore SPARQL endpoint.
 * 
 * DOCUMENTATION COMING SOON
 * 
 */
@Path("/" + Protocol.PATH_SPARQL)
public class Sparql extends Resource {

    @GET
    @Produces(Protocol.MIME_TYPES_ALL)
    @TypeHint(Stream.class)
    public Response get(
            @QueryParam(Protocol.PARAMETER_DEFAULT_GRAPH) final List defaultGraphs,
            @QueryParam(Protocol.PARAMETER_NAMED_GRAPH) final List namedGraphs,
            @QueryParam(Protocol.PARAMETER_QUERY) final String query) throws OperationException {
        return query(query, defaultGraphs, namedGraphs);
    }

    @POST
    @Consumes("application/x-www-form-urlencoded")
    @Produces(Protocol.MIME_TYPES_ALL)
    @TypeHint(Stream.class)
    public Response postURLencoded(
            @FormParam(Protocol.PARAMETER_DEFAULT_GRAPH) final List defaultGraphs,
            @FormParam(Protocol.PARAMETER_NAMED_GRAPH) final List namedGraphs,
            @FormParam(Protocol.PARAMETER_QUERY) final String query) throws OperationException {
        return query(query, defaultGraphs, namedGraphs);
    }

    @POST
    @Consumes("application/sparql-query")
    @Produces(Protocol.MIME_TYPES_ALL)
    @TypeHint(Stream.class)
    public Response postDirect(
            @QueryParam(Protocol.PARAMETER_DEFAULT_GRAPH) final List defaultGraphs,
            @QueryParam(Protocol.PARAMETER_NAMED_GRAPH) final List namedGraphs,
            final String query) throws OperationException {
        return query(query, defaultGraphs, namedGraphs);
    }

    private Response query(final String query, final List defaultGraphs,
            final List namedGraphs) throws OperationException {

        // Check mandatory parameter
        checkNotNull(query, Outcome.Status.ERROR_INVALID_INPUT, "Missing query");

        // Prepare the SPARQL operation, returning an error if parameters are wrong
        final String form;
        final Operation.Sparql operation;
        try {
            form = RDFUtil.detectSparqlForm(query);
            operation = getSession().sparql(query) //
                    .timeout(getTimeout()) //
                    .defaultGraphs(parseGraphURIs(defaultGraphs)) //
                    .namedGraphs(parseGraphURIs(namedGraphs));
        } catch (final RuntimeException ex) {
            throw new OperationException(newOutcome(Outcome.Status.ERROR_INVALID_INPUT, "%s",
                    ex.getMessage()), ex);
        }

        // Select correct MIME type via negotiation, validate preconditions and handle probes
        final GenericType type;
        if (form.equals("construct") || form.equals("describe")) {
            init(false, Protocol.MIME_TYPES_RDF, null, null);
            type = Protocol.STREAM_OF_STATEMENTS;
        } else if (form.equals("select")) {
            init(false, Protocol.MIME_TYPES_SPARQL_TUPLE, null, null);
            type = Protocol.STREAM_OF_TUPLES;
        } else {
            init(false, Protocol.MIME_TYPES_SPARQL_BOOLEAN, null, null);
            type = Protocol.STREAM_OF_BOOLEANS;
        }

        // Setup the result stream based on the selected type. Note that an empty result is
        // selected for HEAD methods, as only headers will be returned.
        Stream entity;
        if (getMethod().equals(HttpMethod.HEAD)) {
            entity = Stream.create();
        } else if (type == Protocol.STREAM_OF_STATEMENTS) {
            entity = operation.execTriples();
        } else if (type == Protocol.STREAM_OF_TUPLES) {
            entity = operation.execTuples();
        } else if (type == Protocol.STREAM_OF_BOOLEANS) {
            entity = Stream.create(operation.execBoolean());
        } else {
            throw new Error("Unexpected type: " + type);
        }

        // Build and return the SPARQL response
        return newResponseBuilder(Status.OK, closeOnCompletion(entity), type).build();
    }

    private static Set parseGraphURIs(final List strings) {
        if (strings == null || strings.isEmpty()) {
            return null;
        }
        final Set uris = Sets.newHashSetWithExpectedSize(strings.size());
        for (final String string : strings) {
            uris.add(Data.getValueFactory().createURI(string));
        }
        return uris;
    }

}