Interface RDF

All Known Implementing Classes:
JsonLdRDF, RDF4J, SimpleRDF

public interface RDF
A RDF implementation.

A RDF implementation can create instances of the RDFTerm types IRI, BlankNode and Literal, as well as creating instances of the types Triple, Quad, Graph or Dataset.

A partial RDF implementation should be clearly documented as such, and may throw UnsupportedOperationException where applicable, e.g. if it does not support creating Datasets or Quads.

Instances of RDF work like a factory for creating Commons RDF instances. spezializations of this interface may also provide methods for conversions from/to their underlying RDF framework.

If a factory method of a particular implementation does not allow or support a provided parameter, e.g. because an IRI is considered invalid, then it SHOULD throw IllegalArgumentException.

Since:
0.3.0-incubating
See Also:
  • Method Details

    • createBlankNode

      BlankNode createBlankNode()
      Create a new blank node.

      The returned blank node MUST NOT be equal to any existing BlankNode instances according to BlankNode.equals(Object).

      Returns:
      A new, unique BlankNode
    • createBlankNode

      BlankNode createBlankNode(String name)
      Create a blank node based on the given name.

      All BlankNodes created with the given name on a particular instance of RDF MUST be equivalent according to BlankNode.equals(Object),

      The returned BlankNode MUST NOT be equal to BlankNode instances returned for any other name or those returned from createBlankNode().

      The returned BlankNode SHOULD NOT be equivalent to any BlankNodes created on a different RDF instance, e.g. different instances of RDF should produce different blank nodes for the same name unless they purposely are intending to create equivalent BlankNode instances (e.g. a reinstated Serializable factory).

      Parameters:
      name - A non-empty, non-null, String that is unique to this blank node in the context of this RDF.
      Returns:
      A BlankNode for the given name
    • createGraph

      Graph createGraph()
      Create a new graph. It is undefined if the graph will be persisted by any underlying storage mechanism.
      Returns:
      A new Graph
    • createDataset

      Dataset createDataset()
      Create a new dataset. It is undefined if the dataset will be persisted by any underlying storage mechanism.
      Returns:
      A new Dataset
    • createIRI

      IRI createIRI(String iri) throws IllegalArgumentException
      Create an IRI from a (possibly escaped) String. The provided iri string MUST be valid according to the W3C RDF-1.1 IRI definition.
      Parameters:
      iri - Internationalized Resource Identifier
      Returns:
      A new IRI
      Throws:
      IllegalArgumentException - If the provided string is not acceptable, e.g. does not conform to the RFC3987 syntax.
    • createLiteral

      Literal createLiteral(String lexicalForm) throws IllegalArgumentException
      Create a simple literal. The provided lexical form should not be escaped in any sense, e.g. should not include "quotes" unless those are part of the literal value. The returned Literal MUST have a Literal.getLexicalForm() that is equal to the provided lexical form, MUST NOT have a Literal.getLanguageTag() present, and SHOULD return a Literal.getDatatype() that is equal to the IRI http://www.w3.org/2001/XMLSchema#string.
      Parameters:
      lexicalForm - The literal value in plain text
      Returns:
      The created Literal
      Throws:
      IllegalArgumentException - If the provided lexicalForm is not acceptable, e.g. because it is too large for an underlying storage.
    • createLiteral

      Literal createLiteral(String lexicalForm, IRI dataType) throws IllegalArgumentException
      Create a literal with the specified data type. The provided lexical form should not be escaped in any sense, e.g. should not include "quotes" unless those are part of the literal value. It is RECOMMENDED that the provided dataType is one of the RDF-compatible XSD types. The provided lexical form SHOULD be in the lexical space of the provided dataType. The returned Literal SHOULD have a Literal.getLexicalForm() that is equal to the provided lexicalForm, MUST NOT have a Literal.getLanguageTag() present, and MUST return a Literal.getDatatype() that is equivalent to the provided dataType IRI.
      Parameters:
      lexicalForm - The literal value
      dataType - The data type IRI for the literal value, e.g. http://www.w3.org/2001/XMLSchema#integer
      Returns:
      The created Literal
      Throws:
      IllegalArgumentException - If any of the provided arguments are not acceptable, e.g. because the provided dataType is not permitted.
    • createLiteral

      Literal createLiteral(String lexicalForm, String languageTag) throws IllegalArgumentException
      Create a language-tagged literal. The provided lexical form should not be escaped in any sense, e.g. should not include "quotes" unless those are part of the literal value. The provided language tag MUST be valid according to BCP47, e.g. en. The provided language tag MAY be converted to lower case. The returned Literal SHOULD have a Literal.getLexicalForm() which is equal to the provided lexicalForm, MUST return a Literal.getDatatype() that is equal to the IRI http://www.w3.org/1999/02/22-rdf-syntax-ns#langString, and MUST have a Literal.getLanguageTag() present which SHOULD be equal to the provided language tag (compared as String.toLowerCase(Locale) using Locale.ENGLISH).
      Parameters:
      lexicalForm - The literal value
      languageTag - The non-empty language tag as defined by BCP47
      Returns:
      The created Literal
      Throws:
      IllegalArgumentException - If the provided values are not acceptable, e.g. because the languageTag was syntactically invalid.
    • createTriple

      Triple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException
      Create a triple. The returned Triple SHOULD have a Triple.getSubject() that is equal to the provided subject, a Triple.getPredicate() that is equal to the provided predicate, and a Triple.getObject() that is equal to the provided object.
      Parameters:
      subject - The IRI or BlankNode that is the subject of the triple
      predicate - The IRI that is the predicate of the triple
      object - The IRI, BlankNode or Literal that is the object of the triple
      Returns:
      The created Triple
      Throws:
      IllegalArgumentException - If any of the provided arguments are not acceptable, e.g. because a Literal has a lexicalForm that is too large for an underlying storage.
    • createQuad

      Quad createQuad(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException
      Create a quad.

      The returned Quad SHOULD have a Quad.getGraphName() that is equal to the provided graphName, a Quad.getSubject() that is equal to the provided subject, a Quad.getPredicate() that is equal to the provided predicate, and a Quad.getObject() that is equal to the provided object.

      Parameters:
      graphName - The IRI or BlankNode that this quad belongs to, or null for the public graph
      subject - The IRI or BlankNode that is the subject of the quad
      predicate - The IRI that is the predicate of the quad
      object - The IRI, BlankNode or Literal that is the object of the quad
      Returns:
      The created Quad
      Throws:
      IllegalArgumentException - If any of the provided arguments are not acceptable, e.g. because a Literal has a lexicalForm that is too large for an underlying storage.