Interface RDF
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 Dataset
s or Quad
s.
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 Summary
Modifier and TypeMethodDescriptionCreate a new blank node.createBlankNode
(String name) Create a blank node based on the given name.Create a new dataset.Create a new graph.Create an IRI from a (possibly escaped) String.createLiteral
(String lexicalForm) Create a simple literal.createLiteral
(String lexicalForm, String languageTag) Create a language-tagged literal.createLiteral
(String lexicalForm, IRI dataType) Create a literal with the specified data type.createQuad
(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object) Create a quad.createTriple
(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) Create a triple.
-
Method Details
-
createBlankNode
BlankNode createBlankNode()Create a new blank node.The returned blank node MUST NOT be equal to any existing
BlankNode
instances according toBlankNode.equals(Object)
.- Returns:
- A new, unique
BlankNode
-
createBlankNode
Create a blank node based on the given name.All
BlankNode
s created with the givenname
on a particular instance ofRDF
MUST be equivalent according toBlankNode.equals(Object)
,The returned BlankNode MUST NOT be equal to
BlankNode
instances returned for any othername
or those returned fromcreateBlankNode()
.The returned BlankNode SHOULD NOT be equivalent to any BlankNodes created on a different
RDF
instance, e.g. different instances ofRDF
should produce different blank nodes for the samename
unless they purposely are intending to create equivalentBlankNode
instances (e.g. a reinstatedSerializable
factory).- Parameters:
name
- A non-empty, non-null, String that is unique to this blank node in the context of thisRDF
.- 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
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
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 aLiteral.getLexicalForm()
that is equal to the provided lexical form, MUST NOT have aLiteral.getLanguageTag()
present, and SHOULD return aLiteral.getDatatype()
that is equal to the IRIhttp://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
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 aLiteral.getLexicalForm()
that is equal to the provided lexicalForm, MUST NOT have aLiteral.getLanguageTag()
present, and MUST return aLiteral.getDatatype()
that is equivalent to the provided dataType IRI.- Parameters:
lexicalForm
- The literal valuedataType
- 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
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 aLiteral.getLexicalForm()
which is equal to the provided lexicalForm, MUST return aLiteral.getDatatype()
that is equal to the IRIhttp://www.w3.org/1999/02/22-rdf-syntax-ns#langString
, and MUST have aLiteral.getLanguageTag()
present which SHOULD be equal to the provided language tag (compared asString.toLowerCase(Locale)
usingLocale.ENGLISH
).- Parameters:
lexicalForm
- The literal valuelanguageTag
- 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 aTriple.getSubject()
that is equal to the provided subject, aTriple.getPredicate()
that is equal to the provided predicate, and aTriple.getObject()
that is equal to the provided object.- Parameters:
subject
- The IRI or BlankNode that is the subject of the triplepredicate
- The IRI that is the predicate of the tripleobject
- 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, aQuad.getSubject()
that is equal to the provided subject, aQuad.getPredicate()
that is equal to the provided predicate, and aQuad.getObject()
that is equal to the provided object.- Parameters:
graphName
- The IRI or BlankNode that this quad belongs to, ornull
for the public graphsubject
- The IRI or BlankNode that is the subject of the quadpredicate
- The IRI that is the predicate of the quadobject
- 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.
-