L10nPack (MyTISM API Documentation)

java.lang.Object
- de.ipcon.tools.L10nPack

All Implemented Interfaces:

SecureExternalizable, java.io.Serializable, java.lang.Cloneable
```
public class L10nPack
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable, SecureExternalizable
```
Represents a localized pack of key-value pairs (messages) used for internationalization (L10n).
Unlike a typical HashMap, this class internally uses two parallel arrays (one for keys and one for values) to store its data. This design choice is made to minimize memory overhead by avoiding additional object pointers that a HashMap would introduce, which is crucial given that localization data often consists of many String objects that already consume significant memory.

For efficient lookup, the keys in the internal array are kept sorted, and binary search is employed. Furthermore, this class provides methods optimized for quickly writing these packs to disk and reading them back. The goal of this optimized serialization/deserialization is to enhance performance, making it feasible to cache L10n bundles using WeakReferences without severe performance compromises.

For memory management reasons, a cascading mechanism (where a pack inherits missing keys from parent packs) is explicitly not implemented at this level. This design allows the garbage collector (GC) a better chance to dispose of individual L10nPack objects when they are no longer strongly referenced. Therefore, the administration and potential reloading of individual packs are delegated to a separate manager component.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static L10nPack[] EMPTY_ARRAY

Fields
Modifier and Type	Field and Description
`static L10nPack[]`	`EMPTY_ARRAY`

Constructor Summary

Constructors
Constructor and Description
`L10nPack()`
`L10nPack(java.util.Map<java.lang.String,java.lang.String> keyValueMap)`
`L10nPack(java.lang.String[] _keys, java.lang.String[] _values)`
`L10nPack(java.lang.String[] _keys, java.lang.String[] _values, boolean preSorted)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.Object`	`clone()`
`void`	`fillFromUnsortedArrays(java.lang.String[] _keys, java.lang.String[] _values)`
`void`	`fillInMissingsFrom(L10nPack sourcePack)` Fills in missing localization keys and their corresponding values in this L10nPack by taking entries from another provided L10nPack.
`java.lang.Long`	`getId()` Retrieves the unique identifier (ID) of this L10n pack.
`java.lang.String[]`	`getKeys()` Returns a copy of all keys present in this L10n pack, typically used for verification purposes.
`long`	`getLmod()` Retrieves the last modification timestamp (lmod) of this L10n pack.
`java.util.Locale`	`getLocale()` Retrieves the `Locale` associated with this L10n pack.
`java.lang.String`	`getName()` Retrieves the name of this L10n pack.
`java.lang.Integer`	`getPathPos()` Retrieves the position in the path for this L10n pack.
`java.lang.String`	`getString(java.lang.String key)` Retrieves the localized string value for a given key from this L10n pack.
`void`	`readFile()`
`void`	`readFile(java.io.File dir)`
`void`	`readFile(java.io.File dir, java.lang.String _name)`
`void`	`readFile(java.io.File dir, java.lang.String _name, java.util.Locale _locale)`
`L10nPack`	`readFromInputStream(java.io.InputStream is)`
`void`	`readInstance(SecureObjectInputI in)` Reads an instance of this class from the given SecureObjectInputI without using readObject.
`L10nPack`	`setId(java.lang.Long newId)` Sets the unique identifier (ID) for this L10n pack.
`L10nPack`	`setLmod(long l)` Sets the last modification timestamp (lmod) for this L10n pack.
`L10nPack`	`setLocale(java.util.Locale l)` Sets the `Locale` for this L10n pack.
`L10nPack`	`setName(java.lang.String s)` Sets the name of this L10n pack.
`L10nPack`	`setPathPos(java.lang.Integer pos)` Sets the position in the path for this L10n pack.
`void`	`setString(java.lang.String key, java.lang.String value)` Sets the string value for a given key in this L10n pack.
`int`	`size()`
`java.lang.String`	`toString()`
`void`	`writeFile()`
`void`	`writeFile(java.io.File dir)`
`void`	`writeInstance(SecureObjectOutputI out)` Writes an instance of this class to the given SecureObjectOutputI without using writeObject.
`L10nPack`	`writeLine(java.io.BufferedWriter w, java.lang.String s)`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - EMPTY_ARRAY
```
public static final L10nPack[] EMPTY_ARRAY
```
- Constructor Detail
  - L10nPack
