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.io.Serializable;
021import java.util.Objects;
022import java.util.Optional;
023
024/**
025 * A RDF-1.1 Literal, as defined by
026 * <a href= "http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal"
027 * >RDF-1.1 Concepts and Abstract Syntax</a>, a W3C Recommendation published on
028 * 25 February 2014
029 * 
030 * @see RDF#createLiteral(String)
031 * @see RDF#createLiteral(String, IRI)
032 * @see RDF#createLiteral(String, String)
033 */
034public interface Literal extends RDFTerm {
035
036    /**
037     * The lexical form of this literal, represented by a
038     * <a href="http://www.unicode.org/versions/latest/">Unicode string</a>.
039     *
040     * @return The lexical form of this literal.
041     * @see <a href=
042     *      "http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-form">RDF-1.1
043     *      Literal lexical form</a>
044     */
045    String getLexicalForm();
046
047    /**
048     * The IRI identifying the datatype that determines how the lexical form
049     * maps to a literal value.
050     *
051     * If the datatype IRI is
052     * <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
053     * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>,
054     * {@link #getLanguageTag()} must not return {@link Optional#empty()}, and
055     * it must return a valid
056     * <a href="http://tools.ietf.org/html/bcp47">BCP47</a> language tag.
057     *
058     * @return The datatype IRI for this literal.
059     * @see <a href=
060     *      "http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri">RDF-1.1
061     *      Literal datatype IRI</a>
062     */
063    IRI getDatatype();
064
065    /**
066     * If and only if the datatype IRI is
067     * <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
068     * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>, the language
069     * tag for this Literal is a non-empty language tag as defined by
070     * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>.<br>
071     * If the datatype IRI is not
072     * <a href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
073     * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>, this method
074     * must return {@link Optional#empty()}.
075     *
076     * Implementation note: If your application requires {@link Serializable}
077     * objects, it is best not to store an {@link Optional} in a field. It is
078     * recommended to use {@link Optional#ofNullable(Object)} to create the
079     * return value for this method.
080     *
081     * @return The {@link Optional} language tag for this literal. If
082     *         {@link Optional#isPresent()} returns true, the value returned by
083     *         {@link Optional#get()} must be a non-empty string conforming to
084     *         BCP47.
085     * @see <a href=
086     *      "http://www.w3.org/TR/rdf11-concepts/#dfn-language-tag">RDF-1.1
087     *      Literal language tag</a>
088     */
089    Optional<String> getLanguageTag();
090
091    /**
092     * Check it this Literal is equal to another Literal. <blockquote>
093     * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-literal-term">Literal
094     * term equality</a>: Two literals are term-equal (the same RDF literal) if
095     * and only if the two lexical forms, the two datatype IRIs, and the two
096     * language tags (if any) compare equal, character by character. Thus, two
097     * literals can have the same value without being the same RDF term.
098     * </blockquote>
099     *
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}