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

Method Summary

Modifier and Type	Method and 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.
static int	getCharacterSetSize(int characterSetId) Deprecated. Use the information provided by the EncodingDefinition returned by getEncodingDefinitionByCharacterSetId(int)
CharacterTranslator	getCharacterTranslator(java.lang.String mappingPath) Gets an instance of CharacterTranslator for the specified mappingPath.
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.nio.charset.Charset charset, java.lang.String mappingPath) Deprecated. To be removed in Jaybird 4, use getEncodingForCharset(Charset)
static Encoding	getEncoding(java.lang.String javaCharsetAlias) Deprecated. Use getEncodingForCharsetAlias(String, Encoding)
static Encoding	getEncoding(java.lang.String encoding, java.lang.String mappingPath) Deprecated. To be removed in Jaybird 4, use getEncodingForCharsetAlias(String)
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()
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()
static CharacterTranslator	getTranslator(java.lang.String mappingPath) Gets the CharacterTranslator for the specified mappingPath, or null if there is no such mappingPath
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)

getCharacterTranslator

public CharacterTranslator getCharacterTranslator(java.lang.String mappingPath)
                                           throws java.sql.SQLException

Description copied from interface: IEncodingFactory

Gets an instance of CharacterTranslator for the specified mappingPath.

Specified by:

getCharacterTranslator in interface IEncodingFactory

Parameters:

mappingPath - Path of the file with mapping definition

Returns:

Instance of CharacterTranslator

Throws:

java.sql.SQLException

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.

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

getEncoding

@Deprecated
public static Encoding getEncoding(java.lang.String encoding,
                                                java.lang.String mappingPath)
                                         throws java.sql.SQLException

Deprecated. To be removed in Jaybird 4, use getEncodingForCharsetAlias(String)

Gets an Encoding instance for the supplied java Charset name and alternative character mapping.

Parameters:

encoding - Java Charset name

mappingPath - Resource file with alternative character mapping

Returns:

Instance of Encoding

Throws:

java.sql.SQLException

getEncoding

@Deprecated
public static Encoding getEncoding(java.nio.charset.Charset charset,
                                                java.lang.String mappingPath)
                                         throws java.sql.SQLException

Deprecated. To be removed in Jaybird 4, use getEncodingForCharset(Charset)

Gets an Encoding instance for the supplied java Charset and alternative character mapping.

Parameters:

charset - Java Charset

mappingPath - Resource file with alternative character mapping

Returns:

Instance of Encoding

Throws:

java.sql.SQLException

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

getTranslator

public static CharacterTranslator getTranslator(java.lang.String mappingPath)
                                         throws java.sql.SQLException

Gets the CharacterTranslator for the specified mappingPath, or null if there is no such mappingPath

Parameters:

mappingPath - Path of the mapping definition file

Returns:

CharacterTranslator or null

Throws:

java.sql.SQLException