Package org.eclipse.rdf4j.rio

## Interface LanguageHandler

- All Known Implementing Classes:
    `BCP47LanguageHandler`, `RFC3066LanguageHandler`

      public interface LanguageHandler

  An interface defining methods related to verification and normalization of language tags.

  The language handler may optionally provide normalization and verification services for string literals based on the language tags, including translation, grammar and spelling checks. However, this behavior is entirely driven by the user.

  Author:
    Peter Ansell

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `BCP47` | Identifier for the language tag format defined by BCP47, which is referenced by the RDF-1.1 specification.
    `static String` | `RFC3066` | Identifier for the language tag format defined by RFC3066, which is referenced by the RDF-1.0 specification.
    `static String` | `RFC4646` | Identifier for the language tag format defined by RFC4646, which obsoletes RFC3066, but which is not referenced by the RDF specification.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `getKey()` | A unique key for this language handler to identify it in the LanguageHandlerRegistry.
    `boolean` | `isRecognizedLanguage​(String languageTag)` | Checks if the given language tag is recognized by this language handler, including cases where the language tag is considered syntactically well-formed, but is not yet normalized.
    `Literal` | `normalizeLanguage​(String literalValue, String languageTag, ValueFactory valueFactory)` | Normalize both the language tag and the language if appropriate, and use the given value factory to generate a literal matching the literal value and language tag.
    `boolean` | `verifyLanguage​(String literalValue, String languageTag)` | Verifies that the language tag is syntactically well-formed, optionally including an automated check on the literal value being a match for the given tag.

- - ### Field Detail

    - #### RFC3066

          static final String RFC3066

      Identifier for the language tag format defined by RFC3066, which is referenced by the RDF-1.0 specification.
      See Also:
        Constant Field Values

    - #### RFC4646

          static final String RFC4646

      Identifier for the language tag format defined by RFC4646, which obsoletes RFC3066, but which is not referenced by the RDF specification.
      See Also:
        Constant Field Values

    - #### BCP47

          static final String BCP47

      Identifier for the language tag format defined by BCP47, which is referenced by the RDF-1.1 specification.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isRecognizedLanguage

          boolean isRecognizedLanguage​(String languageTag)

      Checks if the given language tag is recognized by this language handler, including cases where the language tag is considered syntactically well-formed, but is not yet normalized.
      Parameters:
        `languageTag` - The language tag to check.
      Returns:
        True if the language tag is syntactically well-formed and could be used with `verifyLanguage(String, String)` and `normalizeLanguage(String, String, ValueFactory)`.

    - #### verifyLanguage

          boolean verifyLanguage​(String literalValue,
                                 String languageTag)
                          throws LiteralUtilException

      Verifies that the language tag is syntactically well-formed, optionally including an automated check on the literal value being a match for the given tag.

      This method must only be called after verifying that `isRecognizedLanguage(String)` returns true for the given language tag.

      Parameters:
        `literalValue` - Literal value matching the given language tag.
        `languageTag` - A language tag that matched with `isRecognizedLanguage(String)`.
      Returns:
        True if the language tag is recognized by this language handler, and it is verified to be syntactically valid.
      Throws:
        `LiteralUtilException` - If the language tag was not recognized.

    - #### normalizeLanguage

          Literal normalizeLanguage​(String literalValue,
                                    String languageTag,
                                    ValueFactory valueFactory)
                             throws LiteralUtilException

      Normalize both the language tag and the language if appropriate, and use the given value factory to generate a literal matching the literal value and language tag.

      This method must only be called after verifying that `isRecognizedLanguage(String)` returns true for the given language tag, and `verifyLanguage(String, String)` also returns true for the given language and literal value.

      Parameters:
        `literalValue` - Required literal value to use in the normalization process and to provide the value for the resulting literal.
        `languageTag` - The language tag which is to be normalized. This tag is available in normalized form from the result using `Literal.getLanguage()`.
        `valueFactory` - The `ValueFactory` to use to create the result literal.
      Returns:
        A `Literal` containing the normalized literal value and language tag.
      Throws:
        `LiteralUtilException` - If the language tag was not recognized or verified, or the literal value could not be normalized due to an error.

    - #### getKey

          String getKey()

      A unique key for this language handler to identify it in the LanguageHandlerRegistry.
      Returns:
        A unique string key.