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}