Module org.firebirdsql.jaybird
Package org.firebirdsql.encodings

# Interface IEncodingFactory

All Known Implementing Classes:
  `EncodingFactory`

public interface IEncodingFactory
Interface for the EncodingFactory.

Note on naming convention: normally the prefix `I` for interfaces is avoided in Java, in this particular case I decided to use it as the concrete class `EncodingFactory` is the actual factory and the main access for encoding related information. This interface is used for connection specific factories (e.g. so the defaultEncoding is the connection character set).

Since:
  3.0
Author:
  Mark Rotteveel

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Encoding`
  `getDefaultEncoding()`
  `EncodingDefinition`
  `getDefaultEncodingDefinition()`
  Returns the `EncodingDefinition` for the default platform character set.
  `EncodingDefinition`
  `getEncodingDefinition(String firebirdEncodingName, String javaCharsetAlias)`
  Gets or creates an `EncodingDefinition` for the supplied Firebird encoding and Java charset.
  `EncodingDefinition`
  `getEncodingDefinitionByCharacterSetId(int firebirdCharacterSetId)`
  Looks up the `EncodingDefinition` for the specified Firebird character set id.
  `EncodingDefinition`
  `getEncodingDefinitionByCharset(Charset charset)`
  Looks up an `EncodingDefinition` for the Java `Charset`.
  `EncodingDefinition`
  `getEncodingDefinitionByCharsetAlias(String charsetAlias)`
  Looks up the `EncodingDefinition` by the specified Java character set name or alias.
  `EncodingDefinition`
  `getEncodingDefinitionByFirebirdName(String firebirdEncodingName)`
  Looks up the `EncodingDefinition` for the specified Firebird encoding name.
  `Encoding`
  `getEncodingForCharacterSetId(int firebirdCharacterSetId)`
  Gets an `Encoding` for the specified Firebird character set id.
  `Encoding`
  `getEncodingForCharset(Charset charset)`
  Gets an `Encoding` for the specified Java character set.
  `Encoding`
  `getEncodingForCharset(Charset charset, Encoding fallbackEncoding)`
  Gets an `Encoding` for the specified Java character set.
  `Encoding`
  `getEncodingForCharsetAlias(String charsetAlias)`
  Gets an `Encoding` for the specified Java character set name or alias.
  `Encoding`
  `getEncodingForFirebirdName(String firebirdEncodingName)`
  Gets an `Encoding` for the specified Firebird encoding.
  `<T extends DatatypeCoder>
  T`
  `getOrCreateDatatypeCoder(Class<T> datatypeCoderClass, Function<IEncodingFactory,T> datatypeCoderFactory)`
  Gets or - if necessary - creates a datatype coder of the specified type.
  `Encoding`
  `getOrCreateEncodingForCharset(Charset charset)`
  Creates an `Encoding` for the specified Java character set.
  `IEncodingFactory`
  `withDefaultEncodingDefinition(Charset charset)`
  Returns an `IEncodingFactory` that uses an `EncodingDefinition` identified by `charSet` as the default.
  `IEncodingFactory`
  `withDefaultEncodingDefinition(EncodingDefinition encodingDefinition)`
  Returns an `IEncodingFactory` that uses `encodingDefinition` as the default.

- ## Method Details

  - ### getDefaultEncoding

    Encoding getDefaultEncoding()
    Returns:
      The `Encoding` for `Charset.defaultCharset()`.

  - ### getDefaultEncodingDefinition

    EncodingDefinition getDefaultEncodingDefinition()
    Returns the `EncodingDefinition` for the default platform character set.

    If the default character set is not supported by Jaybird, an instance of EncodingDefinition should be returned with Firebird encoding name `"NONE"`.

    Returns:
      The `EncodingDefinition` for `Charset.defaultCharset()`.

  - ### getEncodingDefinitionByFirebirdName

    EncodingDefinition getEncodingDefinitionByFirebirdName(String firebirdEncodingName)
    Looks up the `EncodingDefinition` for the specified Firebird encoding name.
    Parameters:
      `firebirdEncodingName` - The Firebird encoding name (case-insensitive)
    Returns:
      EncodingDefinition instance or `null` if the encoding name is unknown

  - ### getEncodingForFirebirdName

    Encoding getEncodingForFirebirdName(String firebirdEncodingName)
    Gets an `Encoding` for the specified Firebird encoding. If there is no known encoding for this name, or the loaded EncodingDefinition is information-only, then the defaultEncoding is used.
    Parameters:
      `firebirdEncodingName` - The Firebird encoding name (case-insensitive)
    Returns:
      Encoding instance (never null)

  - ### getEncodingDefinitionByCharacterSetId

    EncodingDefinition getEncodingDefinitionByCharacterSetId(int firebirdCharacterSetId)
    Looks up the `EncodingDefinition` for the specified Firebird character set id.

    Implementations that do not know the connection character set should return `null` for the value `ISCConstants.CS_dynamic` (= 127), as that is the indicator to use the connection character set.

    Parameters:
      `firebirdCharacterSetId` - Firebird character set id
    Returns:
      EncodingDefinition instance or `null` if the character set id is unknown or `127` and this implementation doesn't know the connection character set.

  - ### getEncodingForCharacterSetId

    Encoding getEncodingForCharacterSetId(int firebirdCharacterSetId)
    Gets an `Encoding` for the specified Firebird character set id. If there is no known encoding for this character set id (or if it is 127, see `getEncodingDefinitionByCharacterSetId(int)`), or the loaded EncodingDefinition is information-only, then the defaultEncoding will be used.
    Parameters:
      `firebirdCharacterSetId` - The Firebird character set id
    Returns:
      Encoding instance (never null)

  - ### getEncodingDefinitionByCharset

    EncodingDefinition getEncodingDefinitionByCharset(Charset charset)
    Looks up an `EncodingDefinition` for the Java `Charset`.
    Parameters:
      `charset` - The Java character set
    Returns:
      EncodingDefinition instance or `null` if the character set is not mapped

  - ### getEncodingForCharset

    Encoding getEncodingForCharset(Charset charset, Encoding fallbackEncoding)
    Gets an `Encoding` for the specified Java character set. If there is no known encoding for this `Charset`, or the loaded EncodingDefinition is information-only, then the fallbackEncoding will be used.
    Parameters:
      `charset` - The Java character set
      `fallbackEncoding` - The Encoding to use as fallback if no encoding is found (usually the connection encoding). If `null`, the defaultEncoding for the JVM is used.
    Returns:
      Encoding instance (never null)
    See Also:
      - `getOrCreateEncodingForCharset(java.nio.charset.Charset)`

  - ### getEncodingForCharset

    Encoding getEncodingForCharset(Charset charset)
    Gets an `Encoding` for the specified Java character set. If there is no known encoding for this `Charset`, or the loaded EncodingDefinition is information-only, then the defaultEncoding will be used.
    Parameters:
      `charset` - The Java character set
    Returns:
      Encoding instance (never null)

  - ### getOrCreateEncodingForCharset

    Encoding getOrCreateEncodingForCharset(Charset charset)
    Creates an `Encoding` for the specified Java character set. If there is no known encoding for this charset, then an Encoding instance based on the charset is returned.

    In general the method `getEncodingForCharset(java.nio.charset.Charset, Encoding)` should be used.

    Don't confuse this method with `getEncodingForCharset(Charset)`, which falls back to the default encoding.

    Parameters:
      `charset` - The Java character set
    Returns:
      Encoding instance (never null)
    See Also:
      - `getEncodingForCharset(java.nio.charset.Charset, Encoding)`

  - ### getEncodingDefinitionByCharsetAlias

    EncodingDefinition getEncodingDefinitionByCharsetAlias(String charsetAlias)
    Looks up the `EncodingDefinition` by the specified Java character set name or alias.
    Parameters:
      `charsetAlias` - Name (or alias) of the Java character set (case-insensitive)
    Returns:
      EncodingDefinition instance or `null` if the character set name is not mapped

  - ### getEncodingForCharsetAlias

    Encoding getEncodingForCharsetAlias(String charsetAlias)
    Gets an `Encoding` for the specified Java character set name or alias. If there is no known encoding for this name, or the loaded EncodingDefinition is information-only, then the defaultEncoding will be used.
    Parameters:
      `charsetAlias` - The Java character set name or alias
    Returns:
      Encoding instance (never null)

  - ### getEncodingDefinition

    EncodingDefinition getEncodingDefinition(String firebirdEncodingName, String javaCharsetAlias)
    Gets or creates an `EncodingDefinition` for the supplied Firebird encoding and Java charset.

    When `firebirdEncodingName` is not null and `javaCharsetAlias` is null, then the encoding definition as returned by `getEncodingDefinitionByFirebirdName(String)` is returned. For the reverse (`firebirdEncodingName` is null and `javaCharsetAlias` isn't), the encoding definition as returned by `getEncodingDefinitionByCharsetAlias(String)` is returned.

    When both parameters are set, the result of `getEncodingDefinitionByFirebirdName(String)` is returned if the character set matches, otherwise a new `DefaultEncodingDefinition` is created based on its information, but with the specified character set. This can be useful for attempting to fix encoding issues in Firebird.

    If either of the parameters cannot be resolved, to an EncodingDefinition or `Charset`, or the EncodingDefinition is information-only - with the exception of Firebird encoding NONE - and no Java Charset is specified, then null is returned.

    Parameters:
      `firebirdEncodingName` - Name of the Firebird encoding, or null to defer decision to the java Charset alias
      `javaCharsetAlias` - Alias of the Java character set, or null to defer decision to the Firebird encoding
    Returns:
      An EncodingDefinition or null if both parameters are null, no encoding was found or if an exception occurred.

  - ### withDefaultEncodingDefinition

    IEncodingFactory withDefaultEncodingDefinition(EncodingDefinition encodingDefinition)
    Returns an `IEncodingFactory` that uses `encodingDefinition` as the default.
    Parameters:
      `encodingDefinition` - The default encoding to use (or `null` for the value of `getDefaultEncoding()`
    Returns:
      IEncodingFactory instance with the specified default.

  - ### withDefaultEncodingDefinition

    IEncodingFactory withDefaultEncodingDefinition(Charset charset)
    Returns an `IEncodingFactory` that uses an `EncodingDefinition` identified by `charSet` as the default.
    Parameters:
      `charset` - The default charset to use.
    Returns:
      IEncodingFactory instance with the specified default.

  - ### getOrCreateDatatypeCoder

    <T extends DatatypeCoder> T getOrCreateDatatypeCoder(Class<T> datatypeCoderClass, Function<IEncodingFactory,T> datatypeCoderFactory)
    Gets or - if necessary - creates a datatype coder of the specified type.

    In general this method should only be called from a static factory method on the datatype coder itself.

    Type Parameters:
      `T` - type parameter of type `DatatypeCoder`
    Parameters:
      `datatypeCoderClass` - type of datatype coder
      `datatypeCoderFactory` - function for creating the datatype coder if it doesn't already exist
    Returns:
      New or cached instance of datatype coder
    Since:
      6