001/**
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package com.github.commonsrdf.api;
015
016/**
017 * An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node" >RDF-1.1
018 * Blank Node</a>, as defined by <a href=
019 * "http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes" >RDF-1.1 Concepts
020 * and Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.<br>
021 *
022 * Note that: Blank nodes are disjoint from IRIs and literals. Otherwise,
023 * the set of possible blank nodes is arbitrary. RDF makes no reference to any
024 * internal structure of blank nodes.
025 *
026 * Also note that: Blank node identifiers are local identifiers that are
027 * used in some concrete RDF syntaxes or RDF store implementations. They are
028 * always locally scoped to the file or RDF store, and are not persistent or
029 * portable identifiers for blank nodes. Blank node identifiers are not part of
030 * the RDF abstract syntax, but are entirely dependent on the concrete syntax or
031 * implementation. The syntactic restrictions on blank node identifiers, if any,
032 * therefore also depend on the concrete RDF syntax or implementation.
033 * Implementations that handle blank node identifiers in concrete syntaxes need
034 * to be careful not to create the same blank node from multiple occurrences of
035 * the same blank node identifier except in situations where this is supported
036 * by the syntax.
037 *
038 * @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">RDF-1.1
039 * Blank Node</a>
040 */
041public interface BlankNode extends BlankNodeOrIRI {
042
043    /**
044     * Return a <a href=
045     * "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">label</a>
046     * for the blank node. This is not a serialization/syntax label. It should
047     * be uniquely identifying within the local scope it is created in but has
048     * no uniqueness guarantees other than that.
049     *
050     * In particular, the existence of two objects of type {@link BlankNode}
051     * with the same value returned from {@link #internalIdentifier()} are not
052     * equivalent unless they are known to have been created in the same local
053     * scope.
054     *
055     * An example of a local scope may be an instance of a Java Virtual Machine
056     * (JVM). In the context of a JVM instance, an implementor may support
057     * insertion and removal of {@link Triple} objects containing Blank Nodes
058     * without modifying the blank node labels.
059     *
060     * Another example of a local scope may be a <a
061     * href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph">Graph</a>
062     * or <a
063     * href="http://www.w3.org/TR/rdf11-concepts/#section-dataset">Dataset</a>
064     * created from a single document. In this context, an implementor should
065     * reasonably guarantee that the label returned by getLabel only maps to
066     * equivalent blank nodes in the same Graph or Dataset, but they may not
067     * guarantee that it is unique for the JVM instance. In this case, the
068     * implementor may support a mechanism to provide a mapping for blank nodes
069     * between Graph or Dataset instances to guarantee their uniqueness.
070     *
071     * If implementors support <a
072     * href="http://www.w3.org/TR/rdf11-concepts/#section-skolemization"
073     * >Skolemisation</a>, they may map instances of {@link BlankNode} objects
074     * to {@link IRI} objects to reduce scoping issues.
075     *
076     * @return An internal, system identifier for the {@link BlankNode}.
077     */
078    String internalIdentifier();
079
080}