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
`static java.lang.String` `ENCODING_NAME_NONE`
`static java.lang.String` `ENCODING_NAME_OCTETS`

### Method Summary

Methods
`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.
`protected static <T extends DatatypeCoder> T` `createNewDatatypeCoder(java.lang.Class<T> datatypeCoderClass, IEncodingFactory encodingFactory)`
`static int` `getCharacterSetSize(int characterSetId)` Deprecated. Use the information provided by the `EncodingDefinition` returned by `getEncodingDefinitionByCharacterSetId(int)`
`Encoding` `getDefaultEncoding()`
`EncodingDefinition` `getDefaultEncodingDefinition()` Returns the `EncodingDefinition` for the default platform character set.
`static Encoding` `getEncoding(java.nio.charset.Charset charset)` Deprecated. Use `getEncodingForCharset(java.nio.charset.Charset, Encoding)` or `getOrCreateEncodingForCharset(java.nio.charset.Charset)`
`static Encoding` `getEncoding(java.lang.String javaCharsetAlias)` Deprecated. Use `getEncodingForCharsetAlias(String, Encoding)`
`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.
`static java.lang.String` `getIscEncoding(java.nio.charset.Charset javaCharset)` Deprecated. Use `getEncodingDefinitionByCharset(java.nio.charset.Charset)`
`static java.lang.String` `getIscEncoding(java.lang.String javaCharsetAlias)` Deprecated. Use `getEncodingDefinitionByCharsetAlias(String)`
`static int` `getIscEncodingSize(java.lang.String iscEncoding)` Deprecated. Use `getEncodingDefinitionByFirebirdName(String)` and `EncodingDefinition.getMaxBytesPerChar()`
`static java.lang.String` `getJavaEncoding(java.lang.String iscEncoding)` Deprecated.
`static java.lang.String` `getJavaEncodingForAlias(java.lang.String javaAlias)` Deprecated. Use `getEncodingDefinitionByCharsetAlias(String)` and `EncodingDefinition.getJavaEncodingName()`
`<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

#### createNewDatatypeCoder

    protected static <T extends DatatypeCoder> T createNewDatatypeCoder(java.lang.Class<T> datatypeCoderClass,
                                                     IEncodingFactory encodingFactory)

#### 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.

#### getCharacterSetSize

    @Deprecated
    public static int getCharacterSetSize(int characterSetId)

Deprecated. Use the information provided by the `EncodingDefinition` returned by `getEncodingDefinitionByCharacterSetId(int)`
Get size of a character for the specified character set.

Parameters:
  `characterSetId` - of the character set.
Returns:
  maximum size of the character in bytes or 1 if charset was not found.

#### getEncoding

    @Deprecated
    public static Encoding getEncoding(java.lang.String javaCharsetAlias)

Deprecated. Use `getEncodingForCharsetAlias(String, Encoding)`
Gets an `Encoding` instance for the supplied java Charset name.

Parameters:
  `javaCharsetAlias` - Java Charset name
Returns:
  Instance of `Encoding`

#### getEncoding

    @Deprecated
    public static Encoding getEncoding(java.nio.charset.Charset charset)

Deprecated. Use `getEncodingForCharset(java.nio.charset.Charset, Encoding)` or `getOrCreateEncodingForCharset(java.nio.charset.Charset)`
Gets an `Encoding` instance for the supplied java Charset.

Parameters:
  `charset` - Java Charset
Returns:
  Instance of `Encoding`

#### getIscEncoding

    @Deprecated
    public static java.lang.String getIscEncoding(java.lang.String javaCharsetAlias)

Deprecated. Use `getEncodingDefinitionByCharsetAlias(String)`
Get Firebird encoding for given Java language encoding.

Parameters:
  `javaCharsetAlias` - Java language encoding.
Returns:
  corresponding Firebird encoding or `null` if none found.

#### getIscEncoding

    @Deprecated
    public static java.lang.String getIscEncoding(java.nio.charset.Charset javaCharset)

Deprecated. Use `getEncodingDefinitionByCharset(java.nio.charset.Charset)`
Get Firebird encoding for given Java Charset.

Parameters:
  `javaCharset` - Java Charset
Returns:
  corresponding Firebird encoding or `null` if none found.

#### getIscEncodingSize

    @Deprecated
    public static int getIscEncodingSize(java.lang.String iscEncoding)

Deprecated. Use `getEncodingDefinitionByFirebirdName(String)` and `EncodingDefinition.getMaxBytesPerChar()`
Get size of a character for the specified Firebird encoding.

Parameters:
  `iscEncoding` - Firebird encoding.
Returns:
  maximum size of the character in bytes or 1 if encoding was not found.

#### getJavaEncoding

    @Deprecated
    public static java.lang.String getJavaEncoding(java.lang.String iscEncoding)

Deprecated.
Get Java language encoding for given Firebird encoding.

Parameters:
  `iscEncoding` - Firebird encoding
Returns:
  corresponding Java encoding or `null` if none found. Use `getEncodingDefinitionByFirebirdName(String)` and `EncodingDefinition.getJavaEncodingName()`

#### getJavaEncodingForAlias

    @Deprecated
    public static java.lang.String getJavaEncodingForAlias(java.lang.String javaAlias)

Deprecated. Use `getEncodingDefinitionByCharsetAlias(String)` and `EncodingDefinition.getJavaEncodingName()`
Get Java language encoding for a given Java encoding alias.

Ensures that naming is consistent even if a different alias was used.

Parameters:
  `javaAlias` - Java alias for the encoding
Returns:
  Java Charset name