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.io.Serializable;
21 import java.util.Objects;
22 import java.util.Optional;
23
24 /**
25 * A RDF-1.1 Literal, as defined by
26 * <a href= "http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal"
27 * >RDF-1.1 Concepts and Abstract Syntax</a>, a W3C Recommendation published on
28 * 25 February 2014
29 *
30 * @see RDF#createLiteral(String)
31 * @see RDF#createLiteral(String, IRI)
32 * @see RDF#createLiteral(String, String)
33 */
34 public interface Literal extends RDFTerm {
35
36 /**
37 * The lexical form of this literal, represented by a
38 * <a href="http://www.unicode.org/versions/latest/">Unicode string</a>.
39 *
40 * @return The lexical form of this literal.
41 * @see <a href=
42 * "http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-form">RDF-1.1
43 * Literal lexical form</a>
44 */
45 String getLexicalForm();
46
47 /**
48 * The IRI identifying the datatype that determines how the lexical form
49 * maps to a literal value.
50 *
51 * If the datatype IRI is
52 * <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
53 * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>,
54 * {@link #getLanguageTag()} must not return {@link Optional#empty()}, and
55 * it must return a valid
56 * <a href="http://tools.ietf.org/html/bcp47">BCP47</a> language tag.
57 *
58 * @return The datatype IRI for this literal.
59 * @see <a href=
60 * "http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri">RDF-1.1
61 * Literal datatype IRI</a>
62 */
63 IRI getDatatype();
64
65 /**
66 * If and only if the datatype IRI is
67 * <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
68 * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>, the language
69 * tag for this Literal is a non-empty language tag as defined by
70 * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>.<br>
71 * If the datatype IRI is not
72 * <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
73 * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>, this method
74 * must return {@link Optional#empty()}.
75 *
76 * Implementation note: If your application requires {@link Serializable}
77 * objects, it is best not to store an {@link Optional} in a field. It is
78 * recommended to use {@link Optional#ofNullable(Object)} to create the
79 * return value for this method.
80 *
81 * @return The {@link Optional} language tag for this literal. If
82 * {@link Optional#isPresent()} returns true, the value returned by
83 * {@link Optional#get()} must be a non-empty string conforming to
84 * BCP47.
85 * @see <a href=
86 * "http://www.w3.org/TR/rdf11-concepts/#dfn-language-tag">RDF-1.1
87 * Literal language tag</a>
88 */
89 Optional<String> getLanguageTag();
90
91 /**
92 * Check it this Literal is equal to another Literal. <blockquote>
93 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-literal-term">Literal
94 * term equality</a>: Two literals are term-equal (the same RDF literal) if
95 * and only if the two lexical forms, the two datatype IRIs, and the two
96 * language tags (if any) compare equal, character by character. Thus, two
97 * literals can have the same value without being the same RDF term.
98 * </blockquote>
99 *
100 * Implementations MUST also override {@link #hashCode()} so that two equal
101 * Literals produce the same hash code.
102 *
103 * @param other
104 * Another object
105 * @return true if other is a Literal and is equal to this
106 * @see Object#equals(Object)
107 */
108 @Override
109 public boolean equals(Object other);
110
111 /**
112 * Calculate a hash code for this Literal.
113 * <p>
114 * The returned hash code MUST be equal to the result of
115 * {@link Objects#hash(Object...)} with the arguments
116 * {@link #getLexicalForm()}, {@link #getDatatype()},
117 * {@link #getLanguageTag()}.
118 * <p>
119 * This method MUST be implemented in conjunction with
120 * {@link #equals(Object)} so that two equal Literals produce the same hash
121 * code.
122 *
123 * @return a hash code value for this Literal.
124 * @see Object#hashCode()
125 * @see Objects#hash(Object...)
126 */
127 @Override
128 public int hashCode();
129
130 }