1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.apache.commons.rdf.api;
19
20 import java.util.UUID;
21
22 /**
23 * A <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node" >RDF-1.1
24 * Blank Node</a>, as defined by
25 * <a href= "http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes" >RDF-1.1
26 * Concepts and Abstract Syntax</a>, a W3C Recommendation published on 25
27 * February 2014.<br>
28 *
29 * Note: <blockquote>
30 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">Blank nodes</a>
31 * are disjoint from IRIs and literals. Otherwise, the set of possible blank
32 * nodes is arbitrary. RDF makes no reference to any internal structure of blank
33 * nodes. </blockquote>
34 *
35 * Also note that: <blockquote> <a href=
36 * "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">Blank node
37 * identifiers</a> are local identifiers that are used in some concrete RDF
38 * syntaxes or RDF store implementations. They are always <em>locally
39 * scoped</em> to the file or RDF store, and are <em>not</em> persistent or
40 * portable identifiers for blank nodes. Blank node identifiers are <em>not</em>
41 * part of the RDF abstract syntax, but are entirely dependent on the concrete
42 * syntax or implementation. The syntactic restrictions on blank node
43 * identifiers, if any, therefore also depend on the concrete RDF syntax or
44 * implementation.
45 *
46 * Implementations that handle blank node identifiers in concrete syntaxes need
47 * to be careful not to create the same blank node from multiple occurrences of
48 * the same blank node identifier except in situations where this is supported
49 * by the syntax. </blockquote>
50 *
51 * A BlankNode SHOULD contain a {@link UUID}-derived string as part of its
52 * universally unique {@link #uniqueReference()}.
53 *
54 * @see RDF#createBlankNode()
55 * @see RDF#createBlankNode(String)
56 * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">RDF-1.1
57 * Blank Node</a>
58 */
59 public interface BlankNode extends BlankNodeOrIRI {
60
61 /**
62 * Return a reference for uniquely identifying the blank node.
63 * <p>
64 * The reference string MUST universally and uniquely identify this blank
65 * node. That is, different blank nodes created separately in different JVMs
66 * or from different {@link RDF} instances MUST NOT have the same reference
67 * string.
68 * <p>
69 * The {@link #uniqueReference()} of two <code>BlankNode</code> instances
70 * MUST be equal if and only if the two blank nodes are equal according to
71 * {@link #equals(Object)}.
72 * <p>
73 * Clients should not assume any particular structure of the reference
74 * string, however it is recommended that the reference string contain a
75 * UUID-derived string, e.g. as returned from {@link UUID#toString()}.
76 * <p>
77 * <strong>IMPORTANT:</strong> This is not a
78 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">
79 * blank node identifier</a> nor a serialization/syntax label, and there are
80 * no guarantees that it is a valid identifier in any concrete RDF syntax.
81 * For an N-Triples compatible identifier, use {@link #ntriplesString()}.
82 *
83 * @return A universally unique reference to identify this {@link BlankNode}
84 */
85 String uniqueReference();
86
87 /**
88 * Check it this BlankNode is equal to another BlankNode. Two BlankNodes
89 * MUST be equal if, and only if, they have the same
90 * {@link #uniqueReference()}.
91 * <p>
92 * Implementations MUST also override {@link #hashCode()} so that two equal
93 * Literals produce the same hash code.
94 *
95 * @param other
96 * Another object
97 * @return true if other is a BlankNode instance that represent the same
98 * blank node
99 * @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 }