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

# Class EncodingFactory

java.lang.Object
org.firebirdsql.encodings.EncodingFactory

All Implemented Interfaces:
  `IEncodingFactory`

public final class EncodingFactory extends Object implements IEncodingFactory
Factory for `EncodingDefinition` and `Encoding`.

Author:
  Mark Rotteveel

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ENCODING_NAME_NONE`
  `static final String`
  `ENCODING_NAME_OCTETS`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static IEncodingFactory`
  `createInstance(Charset charset)`
  Returns an `IEncodingFactory` that uses an `EncodingDefinition` identified by `charSet` as the default.
  `static IEncodingFactory`
  `createInstance(EncodingDefinition encodingDefinition)`
  Returns an `IEncodingFactory` that uses `encodingDefinition` as the default.
  `static EncodingFactory`
  `createInstance(EncodingSet... encodingSets)`
  Creates a new EncodingFactory based on the supplied encodingSets.
  `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`
  `getEncodingForCharacterSetId(int firebirdCharacterSetId, Encoding fallbackEncoding)`
  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`
  `getEncodingForCharsetAlias(String charsetAlias, Encoding fallbackEncoding)`
  Gets an `Encoding` for the specified Java character set name or alias.
  `Encoding`
  `getEncodingForFirebirdName(String firebirdEncodingName)`
  Gets an `Encoding` for the specified Firebird encoding.
  `Encoding`
  `getEncodingForFirebirdName(String firebirdEncodingName, Encoding fallbackEncoding)`
  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.
  `static IEncodingFactory`
  `getPlatformDefault()`
  Returns an instance of `IEncodingFactory` with the default encoding set to the platform encoding.
  `static Encoding`
  `getPlatformEncoding()`
  `IEncodingFactory`
  `withDefaultEncodingDefinition()`
  Returns an `ConnectionEncodingFactory` that uses `getDefaultEncodingDefinition()` as the default.
  `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.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### ENCODING_NAME_NONE

    public static final String ENCODING_NAME_NONE
    See Also:
      - Constant Field Values

  - ### ENCODING_NAME_OCTETS

    public static final String ENCODING_NAME_OCTETS
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getDefaultEncoding

    public Encoding getDefaultEncoding()
    Specified by:
      `getDefaultEncoding` in interface `IEncodingFactory`
    Returns:
      The `Encoding` for `Charset.defaultCharset()`.

  - ### getPlatformEncoding

    public static Encoding getPlatformEncoding()
    Returns:
      The default encoding of the platform.

  - ### getDefaultEncodingDefinition

    public EncodingDefinition getDefaultEncodingDefinition()
    Description copied from interface: `IEncodingFactory`
    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"`.

    Specified by:
      `getDefaultEncodingDefinition` in interface `IEncodingFactory`
    Returns:
      The `EncodingDefinition` for `Charset.defaultCharset()`.

  - ### getEncodingDefinitionByFirebirdName

    public EncodingDefinition getEncodingDefinitionByFirebirdName(String firebirdEncodingName)
    Description copied from interface: `IEncodingFactory`
    Looks up the `EncodingDefinition` for the specified Firebird encoding name.
    Specified by:
      `getEncodingDefinitionByFirebirdName` in interface `IEncodingFactory`
    Parameters:
      `firebirdEncodingName` - The Firebird encoding name (case-insensitive)
    Returns:
      EncodingDefinition instance or `null` if the encoding name is unknown

  - ### getEncodingForFirebirdName

    public Encoding getEncodingForFirebirdName(String firebirdEncodingName, Encoding fallbackEncoding)
    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 fallbackEncoding.
    Parameters:
      `firebirdEncodingName` - The Firebird encoding name (case-insensitive)
      `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)

  - ### getEncodingForFirebirdName

    public Encoding getEncodingForFirebirdName(String firebirdEncodingName)
    Description copied from interface: `IEncodingFactory`
    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.
    Specified by:
      `getEncodingForFirebirdName` in interface `IEncodingFactory`
    Parameters:
      `firebirdEncodingName` - The Firebird encoding name (case-insensitive)
    Returns:
      Encoding instance (never null)

  - ### getEncodingDefinitionByCharacterSetId

    public EncodingDefinition getEncodingDefinitionByCharacterSetId(int firebirdCharacterSetId)
    Description copied from interface: `IEncodingFactory`
    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.

    Specified by:
      `getEncodingDefinitionByCharacterSetId` in interface `IEncodingFactory`
    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

    public Encoding getEncodingForCharacterSetId(int firebirdCharacterSetId, Encoding fallbackEncoding)
    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 fallbackEncoding will be used.
    Parameters:
      `firebirdCharacterSetId` - The Firebird character set id
      `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)

  - ### getEncodingForCharacterSetId

    public Encoding getEncodingForCharacterSetId(int firebirdCharacterSetId)
    Description copied from interface: `IEncodingFactory`
    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 `IEncodingFactory.getEncodingDefinitionByCharacterSetId(int)`), or the loaded EncodingDefinition is information-only, then the defaultEncoding will be used.
    Specified by:
      `getEncodingForCharacterSetId` in interface `IEncodingFactory`
    Parameters:
      `firebirdCharacterSetId` - The Firebird character set id
    Returns:
      Encoding instance (never null)

  - ### getEncodingDefinitionByCharset

    public EncodingDefinition getEncodingDefinitionByCharset(Charset charset)
    Description copied from interface: `IEncodingFactory`
    Looks up an `EncodingDefinition` for the Java `Charset`.
    Specified by:
      `getEncodingDefinitionByCharset` in interface `IEncodingFactory`
    Parameters:
      `charset` - The Java character set
    Returns:
      EncodingDefinition instance or `null` if the character set is not mapped

  - ### getEncodingForCharset

    public Encoding getEncodingForCharset(Charset charset, Encoding fallbackEncoding)
    Description copied from interface: `IEncodingFactory`
    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.
    Specified by:
      `getEncodingForCharset` in interface `IEncodingFactory`
    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:
      - `IEncodingFactory.getOrCreateEncodingForCharset(java.nio.charset.Charset)`

  - ### getEncodingForCharset

    public Encoding getEncodingForCharset(Charset charset)
    Description copied from interface: `IEncodingFactory`
    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.
    Specified by:
      `getEncodingForCharset` in interface `IEncodingFactory`
    Parameters:
      `charset` - The Java character set
    Returns:
      Encoding instance (never null)

  - ### getOrCreateEncodingForCharset

    public Encoding getOrCreateEncodingForCharset(Charset charset)
    Description copied from interface: `IEncodingFactory`
    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 `IEncodingFactory.getEncodingForCharset(java.nio.charset.Charset, Encoding)` should be used.

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

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

  - ### getEncodingDefinitionByCharsetAlias

    public EncodingDefinition getEncodingDefinitionByCharsetAlias(String charsetAlias)
    Description copied from interface: `IEncodingFactory`
    Looks up the `EncodingDefinition` by the specified Java character set name or alias.
    Specified by:
      `getEncodingDefinitionByCharsetAlias` in interface `IEncodingFactory`
    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

    public Encoding getEncodingForCharsetAlias(String charsetAlias, Encoding fallbackEncoding)
    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 fallbackEncoding will be used.
    Parameters:
      `charsetAlias` - The Java character set name or alias
      `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)

  - ### getEncodingForCharsetAlias

    public Encoding getEncodingForCharsetAlias(String charsetAlias)
    Description copied from interface: `IEncodingFactory`
    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.
    Specified by:
      `getEncodingForCharsetAlias` in interface `IEncodingFactory`
    Parameters:
      `charsetAlias` - The Java character set name or alias
    Returns:
      Encoding instance (never null)

  - ### getEncodingDefinition

    public EncodingDefinition getEncodingDefinition(String firebirdEncodingName, String javaCharsetAlias)
    Description copied from interface: `IEncodingFactory`
    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 `IEncodingFactory.getEncodingDefinitionByFirebirdName(String)` is returned. For the reverse (`firebirdEncodingName` is null and `javaCharsetAlias` isn't), the encoding definition as returned by `IEncodingFactory.getEncodingDefinitionByCharsetAlias(String)` is returned.

    When both parameters are set, the result of `IEncodingFactory.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.

    Specified by:
      `getEncodingDefinition` in interface `IEncodingFactory`
    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

    public IEncodingFactory withDefaultEncodingDefinition(EncodingDefinition encodingDefinition)
    Returns an `IEncodingFactory` that uses `encodingDefinition` as the default.

    This implementation returns an instance of `ConnectionEncodingFactory`.

    Specified by:
      `withDefaultEncodingDefinition` in interface `IEncodingFactory`
    Parameters:
      `encodingDefinition` - The default encoding to use (or `null` for the value of `IEncodingFactory.getDefaultEncoding()`
    Returns:
      IEncodingFactory instance with the specified default.

  - ### withDefaultEncodingDefinition

    public IEncodingFactory withDefaultEncodingDefinition(Charset charset)
    Returns an `IEncodingFactory` that uses an `EncodingDefinition` identified by `charSet` as the default.

    This implementation returns an instance of `ConnectionEncodingFactory`.

    Specified by:
      `withDefaultEncodingDefinition` in interface `IEncodingFactory`
    Parameters:
      `charset` - The default charset to use.
    Returns:
      IEncodingFactory instance with the specified default.

  - ### getOrCreateDatatypeCoder

    public <T extends DatatypeCoder> T getOrCreateDatatypeCoder(Class<T> datatypeCoderClass, Function<IEncodingFactory,T> datatypeCoderFactory)
    Description copied from interface: `IEncodingFactory`
    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.

    Specified by:
      `getOrCreateDatatypeCoder` in interface `IEncodingFactory`
    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

  - ### withDefaultEncodingDefinition

    public IEncodingFactory withDefaultEncodingDefinition()
    Returns an `ConnectionEncodingFactory` that uses `getDefaultEncodingDefinition()` as the default.
    Returns:
      IEncodingFactory instance with the specified default.

  - ### getPlatformDefault

    public static IEncodingFactory getPlatformDefault()
    Returns an instance of `IEncodingFactory` with the default encoding set to the platform encoding.
    Returns:
      Instance of `IEncodingFactory`.

  - ### createInstance

    public static IEncodingFactory createInstance(EncodingDefinition encodingDefinition)
    Returns an `IEncodingFactory` that uses `encodingDefinition` as the default.

    If `encodingDefinition` is `null` or an information-only encoding, the implementation will return the cached instance returned by `getPlatformDefault()`.

    Parameters:
      `encodingDefinition` - The default encoding to use (or `null` to get `getPlatformDefault()`
    Returns:
      IEncodingFactory instance with the specified default.

  - ### createInstance

    public static IEncodingFactory createInstance(Charset charset)
    Returns an `IEncodingFactory` that uses an `EncodingDefinition` identified by `charSet` as the default.

    If `charset` is `null`, the implementation will return the cached instance return by `getPlatformDefault()`.

    Parameters:
      `charset` - The default charset to use, or `null` for `getPlatformDefault()`.
    Returns:
      IEncodingFactory instance with the specified default.

  - ### createInstance

    public static EncodingFactory createInstance(EncodingSet... encodingSets)
    Creates a new EncodingFactory based on the supplied encodingSets. The supplied `EncodingSet` instances are processed highest preferenceWeight first.
    Parameters:
      `encodingSets` - The EncodingSet definitions to use for the EncodingFactory instance
    Returns:
      EncodingFactory instance based on the supplied encodingSets.