org.eclipse.rdf4j.model.Literal Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2015 Eclipse RDF4J contributors, Aduna, and others.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Distribution License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: BSD-3-Clause
*******************************************************************************/
package org.eclipse.rdf4j.model;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.time.DateTimeException;
import java.time.Duration;
import java.time.OffsetDateTime;
import java.time.temporal.TemporalAccessor;
import java.time.temporal.TemporalAmount;
import java.util.Optional;
import javax.xml.datatype.XMLGregorianCalendar;
import org.eclipse.rdf4j.model.base.CoreDatatype;
/**
* An RDF-1.1 literal consisting of a label (the lexical value), a datatype, and optionally a language tag.
*
*
* Value accessor methods (for instance, {@link #booleanValue()}) map literal lexical values conforming to the syntax of
* a supported XML Schema 1.1 datatype to a corresponding Java object.
*
*
* @author Arjohn Kampman
* @implSpec In order to ensure interoperability of concrete classes implementing this interface,
* {@link #equals(Object)} and {@link #hashCode()} methods must be implemented exactly as described in their
* specs.
* @see RDF-1.1 Concepts and Abstract Syntax
* @see RDF 1.1 Concepts and Abstract Syntax - §5.1
* The XML Schema Built-in Datatypes
* @see XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes
*/
public interface Literal extends Value {
@Override
default boolean isLiteral() {
return true;
}
/**
* Gets the label (the lexical value) of this literal.
*
* @return The literal's label.
*/
String getLabel();
/**
* Gets the language tag for this literal, normalized to lower case.
*
* @return The language tag for this literal, or {@link Optional#empty()} if it doesn't have one.
*/
Optional getLanguage();
/**
* Gets the datatype for this literal.
*
* If {@link #getLanguage()} returns a non-empty value than this must return
* {@code rdf:langString}. If no datatype was
* assigned to this literal by the creator, then this method must return
* {@code xsd:string}.
*
* @return The datatype for this literal.
*/
IRI getDatatype();
/**
* Returns the boolean value of this literal.
*
* @return The boolean value of the literal.
* @throws IllegalArgumentException If the literal's label cannot be represented by a boolean .
*/
boolean booleanValue();
/**
* Returns the byte value of this literal.
*
* @return The byte value of the literal.
* @throws NumberFormatException If the literal cannot be represented by a byte.
*/
byte byteValue();
/**
* Returns the short value of this literal.
*
* @return The short value of the literal.
* @throws NumberFormatException If the literal's label cannot be represented by a short.
*/
short shortValue();
/**
* Returns the int value of this literal.
*
* @return The int value of the literal.
* @throws NumberFormatException If the literal's label cannot be represented by a int.
*/
int intValue();
/**
* Returns the long value of this literal.
*
* @return The long value of the literal.
* @throws NumberFormatException If the literal's label cannot be represented by to a long .
*/
long longValue();
/**
* Returns the integer value of this literal.
*
* @return The integer value of the literal.
* @throws NumberFormatException If the literal's label is not a valid integer.
*/
BigInteger integerValue();
/**
* Returns the decimal value of this literal.
*
* @return The decimal value of the literal.
* @throws NumberFormatException If the literal's label is not a valid decimal.
*/
BigDecimal decimalValue();
/**
* Returns the float value of this literal.
*
* @return The float value of the literal.
* @throws NumberFormatException If the literal's label cannot be represented by a float.
*/
float floatValue();
/**
* Returns the double value of this literal.
*
* @return The double value of the literal.
* @throws NumberFormatException If the literal's label cannot be represented by a double.
*/
double doubleValue();
/**
* Retrieves the {@link TemporalAccessor temporal accessor} value of this literal.
*
*
* A temporal accessor representation can be given for literals whose label conforms to the syntax of the following
* XML Schema 1.1 date/time datatypes:
*
*
*
*
* - xsd:dateTime,
* - xsd:time,
* - xsd:date,
*
* - xsd:gYearMonth,
* - xsd:gYear,
* - xsd:gMonthDay,
* - xsd:gDay,
* - xsd:gMonth.
*
*
*
*
* Temporal accessor representations may be converted to specific {@link java.time} values like
* {@link OffsetDateTime} using target static factory methods, for instance
* {@code OffsetDateTime.from(literal.temporalAccessorValue())}.
*
*
*
* Note however that {@link java.time} doesn't include dedicated classes for some legal XML Schema date/time values,
* like offset dates (for instance, {@code 2020-11-16+01:00}) and {@code xsd:gDay} (for instance, {@code ---16}).
*
*
* @return the temporal accessor value of this literal
* @throws DateTimeException if this literal cannot be represented by a {@link TemporalAccessor} value
* @author Alessandro Bollini
* @apiNote the xsd:dateTimeStamp datatype
* (supported by calendar-based {@linkplain #calendarValue() value accessor} and
* {@linkplain ValueFactory#createLiteral(XMLGregorianCalendar) factory methods}) was specified by
* XML Schema Definition Language (XSD) 1.1 Part 2:
* Datatypes and later removed from XML Schema Part 2:
* Datatypes Second Edition: it is not included among temporal datatypes automatically assigned by
* {@link ValueFactory#createLiteral(TemporalAmount)} in order to provide better interoperability with the
* latter version of the standard.
* @implSpec The default method implementation throws an {@link UnsupportedOperationException} and is only supplied
* as a stop-gap measure for backward compatibility: concrete classes implementing this interface are
* expected to override it.
* @see The Java™ Tutorials – Trail: Date Time
* @since 3.5.0
*/
default TemporalAccessor temporalAccessorValue() throws DateTimeException {
throw new UnsupportedOperationException();
}
/**
* Retrieves the {@link TemporalAmount temporal amount} value of this literal.
*
*
* A temporal amount representation can be given for literals whose label conforms to the syntax of the
* XML Schema 2
* xsd:duration datatype.
*
*
*
* The adoption of the XML Schema 2 definition is a known deviation
* from the RDF 1.1 standard;
* well-formedness rules are relaxed to consider all duration components as optional and freely mixable.
*
*
*
* Temporal amount representations may be converted to specific {@link java.time} values like {@link Duration} using
* target static factory methods, for instance {@code Duration.from(literal.temporalAmountValue())}.
*
*
*
* Note however that {@link java.time} doesn't include dedicated classes for legal XML Schema duration values
* including both date and time components (for instance, {@code P1YT23H}).
*
*
* @return the temporal amount value of this literal
* @throws DateTimeException if this literal cannot be represented by a {@link TemporalAmount} value
* @author Alessandro Bollini
* @apiNote xsd:yearMonthDuration and
* xsd:xsd:dayTimeDuration datatypes
* (supported by calendar-based {@linkplain #calendarValue() value accessor} and
* {@linkplain ValueFactory#createLiteral(XMLGregorianCalendar) factory methods}) were specified by
* XML Schema Definition Language (XSD) 1.1 Part 2:
* Datatypes and later removed from XML Schema Part 2:
* Datatypes Second Edition: they are not included among temporal datatypes automatically assigned by
* {@link ValueFactory#createLiteral(TemporalAmount)} in order to provide better interoperability with the
* latter version of the standard; interoperability with
* SPARQL 1.1 Query Language §17.4.5.8
* timezone is not compromised, as the legacy {@code xsd:dayTimeDuration} return datatype is defined as
* a restriction of the {@code xds:duration} datatype.
* @implSpec The default method implementation throws an {@link UnsupportedOperationException} and is only supplied
* as a stop-gap measure for backward compatibility: concrete classes implementing this interface are
* expected to override it.
* @see The Java™ Tutorials – Trail: Date Time
* @since 3.5.0
*/
default TemporalAmount temporalAmountValue() throws DateTimeException {
throw new UnsupportedOperationException();
}
/**
* Returns the {@link XMLGregorianCalendar} value of this literal. A calendar representation can be given for
* literals whose label conforms to the syntax of the following XML
* Schema datatypes: dateTime, time, date, gYearMonth,
* gMonthDay, gYear, gMonth or gDay.
*
* @return The calendar value of the literal.
* @throws IllegalArgumentException If the literal cannot be represented by a {@link XMLGregorianCalendar}.
*/
XMLGregorianCalendar calendarValue();
/**
* CoreDatatype is an interface for natively supported datatypes in RDF4J. This includes, among others, the XML
* Schema datatypes and rdf:langString. CoreDatatypes are implemented as enums and more performant and convenient to
* work with than IRI-based datatypes. The constant {@link CoreDatatype#NONE)} is used to represent a datatype that
* is not one of the supported core datatypes.
*
* @return The CoreDatatype or {@link CoreDatatype#NONE)} if the datatype matches none of the core datatypes. This
* method will not return null.
* @implNote This method may not return null. Returning {@link CoreDatatype#NONE)} is only permitted if the datatype
* does not match any of the core datatypes. A literal with a language tag must return
* {@link CoreDatatype.RDF#LANGSTRING)}. A literal without a specified datatype must return
* {@link CoreDatatype.XSD#STRING)}.
*/
CoreDatatype getCoreDatatype();
/**
* Compares this literal to another object.
*
* @param other the object to compare this literal to
* @return {@code true}, if the other object is an instance of {@code Literal} and if their {@linkplain #getLabel()
* labels}, {@linkplain #getLanguage() language tags} and {@linkplain #getDatatype() datatypes} are equal
*/
@Override
boolean equals(Object other);
/**
* Computes the hash code of this literal.
*
* @return a hash code for this literal computed as {@link #getLabel()}{@code .hashCode()}
* @implNote {@linkplain #getLanguage() language} and {@linkplain #getDatatype() datatype} are deliberately not
* considered in the computation (see issue
* #655)
*/
@Override
int hashCode();
}