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