Class RDF4J

java.lang.Object
org.apache.commons.rdf.rdf4j.RDF4J
All Implemented Interfaces:
RDF
public final class RDF4J extends Object implements RDF
RDF4J implementation of RDF.

The RDF4J() constructor uses a SimpleValueFactory to create corresponding RDF4J Value instances. Alternatively, this factory can be constructed with a different ValueFactory using RDF4J(ValueFactory).

asRDFTerm(Value) can be used to convert any RDF4J Value to an RDFTerm. Note that adapted BNodes are considered equal if they are converted with the same RDF4J instance and have the same BNode.getID().

createGraph() creates a new Graph backed by LinkedHashModel. To use other models, see asGraph(Model).

To adapt a RDF4J Repository as a Dataset or Graph, use asDataset(Repository, Option...) or asGraph(Repository, Option...).

asTriple(Statement) can be used to convert a RDF4J Statement to a Commons RDF Triple, and equivalent asQuad(Statement) to convert a Quad.

To convert any Triple or Quad to to RDF4J Statement, use asStatement(TripleLike). This recognises previously converted RDF4JTriples and RDF4JQuads without re-converting their RDF4JTripleLike.asStatement().

Likewise, asValue(RDFTerm) can be used to convert any Commons RDF RDFTerm to a corresponding RDF4J Value. This recognises previously converted RDF4JTerms without re-converting their RDF4JTerm.asValue().

For the purpose of BlankNode equivalence, this factory contains an internal UUID salt that is used by adapter methods like asQuad(Statement), asTriple(Statement), asRDFTerm(Value) as well as createBlankNode(String). As RDF4J BNode instances from multiple repositories or models may have the same BNode.getID(), converting them with the above methods might cause accidental BlankNode equivalence. Note that the Graph and Dataset adapter methods like asDataset(Repository, Option...) and asGraph(Repository, Option...) therefore uses a unique RDF4J internally.

