com.microej.nls

Class BinaryNLS

java.lang.Object

com.microej.nls.BinaryNLS

All Implemented Interfaces:

NLS

public class BinaryNLS
extends Object
implements NLS

This NLS implementation uses a binary file as entry point.
This binary file is automatically encoded by the associated Add-On Processor from GNU PO files or Android String resources.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_IMPLEMENTATION_ERROR Error code when default implementation cannot be instantiated.
static int	FORM_INDEX_OUT_OF_BOUNDS_ERROR Error code when the plural form index resulting from a plural expression is negative or larger than the number of available forms for the locale.
static int	MISSING_BINARY Error code when binary is missing.
static String	NLS_DEFAULT_IMPLEMENTATION Property which allows to define a fallback NLS implementation.
static String	NLS_DEFAULT_LOCALE Property which allows to fix the default locale at compiletime.
static int	REQUIRED_IMPLEMENTATION_ERROR Error code when required implementation cannot be instantiated.
static int	WRONG_CRC Error code when binary is incompatible: wrong CRC.
static int	WRONG_FORMAT_VERSION Error code when binary is incompatible: wrong format version.
static int	WRONG_HEADER Error code when binary is incompatible: wrong header.
static int	WRONG_LOCALE_INDEX Error code when the provided locale index does not correspond to an available one.

Constructor Summary

Constructors

Constructor and Description
BinaryNLS(Class<? extends Object> nlsInterface, int keysCRC32) Decodes a binary NLS file for the given interface.
BinaryNLS(String nlsInterfaceName, int keysCRC32) Decodes a binary NLS file for the given interface.
BinaryNLS(String nlsInterfaceName, int keysCRC32, NLSPlural pluralInfo) Decodes a binary NLS file for the given interface.

Method Summary

Modifier and Type	Method and Description
String[]	getAvailableLocales() Gets the list of available locales.
String	getCurrentLocale() Gets the current locale.
String	getDisplayName(String locale) Gets the human-readable name of the given locale.
static String	getErrorMessage(int errorCode) Builds a Severe-level error message.
String	getMessage(int messageID) Gets the message matching an ID in the current language.
String	getMessage(int messageID, int count) Gets the message or one of its plural forms matching an ID and a count value in the current language.
String	getMessage(int messageID, int count, String locale) Gets the message or one of its plural forms matching an ID and a count value in a specific language.
String	getMessage(int messageID, String locale) Gets the message matching an ID in a specific language.
static NLS	newBinaryNLS(String nlsInterfaceName, int keysCRC32) Decodes a binary NLS file for the given interface.
static NLS	newBinaryNLS(String nlsInterfaceName, int keysCRC32, NLSPlural pluralInfo) Decodes a binary NLS file for the given interface.
void	setCurrentLocale(String locale) Changes the current locale.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_IMPLEMENTATION_ERROR

public static final int DEFAULT_IMPLEMENTATION_ERROR

Error code when default implementation cannot be instantiated.

See Also:

Constant Field Values

FORM_INDEX_OUT_OF_BOUNDS_ERROR

public static final int FORM_INDEX_OUT_OF_BOUNDS_ERROR

Error code when the plural form index resulting from a plural expression is negative or larger than the number of available forms for the locale.

See Also:

Constant Field Values

MISSING_BINARY

public static final int MISSING_BINARY

Error code when binary is missing.

See Also:

Constant Field Values

NLS_DEFAULT_IMPLEMENTATION

public static final String NLS_DEFAULT_IMPLEMENTATION

Property which allows to define a fallback NLS implementation.

See Also:

newBinaryNLS(String, int), Constant Field Values

NLS_DEFAULT_LOCALE

public static final String NLS_DEFAULT_LOCALE

Property which allows to fix the default locale at compiletime.

See Also:

Constant Field Values

REQUIRED_IMPLEMENTATION_ERROR

public static final int REQUIRED_IMPLEMENTATION_ERROR

Error code when required implementation cannot be instantiated.

See Also:

Constant Field Values

WRONG_CRC

public static final int WRONG_CRC

Error code when binary is incompatible: wrong CRC.

See Also:

Constant Field Values

WRONG_FORMAT_VERSION

public static final int WRONG_FORMAT_VERSION

Error code when binary is incompatible: wrong format version.

See Also:

Constant Field Values

WRONG_HEADER

public static final int WRONG_HEADER

Error code when binary is incompatible: wrong header.

See Also:

Constant Field Values

WRONG_LOCALE_INDEX

public static final int WRONG_LOCALE_INDEX

Error code when the provided locale index does not correspond to an available one.

See Also:

Constant Field Values

Constructor Detail

BinaryNLS

public BinaryNLS(Class<? extends Object> nlsInterface,
                 int keysCRC32)
          throws IOException

Decodes a binary NLS file for the given interface. The name of binary file is the interface full name (package + interface simple name) + ".nls" extension. This binary file must have been compiled thanks the binary NLS addon processor.

Parameters:

nlsInterface - the NLS interface which lists the messages ID.

keysCRC32 - the CRC32 of all messages keys. This allows to verify the coherence between the encoded messages and the given interface. This CRC32 is a field of the given interface.

Throws:

IOException - if the expected binary file is not available in application classpath or if the binary file content is not recognized (probably because not encoded by the Binary NLS addon processor).

IllegalArgumentException - if the default locale defined by the property NLS_DEFAULT_LOCALE is not available in the binary file.

BinaryNLS

public BinaryNLS(String nlsInterfaceName,
                 int keysCRC32)
          throws IOException

