Package com.stardog.stark

# Interface Literal

All Superinterfaces:
  `Serializable`, `Value`

All Known Implementing Classes:
  `ArrayLiteral`

public interface Literal extends Value

A literal value in an RDF graph

Since:
  1.0
Version:
  1.0
Author:
  Michael Grove
See Also:
  - RDF Literal

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final boolean`
  `STRICT_TYPES`
  System setting that controls whether the casting methods of `Literal` such as `intValue(Literal)` are strict about the conversion.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `booleanValue(Literal theLiteral)`
  Get the value of the `Literal` as a `boolean`.
  `static byte`
  `byteValue(Literal theLiteral)`
  `static XMLGregorianCalendar`
  `calendarValue(Literal theLiteral)`
  Get the value of the `Literal` as a `calendar`.
  `Datatype`
  `datatype()`
  The datatype of the `Literal`.
  `default IRI`
  `datatypeIRI()`
  The IRI of the `Datatype` of the `Literal`.
  `static BigDecimal`
  `decimalValue(Literal theLiteral)`
  Get the value of the `Literal` as a `BigDecimal`.
  `static double`
  `doubleValue(Literal theLiteral)`
  Get the value of the `Literal` as a `double`.
  `static Duration`
  `durationValue(Literal theLiteral)`
  `static float`
  `floatValue(Literal theLiteral)`
  Get the value of the `Literal` as a `float`.
  `static BigInteger`
  `integerValue(Literal theLiteral)`
  Get the value of the `Literal` as a `BigInteger`.
  `static int`
  `intValue(Literal theLiteral)`
  `static boolean`
  `isLanguageLiteral(Literal theLiteral)`
  Sugar for `Literal.lang().isPresent()`
  `String`
  `label()`
  The lexical value of the literal
  `default Optional<String>`
  `lang()`
  Optionally, the language of the lexical value of the `Literal`.
  `static long`
  `longValue(Literal theLiteral)`
  `static int`
  `shortValue(Literal theLiteral)`
  `static String`
  `str(Literal theLiteral)`
  Return the `String` serialization of the `Literal`
  `static XMLCalendar`
  `xmlCalendarValue(Literal theLiteral)`
  Get the value of the `Literal` as a `calendar`.

- ## Field Details

  - ### STRICT_TYPES

    static final boolean STRICT_TYPES
    System setting that controls whether the casting methods of `Literal` such as `intValue(Literal)` are strict about the conversion. When `true`, if you try to get the `int` value of `"5"^^xsd:string` it will throw a `NumberFormatException` because the datatype of the `Literal` is incompatible with `int`. If `false` the `label()` will be used and passed to, in this example, ``Integer.parseInt(String)` which still may throw a `NumberFormatException` if the value of the `Literal` is not a valid numeric value. The default value is `false`.

- ## Method Details

  - ### label

    @Nonnull String label()
    The lexical value of the literal
    Returns:
      the lexical value

  - ### lang

    @Nonnull default Optional<String> lang()
    Optionally, the language of the lexical value of the `Literal`. When present, the `datatype()` is `RDF.LANG_STRING`.
    Returns:
      the language of the literal
    See Also:
      - RDF Language

  - ### datatypeIRI

    @Nonnull default IRI datatypeIRI()
    The IRI of the `Datatype` of the `Literal`. Often, this is syntactic sugar for `datatype().iri()` however, in the case where it is a user defined datatype, eg `Datatype.UDF` this will return the specific IRI of the datatype.
    Returns:
      the datatype IRI of the lexical value

  - ### datatype

    @Nonnull Datatype datatype()
    The datatype of the `Literal`. Some serializations of RDF use a "simple literal" which is a literal with no explicit datatype. That is just syntactic sugar for `xsd:string` typed literals.
    Returns:
      the Datatype

  - ### str

    @Nonnull static String str(@Nonnull Literal theLiteral)
    Return the `String` serialization of the `Literal`
    Parameters:
      `theLiteral` - the `Literal` to serialize
    Returns:
      the serialized `Literal`

  - ### isLanguageLiteral

    static boolean isLanguageLiteral(@Nonnull Literal theLiteral)
    Sugar for `Literal.lang().isPresent()`
    Parameters:
      `theLiteral` - the literal
    Returns:
      whether it's a language tagged literal

  - ### booleanValue

    static boolean booleanValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `boolean`.
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    See Also:
      - `BooleanLiteral`

  - ### calendarValue

    static XMLGregorianCalendar calendarValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `calendar`.
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    Throws:
      `IllegalArgumentException` - if the literal is not a calendar datatype
    See Also:
      - `CalendarLiteral`
      - `XMLDatatypes.isCalendarDatatype(Datatype)`

  - ### xmlCalendarValue

    @Nonnull static XMLCalendar xmlCalendarValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `calendar`. Defers the creation of XMLGregorianCalendar if possible
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    Throws:
      `IllegalArgumentException` - if the literal is not a calendar datatype
    See Also:
      - `CalendarLiteral`
      - `XMLDatatypes.isCalendarDatatype(Datatype)`

  - ### intValue

    static int intValue(@Nonnull Literal theLiteral)

  - ### byteValue

    static byte byteValue(@Nonnull Literal theLiteral)

  - ### shortValue

    static int shortValue(@Nonnull Literal theLiteral)

  - ### longValue

    static long longValue(@Nonnull Literal theLiteral)

  - ### durationValue

    @Nonnull static Duration durationValue(@Nonnull Literal theLiteral)

  - ### floatValue

    static float floatValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `float`.
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    Throws:
      `NumberFormatException` - if the literal is not a numeric datatype

  - ### doubleValue

    static double doubleValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `double`.
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    Throws:
      `NumberFormatException` - if the literal is not a numeric datatype

  - ### integerValue

    static BigInteger integerValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `BigInteger`.
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    Throws:
      `NumberFormatException` - if the literal is not a numeric datatype

  - ### decimalValue

    static BigDecimal decimalValue(@Nonnull Literal theLiteral)
    Get the value of the `Literal` as a `BigDecimal`.
    Parameters:
      `theLiteral` - the literal
    Returns:
      the value
    Throws:
      `NumberFormatException` - if the literal is not a numeric datatype