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 /**
21 * An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
22 * Term</a>, as defined by
23 * <a href= "http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and
24 * Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.
25 * <p>
26 * A {@link RDFTerm} object in Commons RDF is considered
27 * <strong>immutable</strong>, that is, over its life time it will have
28 * consistent behaviour for its {@link #equals(Object)} and {@link #hashCode()},
29 * and objects returned from its getter methods (e.g. {@link IRI#getIRIString()}
30 * and {@link Literal#getLanguageTag()}) will have consistent
31 * {@link #equals(Object)} behaviour.
32 * <p>
33 * Note that methods in <code>RDFTerm</code> and its Commons RDF specialisations
34 * {@link IRI}, {@link BlankNode} and {@link Literal} are not required to return
35 * object identical (<code>==</code>) instances as long as they are equivalent
36 * according to their {@link Object#equals(Object)}. Further specialisations may
37 * provide additional methods that are documented to be mutable.
38 * <p>
39 * Methods in <code>RDFTerm</code> and its Commons RDF specialisations
40 * {@link IRI}, {@link BlankNode} and {@link Literal} are
41 * <strong>thread-safe</strong>, however further specialisations may add
42 * additional methods that are documented to not be thread-safe.
43 * <p>
44 * <code>RDFTerm</code>s can be safely used in hashing collections like
45 * {@link java.util.HashSet} and {@link java.util.HashMap}.
46 * <p>
47 * Any <code>RDFTerm</code> can be used interchangeably across Commons RDF
48 * implementations.
49 *
50 * @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
51 * Term</a>
52 */
53 public interface RDFTerm {
54
55 /**
56 * Return the term serialised as specified by the RDF-1.1 N-Triples
57 * Canonical form.
58 *
59 * @return The term serialised as RDF-1.1 N-Triples.
60 * @see <a href="http://www.w3.org/TR/n-triples/#canonical-ntriples">
61 * RDF-1.1 N-Triples Canonical form</a>
62 */
63 String ntriplesString();
64
65 /**
66 * Check it this RDFTerm is equal to another RDFTerm.
67 * <p>
68 * If this object is an {@link IRI}, equality is checked using
69 * {@link IRI#equals(Object)}, or if this object is a {@link BlankNode},
70 * equality is checked using {@link BlankNode#equals(Object)}, or if this
71 * object is a {@link Literal}, equality is checked using
72 * {@link Literal#equals(Object)}.
73 * <p>
74 * Implementations MUST also override {@link #hashCode()} so that two equal
75 * Literals produce the same hash code.
76 *
77 * @see IRI#equals(Object)
78 * @see BlankNode#equals(Object)
79 * @see Literal#equals(Object)
80 *
81 * @param other
82 * Another object
83 * @return true if other is a RDFTerm and is equal to this
84 */
85 @Override
86 boolean equals(Object other);
87
88 /**
89 * Calculate a hash code for this RDFTerm.
90 * <p>
91 * As an {@link RDFTerm} is <em>immutable</em>, this method will always
92 * return the same hashCode over the lifetime of this object.
93 * <p>
94 * This method MUST be implemented in conjunction with
95 * {@link #equals(Object)} so that two equal RDFTerm produce the same hash
96 * code.
97 *
98 * @see IRI#hashCode()
99 * @see Literal#hashCode()
100 * @see BlankNode#hashCode()
101 *
102 * @return a hash code value for this RDFTerm.
103 */
104 @Override
105 int hashCode();
106
107 }