```
public L10nPack()
```
  - L10nPack
```
public L10nPack(java.lang.String[] _keys,
                java.lang.String[] _values)
```
  - L10nPack
```
public L10nPack(java.lang.String[] _keys,
                java.lang.String[] _values,
                boolean preSorted)
```
  - L10nPack
```
public L10nPack(java.util.Map<java.lang.String,java.lang.String> keyValueMap)
```
- Method Detail
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - size
```
public int size()
```
  - fillFromUnsortedArrays
```
public void fillFromUnsortedArrays(java.lang.String[] _keys,
                                   java.lang.String[] _values)
```
  - fillInMissingsFrom
```
public void fillInMissingsFrom(L10nPack sourcePack)
```
    Fills in missing localization keys and their corresponding values in this L10nPack by taking entries from another provided L10nPack.
    This method iterates through the keys of the current pack, storing existing key-value pairs in a temporary map. It then iterates through the keys of the sourcePack and adds any keys that are missing from the current pack (i.e., not present in the temporary map) along with their values from the source pack. This effectively merges the missing entries from the source pack into this pack.
    
    During the process, it logs warnings if null keys are encountered in either the current pack or the source pack, skipping such entries to prevent errors.
    
    Parameters:
    
    sourcePack - The L10nPack from which to retrieve missing keys and values.
  - getLocale
```
public java.util.Locale getLocale()
```
    Retrieves the Locale associated with this L10n pack.
    
    Returns:
    
    The Locale of this pack.
  - setLocale
```
public L10nPack setLocale(java.util.Locale l)
```
    Sets the Locale for this L10n pack.
    The property is not defined as indirect to allow the setter to return the pack itself, facilitating method chaining without excessive constructor proliferation.
    
    Parameters:
    
    l - The Locale to set.
    
    Returns:
    
    This L10nPack instance, allowing for method chaining.
  - getName
```
public java.lang.String getName()
```
    Retrieves the name of this L10n pack.
    
    Returns:
    
    The name as a String.
  - setName
```
public L10nPack setName(java.lang.String s)
```
    Sets the name of this L10n pack.
    The property is not defined as indirect to allow the setter to return the pack itself, facilitating method chaining without excessive constructor proliferation.
    
    Parameters:
    
    s - The name String to set.
    
    Returns:
    
    This L10nPack instance, allowing for method chaining.
  - getLmod
```
public long getLmod()
```
    Retrieves the last modification timestamp (lmod) of this L10n pack.
    
    Returns:
    
    The last modification timestamp as a long.
  - setLmod
```
public L10nPack setLmod(long l)
```
    Sets the last modification timestamp (lmod) for this L10n pack.
    The property is not defined as indirect to allow the setter to return the pack itself, facilitating method chaining without excessive constructor proliferation.
    
    Parameters:
    
    l - The last modification timestamp as a long.
    
    Returns:
    
    This L10nPack instance, allowing for method chaining.
  - getId
```
public java.lang.Long getId()
```
    Retrieves the unique identifier (ID) of this L10n pack.
    
    Returns:
    
    The ID as a Long.
  - setId
```
public L10nPack setId(java.lang.Long newId)
```
    Sets the unique identifier (ID) for this L10n pack.
    The property is not defined as indirect to allow the setter to return the pack itself, facilitating method chaining without excessive constructor proliferation.
    
    Parameters:
    
    newId - The ID Long to set.
    
    Returns:
    
    This L10nPack instance, allowing for method chaining.
  - getPathPos
