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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of marklogic-client-api Show documentation
The official MarkLogic Java client API.
The newest version!
/*
 * Copyright © 2024 MarkLogic Corporation. All Rights Reserved.
 */
package com.marklogic.client.semantics;

import java.util.List;
import java.util.Locale;
import java.util.Map;

/** Represents binding names and values to be sent with a SPARQL Query.
 * Available for situations where {@link SPARQLQueryDefinition#withBinding
 * SPARQLQueryDefinition.withBinding} methods are not enough.
 *
 * 
Example matching an iri:
 *
 *     graphMgr.setDefaultMimetype(RDFMimeTypes.NTRIPLES);
 *    graphMgr.writeAs("http://example.org",
 *        "<http://example.org/s1> <http://example.org/p1> <http://example.org/object1> .\n" +
 *        "<http://example.org/s2> <http://example.org/p2> \"object2\" .\n" +
 *        "<http://example.org/s3> <http://example.org/p3> \"object3\"@en .");
 *    String select = "SELECT * WHERE { ?s ?p ?o }";
 *    SPARQLQueryDefinition qdef = sparqlMgr.newQueryDefinition(select);
 *    SPARQLBindings bindings = qdef.getBindings();
 *    bindings.bind("o", "http://example.org/object1");
 *    JacksonHandle results = sparqlMgr.executeSelect(qdef, new JacksonHandle());
 *
 * Example matching a literal of rdf data type string (re-using data and variables above):
 *
 *     qdef = sparqlMgr.newQueryDefinition(select);
 *    bindings = qdef.getBindings();
 *    bindings.bind("o", "object2", RDFTypes.STRING);
 *    results = sparqlMgr.executeSelect(qdef, new JacksonHandle());
 *
 *
 * Example matching a string with a language tag (re-using data and variables above):
 *
 *     qdef = sparqlMgr.newQueryDefinition(select);
 *    bindings = qdef.getBindings();
 *    bindings.bind("o", "object3", new Locale("en"));
 *    results = sparqlMgr.executeSelect(qdef, new JacksonHandle());
 *
 * For more about RDF literals, see RDF 1.1 section 3.3.
 *
 * 
For details about RDF, SPARQL, and semantics in MarkLogic see the Semantics
 * Developer's Guide.
 */
public interface SPARQLBindings extends Map> {
  /** 
Bind a variable of type iri.
   *
   * @param name the bound variable name
   * @param value the iri value
   *
   * @return this instance (for method chaining)
   */
  SPARQLBindings bind(String name, String value);

  /** Bind a variable of specified type.
   *
   * @param name the bound variable name
   * @param value the value of the literal
   * @param datatype the literal type
   *
   * @return this instance (for method chaining)
   */
  SPARQLBindings bind(String name, String value, RDFTypes datatype);

  /** Bind a variable of type
   * http://www.w3.org/1999/02/22-rdf-syntax-ns#langString with the specified
   * language tag.  Note that we call {@link Locale#toLanguageTag}
   * to get compliant IETF BCP 47 language tags.
   *
   * @param name the bound variable name
   * @param value the value as a string
   * @param languageTag the language and regional modifiers compliant with BCP-47
   *
   * @return this instance (for method chaining)
   */
  SPARQLBindings bind(String name, String value, Locale languageTag);
};