Package org.firebirdsql.encodings

## Class EncodingFactory

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

- All Implemented Interfaces:
    `IEncodingFactory`

      public final class EncodingFactory
      extends java.lang.Object
      implements IEncodingFactory

  Factory for `EncodingDefinition` and `Encoding`.
  Author:
    Mark Rotteveel

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ENCODING_NAME_NONE` |
    `static java.lang.String` | `ENCODING_NAME_OCTETS` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static IEncodingFactory` | `createInstance​(java.nio.charset.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​(java.lang.String firebirdEncodingName, java.lang.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​(java.nio.charset.Charset charset)` | Looks up an `EncodingDefinition` for the Java `Charset`.
    `EncodingDefinition` | `getEncodingDefinitionByCharsetAlias​(java.lang.String charsetAlias)` | Looks up the `EncodingDefinition` by the specified Java character set name or alias.
    `EncodingDefinition` | `getEncodingDefinitionByFirebirdName​(java.lang.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​(java.nio.charset.Charset charset)` | Gets an `Encoding` for the specified Java character set.
    `Encoding` | `getEncodingForCharset​(java.nio.charset.Charset charset, Encoding fallbackEncoding)` | Gets an `Encoding` for the specified Java character set.
    `Encoding` | `getEncodingForCharsetAlias​(java.lang.String charsetAlias)` | Gets an `Encoding` for the specified Java character set name or alias.
    `Encoding` | `getEncodingForCharsetAlias​(java.lang.String charsetAlias, Encoding fallbackEncoding)` | Gets an `Encoding` for the specified Java character set name or alias.
    `Encoding` | `getEncodingForFirebirdName​(java.lang.String firebirdEncodingName)` | Gets an `Encoding` for the specified Firebird encoding.
    `Encoding` | `getEncodingForFirebirdName​(java.lang.String firebirdEncodingName, Encoding fallbackEncoding)` | Gets an `Encoding` for the specified Firebird encoding.
    `<T extends DatatypeCoder> T` | `getOrCreateDatatypeCoder​(java.lang.Class<T> datatypeCoderClass)` | Gets or - if necessary - creates a datatype coder of the specified type.
    `Encoding` | `getOrCreateEncodingForCharset​(java.nio.charset.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​(java.nio.charset.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 Detail

    - #### ENCODING_NAME_NONE

          public static final java.lang.String ENCODING_NAME_NONE

      See Also:
        Constant Field Values

    - #### ENCODING_NAME_OCTETS

          public static final java.lang.String ENCODING_NAME_OCTETS

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### 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​(java.lang.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​(java.lang.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​(java.lang.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​(java.nio.charset.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​(java.nio.charset.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​(java.nio.charset.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​(java.nio.charset.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String firebirdEncodingName,
                                                          java.lang.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​(java.nio.charset.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​(java.lang.Class<T> datatypeCoderClass)

      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, needs to have a single-arg constructor accepting an `IEncodingFactory`.
      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​(java.nio.charset.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.