See Also:

  • Field Details

    • rdf4j

      private static InternalRDF4JFactory rdf4j
      InternalRDF4JFactory is deliberately abstract

    • salt

      private final UUID salt

    • valueFactory

      private final org.eclipse.rdf4j.model.ValueFactory valueFactory

  • Constructor Details

    • RDF4J

      public RDF4J()
      Construct an RDF4J.

    • RDF4J

      public RDF4J(org.eclipse.rdf4j.model.ValueFactory valueFactory)
      Construct an RDF4J.

      This constructor is intended for use with the value factory from Repository.getValueFactory() when using Repository-based graphs and datasets.

      Parameters:
      valueFactory - The RDF4J ValueFactory to use

    • RDF4J

      public RDF4J(UUID salt)
      Construct an RDF4J.

      This constructor may be used if reproducible BlankNode.uniqueReference() in BlankNode is desirable.

      Parameters:
      salt - An UUID salt to be used by any created BlankNodes for the purpose of BlankNode.uniqueReference()

    • RDF4J

      public RDF4J(org.eclipse.rdf4j.model.ValueFactory valueFactory, UUID salt)
      Construct an RDF4J.

      This constructor may be used if reproducible BlankNode.uniqueReference() in BlankNode is desirable.

      Parameters:
      valueFactory - The RDF4J ValueFactory to use
      salt - An UUID salt to be used by any created BlankNodes for the purpose of BlankNode.uniqueReference()

  • Method Details

    • asQuad

      public RDF4JQuad asQuad(org.eclipse.rdf4j.model.Statement statement)
      Adapt a RDF4J Statement as a Commons RDF Quad.

      For the purpose of BlankNode equivalence, this method will use an internal salt UUID that is unique per instance of RDF4J.

      NOTE: If combining RDF4J Statements multiple repositories or models, then their BNodes may have the same BNode.getID(), which with this method would become equivalent according to BlankNode.equals(Object) and BlankNode.uniqueReference(), unless a separate RDF4J instance is used per RDF4J repository/model.

      Parameters:
      statement - The statement to convert
      Returns:
      A RDF4JQuad that is equivalent to the statement

    • asRDFTerm

      public RDF4JTerm asRDFTerm(org.eclipse.rdf4j.model.Value value)
      Adapt a RDF4J Value as a Commons RDF RDFTerm.

      The value will be of the same kind as the term, e.g. a BNode is converted to a BlankNode, a IRI is converted to a IRI and a Literal. is converted to a Literal

      For the purpose of BlankNode equivalence, this method will use an internal salt UUID that is unique per instance of RDF4J.

      NOTE: If combining RDF4J values from multiple repositories or models, then their BNodes may have the same BNode.getID(), which with this method would become equivalent according to BlankNode.equals(Object) and BlankNode.uniqueReference(), unless a separate RDF4J instance is used per RDF4J repository/model.

      Parameters:
      value - The RDF4J Value to convert.
      Returns:
      A RDFTerm that corresponds to the RDF4J value
      Throws:
      IllegalArgumentException - if the value is not a BNode, Literal or IRI

    • asRDFTerm

      public RDF4JBlankNode asRDFTerm(org.eclipse.rdf4j.model.BNode value)
      Adapt a RDF4J BNode as a Commons RDF BlankNode

      For the purpose of BlankNode equivalence, this method will use an internal salt UUID that is unique per instance of RDF4J.

      NOTE: If combining RDF4J values from multiple repositories or models, then their BNodes may have the same BNode.getID(), which with this method would become equivalent according to BlankNode.equals(Object) and BlankNode.uniqueReference(), unless a separate RDF4J instance is used per RDF4J repository/model.

      Parameters:
      value - The RDF4J BNode to convert.
      Returns:
      A RDF4JBlankNode that corresponds to the RDF4J BNode

    • asRDFTerm

      public RDF4JLiteral asRDFTerm(org.eclipse.rdf4j.model.Literal value)
      Adapt a RDF4J Literal as a Commons RDF Literal

      Parameters:
      value - The RDF4J Literal to convert.
      Returns:
      A RDF4JLiteral that corresponds to the RDF4J literal

    • asRDFTerm

      public RDF4JIRI asRDFTerm(org.eclipse.rdf4j.model.IRI value)
      Adapt a RDF4J IRI as a Commons RDF IRI

      Parameters:
      value - The RDF4J Value to convert.
      Returns:
      A RDF4JIRI that corresponds to the RDF4J IRI

    • asRDFTerm

      public RDF4JBlankNodeOrIRI asRDFTerm(org.eclipse.rdf4j.model.Resource value)
      Adapt a RDF4J Resource as a Commons RDF BlankNodeOrIRI

      Parameters:
      value - The RDF4J Value to convert.
      Returns:
      A RDF4JBlankNodeOrIRI that corresponds to the RDF4J Resource

    • asRDFTerm

      public static RDF4JTerm asRDFTerm(org.eclipse.rdf4j.model.Value value, UUID salt)
      Adapt a RDF4J Value as a Commons RDF RDFTerm.

      The value will be of the same kind as the term, e.g. a BNode is converted to a BlankNode, a IRI is converted to a IRI and a Literal. is converted to a Literal

      Parameters:
      value - The RDF4J Value to convert.
      salt - A UUID salt to use for uniquely mapping any BNodes. The salt should typically be the same for multiple statements in the same Repository or Model to ensure BlankNode.equals(Object) and BlankNode.uniqueReference() works as intended.
      Returns:
      A RDFTerm that corresponds to the RDF4J value
      Throws:
      IllegalArgumentException - if the value is not a BNode, Literal or IRI

    • asDataset

      public RDF4JDataset asDataset(org.eclipse.rdf4j.repository.Repository repository, RDF4J.Option... options)
      Adapt an RDF4J Repository as a Commons RDF Dataset.

      Changes to the dataset are reflected in the repository, and vice versa.

      Note: Some operations on the RDF4JDataset requires the use of try-with-resources to close underlying RepositoryConnections, including RDF4JDataset.iterate(), RDF4JDataset.stream() and RDF4JDataset.getGraphNames().

      Parameters:
      repository - RDF4J Repository to connect to.
      options - Zero or more RDF4J.Option
      Returns:
      A Dataset backed by the RDF4J repository.

    • asGraph

      public RDF4JGraph asGraph(org.eclipse.rdf4j.model.Model model)
      Adapt an RDF4J Model as a Commons RDF Graph.

      Changes to the graph are reflected in the model, and vice versa.

      Parameters:
      model - RDF4J Model to adapt.
      Returns:
      Adapted Graph.

    • asGraph

      public RDF4JGraph asGraph(org.eclipse.rdf4j.repository.Repository repository, RDF4J.Option... options)
      Adapt an RDF4J Repository as a Commons RDF Graph.

      The graph will only include triples in the default graph (equivalent to context new Resource[0]{null}) in RDF4J).

      Changes to the graph are reflected in the repository, and vice versa.

      Note: Some operations on the RDF4JGraph requires the use of try-with-resources to close underlying RepositoryConnections, including RDF4JGraph.iterate() and RDF4JGraph.stream().

      Parameters:
      repository - RDF4J Repository to connect to.
      options - Zero or more RDF4J.Option
      Returns:
      A Graph backed by the RDF4J repository.

    • asGraphUnion

      public RDF4JGraph asGraphUnion(org.eclipse.rdf4j.repository.Repository repository, RDF4J.Option... options)
      Adapt an RDF4J Repository as a Commons RDF Graph.

      The graph will include triples in any contexts (e.g. the union graph).

      Changes to the graph are reflected in the repository, and vice versa.

      Parameters:
      repository - RDF4J Repository to connect to.
      options - Zero or more RDF4J.Option
      Returns:
      A union Graph backed by the RDF4J repository.

    • asGraph

      public RDF4JGraph asGraph(org.eclipse.rdf4j.repository.Repository repository, Set<? extends BlankNodeOrIRI> contexts, RDF4J.Option... option)
      Adapt an RDF4J Repository as a Commons RDF Graph.

      The graph will include triples in the specified contexts.

      Changes to the graph are reflected in the repository, and vice versa. Triples added/removed to the graph are reflected in all the specified contexts.

      Note: Some operations on the RDF4JGraph requires the use of try-with-resources to close underlying RepositoryConnections, including RDF4JGraph.iterate() and RDF4JGraph.stream().

      Parameters:
      repository - RDF4J Repository to connect to.
      contexts - A Set of BlankNodeOrIRI specifying the graph names to use as a context. The set may include the value null to indicate the default graph. The empty set indicates any context, e.g. the union graph.
      option - Zero or more RDF4J.Options
      Returns:
      A Graph backed by the RDF4J repository.

    • asStatement

      public org.eclipse.rdf4j.model.Statement asStatement(TripleLike tripleLike)
      Adapt a Commons RDF Triple or Quad as a RDF4J Statement.

      If the tripleLike argument is an RDF4JTriple or a RDF4JQuad, then its RDF4JTripleLike.asStatement() is returned as-is. Note that this means that a RDF4JTriple would preserve its Statement.getContext(), and that any BlankNodes would be deemed equivalent in RDF4J if they have the same BNode.getID().

      Parameters:
      tripleLike - A Triple or Quad to adapt
      Returns:
      A corresponding Statement

    • asTriple

      public RDF4JTriple asTriple(org.eclipse.rdf4j.model.Statement statement)
      Adapt a RDF4J Statement as a Commons RDF Triple.

      For the purpose of BlankNode equivalence, this method will use an internal salt UUID that is unique per instance of RDF4J.

      NOTE: If combining RDF4J statements from multiple repositories or models, then their BNodes may have the same BNode.getID(), which with this method would become equivalent according to BlankNode.equals(Object) and BlankNode.uniqueReference(), unless a separate RDF4J instance is used per RDF4J repository/model.

      Parameters:
      statement - The RDF4J Statement to adapt.
      Returns:
      A RDF4JTriple that is equivalent to the statement

    • asValue

      public org.eclipse.rdf4j.model.Value asValue(RDFTerm term)
      Adapt a Commons RDF RDFTerm as a RDF4J Value.

      The value will be of the same kind as the term, e.g. a BlankNode is converted to a BNode, a IRI is converted to a IRI and a Literal is converted to a Literal.

      If the provided RDFTerm is null, then the returned value is null.

      If the provided term is an instance of RDF4JTerm, then the RDF4JTerm.asValue() is returned without any conversion. Note that this could mean that a Value from a different kind of ValueFactory could be returned.

      Parameters:
      term - RDFTerm to adapt to RDF4J Value
      Returns:
      Adapted RDF4J Value

    • createBlankNode

      public RDF4JBlankNode createBlankNode()
      Description copied from interface: RDF
      Create a new blank node.

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

      Specified by:
      createBlankNode in interface RDF
      Returns:
      A new, unique BlankNode

    • createBlankNode

      public RDF4JBlankNode createBlankNode(String name)
      Description copied from interface: RDF
      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 RDF.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).

      Specified by:
      createBlankNode in interface RDF
      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

    • createDataset

      public RDF4JDataset createDataset()
      Create a new dataset. It is undefined if the dataset will be persisted by any underlying storage mechanism.

      Note: Some operations on the RDF4JDataset requires the use of try-with-resources to close underlying RepositoryConnections, including RDF4JDataset.iterate(), RDF4JDataset.stream() and RDF4JDataset.getGraphNames().

      Specified by:
      createDataset in interface RDF
      Returns:
      A new Dataset

    • createGraph

      public RDF4JGraph createGraph()
      Description copied from interface: RDF
      Create a new graph. It is undefined if the graph will be persisted by any underlying storage mechanism.
      Specified by:
      createGraph in interface RDF
      Returns:
      A new Graph

    • createIRI

      public RDF4JIRI createIRI(String iri) throws IllegalArgumentException
      Description copied from interface: RDF
      Create an IRI from a (possibly escaped) String. The provided iri string MUST be valid according to the W3C RDF-1.1 IRI definition.
      Specified by:
      createIRI in interface RDF
      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

      public RDF4JLiteral createLiteral(String lexicalForm) throws IllegalArgumentException
      Description copied from interface: RDF
      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.
      Specified by:
      createLiteral in interface RDF
      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

      public Literal createLiteral(String lexicalForm, IRI dataType) throws IllegalArgumentException
      Description copied from interface: RDF
      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.
      Specified by:
      createLiteral in interface RDF
      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

      public Literal createLiteral(String lexicalForm, String languageTag) throws IllegalArgumentException
      Description copied from interface: RDF
      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).
      Specified by:
      createLiteral in interface RDF
      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

      public RDF4JTriple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException
      Description copied from interface: RDF
      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.
      Specified by:
      createTriple in interface RDF
      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

      public Quad createQuad(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException
      Description copied from interface: RDF
      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.

      Specified by:
      createQuad in interface RDF
      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.

    • getValueFactory

      public org.eclipse.rdf4j.model.ValueFactory getValueFactory()

    • optionSet

      private EnumSet<RDF4J.Option> optionSet(RDF4J.Option... options)