001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.commons.rdf.api;
019
020import java.util.UUID;
021
022/**
023 * A <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node" >RDF-1.1
024 * Blank Node</a>, as defined by
025 * <a href= "http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes" >RDF-1.1
026 * Concepts and Abstract Syntax</a>, a W3C Recommendation published on 25
027 * February 2014.<br>
028 *
029 * Note: <blockquote>
030 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">Blank nodes</a>
031 * are disjoint from IRIs and literals. Otherwise, the set of possible blank
032 * nodes is arbitrary. RDF makes no reference to any internal structure of blank
033 * nodes. </blockquote>
034 *
035 * Also note that: <blockquote> <a href=
036 * "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">Blank node
037 * identifiers</a> are local identifiers that are used in some concrete RDF
038 * syntaxes or RDF store implementations. They are always <em>locally
039 * scoped</em> to the file or RDF store, and are <em>not</em> persistent or
040 * portable identifiers for blank nodes. Blank node identifiers are <em>not</em>
041 * part of the RDF abstract syntax, but are entirely dependent on the concrete
042 * syntax or implementation. The syntactic restrictions on blank node
043 * identifiers, if any, therefore also depend on the concrete RDF syntax or
044 * implementation.
045 *
046 * Implementations that handle blank node identifiers in concrete syntaxes need
047 * to be careful not to create the same blank node from multiple occurrences of
048 * the same blank node identifier except in situations where this is supported
049 * by the syntax. </blockquote>
050 *
051 * A BlankNode SHOULD contain a {@link UUID}-derived string as part of its
052 * universally unique {@link #uniqueReference()}.
053 *
054 * @see RDF#createBlankNode()
055 * @see RDF#createBlankNode(String)
056 * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">RDF-1.1
057 *      Blank Node</a>
058 */
059public interface BlankNode extends BlankNodeOrIRI {
060
061    /**
062     * Return a reference for uniquely identifying the blank node.
063     * <p>
064     * The reference string MUST universally and uniquely identify this blank
065     * node. That is, different blank nodes created separately in different JVMs
066     * or from different {@link RDF} instances MUST NOT have the same reference
067     * string.
068     * <p>
069     * The {@link #uniqueReference()} of two <code>BlankNode</code> instances
070     * MUST be equal if and only if the two blank nodes are equal according to
071     * {@link #equals(Object)}.
072     * <p>
073     * Clients should not assume any particular structure of the reference
074     * string, however it is recommended that the reference string contain a
075     * UUID-derived string, e.g. as returned from {@link UUID#toString()}.
076     * <p>
077     * <strong>IMPORTANT:</strong> This is not a
078     * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">
079     * blank node identifier</a> nor a serialization/syntax label, and there are
080     * no guarantees that it is a valid identifier in any concrete RDF syntax.
081     * For an N-Triples compatible identifier, use {@link #ntriplesString()}.
082     *
083     * @return A universally unique reference to identify this {@link BlankNode}
084     */
085    String uniqueReference();
086
087    /**
088     * Check it this BlankNode is equal to another BlankNode. Two BlankNodes
089     * MUST be equal if, and only if, they have the same
090     * {@link #uniqueReference()}.
091     * <p>
092     * Implementations MUST also override {@link #hashCode()} so that two equal
093     * Literals produce the same hash code.
094     *
095     * @param other
096     *            Another object
097     * @return true if other is a BlankNode instance that represent the same
098     *         blank node
099     * @see Object#equals(Object)
100     */
101    @Override
102    boolean equals(Object other);
103
104    /**
105     * Calculate a hash code for this BlankNode.
106     * <p>
107     * The returned hash code MUST be equal to the {@link String#hashCode()} of
108     * the {@link #uniqueReference()}.
109     * <p>
110     * This method MUST be implemented in conjunction with
111     * {@link #equals(Object)} so that two equal BlankNodes produce the same
112     * hash code.
113     *
114     * @return a hash code value for this BlankNode.
115     * @see Object#hashCode()
116     */
117    @Override
118    int hashCode();
119
120}