Decodes a binary NLS file for the given interface. The name of binary file is the interface full name (package + interface simple name) + ".nls" extension. This binary file must have been compiled thanks the binary NLS addon processor.

No NLSPlural plural form processing class will be provided, all messages will be considered as singular form only.

Parameters:

nlsInterfaceName - the name of the NLS interface which lists the messages ID.

keysCRC32 - the CRC32 of all messages keys. This allows to verify the coherence between the encoded messages and the given interface. This CRC32 is a field of the given interface.

Throws:

IOException - if the expected binary file is not available in application classpath or if the binary file content is not recognized (probably because not encoded by the Binary NLS addon processor).

IllegalArgumentException - if the default locale defined by the property NLS_DEFAULT_LOCALE is not available in the binary file.

BinaryNLS

public BinaryNLS(String nlsInterfaceName,
                 int keysCRC32,
                 @Nullable
                 NLSPlural pluralInfo)
          throws IOException

Decodes a binary NLS file for the given interface. The name of binary file is the interface full name (package + interface simple name) + ".nls" extension. This binary file must have been compiled thanks the binary NLS addon processor.

Parameters:

nlsInterfaceName - the name of the NLS interface which lists the messages ID.

keysCRC32 - the CRC32 of all messages keys. This allows to verify the coherence between the encoded messages and the given interface. This CRC32 is a field of the given interface.

pluralInfo - an instance of NLSPlural containing the necessary information for plural messages management, can be null if there are no plural messages in an interface.

Throws:

IOException - if the expected binary file is not available in application classpath or if the binary file content is not recognized (probably because not encoded by the Binary NLS addon processor).

IllegalArgumentException - if the default locale defined by the property NLS_DEFAULT_LOCALE is not available in the binary file.

Method Detail

getAvailableLocales

public String[] getAvailableLocales()

Description copied from interface: NLS

Gets the list of available locales.

Specified by:

getAvailableLocales in interface NLS

Returns:

the list of locales.

getCurrentLocale

public String getCurrentLocale()

Description copied from interface: NLS

Gets the current locale.

Specified by:

getCurrentLocale in interface NLS

Returns:

the current locale.

getDisplayName

public String getDisplayName(String locale)

Description copied from interface: NLS

Gets the human-readable name of the given locale.

Specified by:

getDisplayName in interface NLS

Parameters:

locale - the locale.

Returns:

the human-readable name.

getErrorMessage

public static String getErrorMessage(int errorCode)

Builds a Severe-level error message.

Parameters:

errorCode - The error code.

getMessage

public String getMessage(int messageID)

Description copied from interface: NLS

Gets the message matching an ID in the current language.

Specified by:

getMessage in interface NLS

Parameters:

messageID - the ID of the message to retrieve.

Returns:

the message at the specified ID.

getMessage

public String getMessage(int messageID,
                         int count)

Description copied from interface: NLS

Gets the message or one of its plural forms matching an ID and a count value in the current language.

The count argument is intended to be positive, negative values will however still be accepted and plugged into the plural expressions defined in the translations files.

Specified by:

getMessage in interface NLS

Parameters:

messageID - the ID of the message to retrieve.

count - the count value.

Returns:

the message at the specified ID in the corresponding plural form.

getMessage

public String getMessage(int messageID,
                         int count,
                         String locale)

Description copied from interface: NLS

Gets the message or one of its plural forms matching an ID and a count value in a specific language.

The count argument is intended to be positive, negative values will however still be accepted and plugged into the plural expressions defined in the translations files.

Specified by:

getMessage in interface NLS

Parameters:

messageID - the ID of the message to retrieve.

count - the count value.

locale - the locale to use.

Returns:

the message at the specified ID in the corresponding plural form.

getMessage

public String getMessage(int messageID,
                         String locale)

Description copied from interface: NLS

Gets the message matching an ID in a specific language.

Specified by:

getMessage in interface NLS

Parameters:

messageID - the ID of the message to retrieve.

locale - the locale to use.

Returns:

the message at the specified ID.

newBinaryNLS

@Nullable
public static NLS newBinaryNLS(String nlsInterfaceName,
                                         int keysCRC32)

Decodes a binary NLS file for the given interface. Use this method when there are no plural messages to be handled in the interface.

If an error occurs while creating the NLS, a default NLS implementation instance is returned if the property NLS_DEFAULT_IMPLEMENTATION is defined, otherwise, null is returned.

Parameters:

nlsInterfaceName - the name of the NLS interface which lists the messages ID.

keysCRC32 - the CRC32 of all messages keys.

Returns:

an NLS instance.

Throws:

IllegalArgumentException - if the default implementation cannot be instantiated.

See Also:

BinaryNLS(String, int)

newBinaryNLS

@Nullable
public static NLS newBinaryNLS(String nlsInterfaceName,
                                         int keysCRC32,
                                         NLSPlural pluralInfo)

Decodes a binary NLS file for the given interface.

If an error occurs while creating the NLS, a default NLS implementation instance is returned if the property NLS_DEFAULT_IMPLEMENTATION is defined, otherwise, null is returned.

Parameters:

nlsInterfaceName - the name of the NLS interface which lists the messages ID.

keysCRC32 - the CRC32 of all messages keys.

pluralInfo - an instance of NLSPlural containing the necessary information for plural messages management, can be null if there are no plural messages in an interface.

Returns:

an NLS instance.

Throws:

IllegalArgumentException - if the default implementation cannot be instantiated.

See Also:

BinaryNLS(String, int)

setCurrentLocale

public void setCurrentLocale(String locale)

Description copied from interface: NLS

Changes the current locale.

Specified by:

setCurrentLocale in interface NLS

Parameters:

locale - the locale to set.