```
public java.lang.Integer getPathPos()
```
    Retrieves the position in the path for this L10n pack.
    
    Returns:
    
    The position as an Integer.
  - setPathPos
```
public L10nPack setPathPos(java.lang.Integer pos)
```
    Sets the position in the path for this L10n pack.
    The property is not defined as indirect to allow the setter to return the pack itself, facilitating method chaining without excessive constructor proliferation.
    
    Parameters:
    
    pos - The position as an Integer.
    
    Returns:
    
    This L10nPack instance, allowing for method chaining.
  - getString
```
public java.lang.String getString(java.lang.String key)
```
    Retrieves the localized string value for a given key from this L10n pack. This is the core functionality of this class.
    Keys are looked up using binary search on the internally sorted array of keys. If the key is not found, null is returned.
    
    Parameters:
    
    key - The String key whose associated value is to be returned.
    
    Returns:
    
    The String value to which the specified key is mapped, or null if this pack contains no mapping for the key or if the key itself is null.
  - setString
```
public void setString(java.lang.String key,
                      java.lang.String value)
```
    Sets the string value for a given key in this L10n pack.
    This method expects the key to already be present in the pack. If the key does not exist, an IllegalArgumentException is thrown. The value associated with the existing key is updated.
    
    Parameters:
    
    key - The String key whose value is to be set. If not null it must exist in the pack.
    
    value - The String value to associate with the specified key.
    
    Throws:
    
    java.lang.IllegalArgumentException - If the provided key is not present in this L10n pack.
  - getKeys
```
public java.lang.String[] getKeys()
```
    Returns a copy of all keys present in this L10n pack, typically used for verification purposes.
    A copy of the internal key array is returned to ensure that modifications to the returned array do not affect the internal state of the L10n pack.
    
    Returns:
    
    A String array containing all the keys in this pack. The array is a defensive copy of the internal key storage.
  - clone
```
public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
```
    Overrides:
    
    clone in class java.lang.Object
    
    Throws:
    
    java.lang.CloneNotSupportedException
  - writeInstance
```
public void writeInstance(SecureObjectOutputI out)
                   throws java.io.IOException
```
    Description copied from interface: SecureExternalizable
    
    Writes an instance of this class to the given SecureObjectOutputI without using writeObject.
    
    Specified by:
    
    writeInstance in interface SecureExternalizable
    
    Throws:
    
    java.io.IOException
  - readInstance
```
public void readInstance(SecureObjectInputI in)
                  throws java.io.IOException
```
    Description copied from interface: SecureExternalizable
    
    Reads an instance of this class from the given SecureObjectInputI without using readObject.
    
    Specified by:
    
    readInstance in interface SecureExternalizable
    
    Throws:
    
    java.io.IOException
  - writeFile
```
public void writeFile()
```
  - writeFile
```
public void writeFile(java.io.File dir)
```
  - readFile
```
public void readFile()
```
  - readFile
```
public void readFile(java.io.File dir)
```
  - readFile
```
public void readFile(java.io.File dir,
                     java.lang.String _name)
```
  - readFile
```
public void readFile(java.io.File dir,
                     java.lang.String _name,
                     java.util.Locale _locale)
```
  - readFromInputStream
```
public L10nPack readFromInputStream(java.io.InputStream is)
```
  - writeLine
```
public L10nPack writeLine(java.io.BufferedWriter w,
                          java.lang.String s)
                   throws java.io.IOException
```
    Throws:
    
    java.io.IOException

Class L10nPack

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EMPTY_ARRAY

Constructor Detail

L10nPack

L10nPack

L10nPack

L10nPack

Method Detail

toString

size

fillFromUnsortedArrays

fillInMissingsFrom

getLocale

setLocale

getName

setName

getLmod

setLmod

getId

setId

getPathPos

setPathPos

getString

setString

getKeys

clone

writeInstance

readInstance

writeFile

writeFile

readFile

readFile

readFile

readFile

readFromInputStream

writeLine