IANACharsets (Commons)

java.lang.Object
- com.lf.commons.i18n.IANACharsets

```
public class IANACharsets
extends java.lang.Object
```
Provides support for IANA character sets, aliases, and preferred MIME names.
The character set names defined by this class have been extracted from the IANA website http://www.iana.org/assignments/character-sets with the help of an XSLT script executed by a KAT-based application. This class is a fast lightweight database for character sets using efficient data caches which are installed when needed. Also the I18NFactory class provides support for a shared instance so application servers and KAT applications do not have to create multiple objects. Since the data provided here is static there is no need to have more than one single instance doing the job for you.
You can request values in various ways: get a preferred MIME name from IANA name (useful for XML functionality), get the character set alias(es) from the IANA names and vice versa. For populating GUI lists and comboboxes you can request containers with all available names. Since there are aliases defined for some of the IANA character sets this class provides support for requesting these aliases.
Another key feature of this class is its extensibility by simply adding new definitions to the resource/character-sets.conf file which was generated from the above mentioned IANA original file. The *.xsl and character-sets file in the same directory are used to create the *.conf resource file and are not discussed here. The format of the character set definition file character-sets.conf is as follows:
```
 ...
 CS_1_NAME=ANSI_X3.4-1968
 CS_1_AKA_1=iso-ir-6
 CS_1_AKA_2=ANSI_X3.4-1986
 CS_1_AKA_3=ISO_646.irv:1991
 CS_1_AKA_4=ASCII
 CS_1_AKA_5=ISO646-US
 CS_1_AKA_6=US-ASCII
 CS_1_AKA_7=us
 CS_1_AKA_8=IBM367
 CS_1_AKA_9=cp367
 CS_1_AKA_10=csASCII
 CS_1_MIME=US-ASCII
 ...
 
```
The CS_*_NAME variables hold the character set names as defined by IANA. IANA also defined some additional data for each of the sets like the MIBenum which is not handled by this class. The CS_*_AKA_* variables hold the corresponding character set aliases. The listing shows the character set ANSI_X3.4-1968 which is a synonym for US-ASCII. If a certain alias should be preferred for use in MIME-based formats like XML the resource file holds the variable CS_*_MIME. If there is no special MIME name defined simply use the full IANA name for your encoding settings or whatever.
New character set definitions should only be added as the IANA website changes. Do not set own local definitions as long as they do not apply to the IANA standards. The best way to set new character sets is to download the IANA resource file as mentioned above and rerun the XSLT script. The new resource file will then be updated in a manner it should be done. Since modern systems use Unicode and XML I expect the "old fashioned" character sets will be obsolete some day in the near future.
The IANA character set names may be up to 40 characters taken from the printable characters of US-ASCII. However, no distinction is made between use of upper and lower case letters. This means that you could query the caches as you like, the search patterns "cp850" and "CP850" will both deliver the same result.
Since this class uses some amount of memory for the caches you could also create instances as usual if you only use this class once in your program. If you use the factory shared instance the memory will never be released during the JVM lifetime as long as you do not flush the factory. As you can see you can tune this class either for more performance or for a smaller memory footprint.
This class is tested in detail by the class TestIANACharsets which you can find in the test directory of the KAT framework. Let me encourage you to always adapt and execute this test class when changes are applied since also little changes can cause errors.
Since:

1.5

Version:

$Revision: 1.10 $, $Date: 2012/12/28 11:44:25 $

Author:

Axel Schwolow

See Also:
I18NFactory

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Hashtable<java.lang.String,java.lang.String[]>`	`cacheAliasesByName` Container for fast acquisition of the character set aliases by IANA name.
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`cacheMIMEByName` Container for fast acquisition of the preferred MIME name by IANA name.
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`cacheNameByAlias` Container for fast acquisition of the character set aliases by IANA name.
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`cacheNameByMIME` Container for fast acquisition of IANA character set names by preferred MIME name.
`protected java.util.Hashtable<java.lang.String,java.lang.String>`	`cacheNormalized` Container for fast acquisition of normalized IANA character set names.
`protected java.lang.String`	`resourceFile` Target resource file (without path) with IANA character set definitions

Constructor Summary

Constructors
Constructor and Description

IANACharsets()
Constructor method.

Constructors
Constructor and Description
`IANACharsets()` Constructor method.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`finalize()` Cares for proper cleanup when is not needed any longer (helps gc).
`java.lang.String[]`	`getAliasesByName(java.lang.String name)` Returns the aliases associated with a certain IANA character set name.
`java.util.Vector<java.lang.String>`	`getAllMIME()` Returns the sorted list with supported MIME character set names.
`java.util.Vector<java.lang.String>`	`getAllNames()` Returns the sorted list with supported IANA character set names.
`java.lang.String`	`getMIMEByName(java.lang.String name)` Returns the preferred MIME name associated with a certain IANA character set name.
`java.lang.String`	`getNameByAlias(java.lang.String alias)` Returns the IANA character set name associated with a certain alias.
`java.lang.String`	`getNameByMIME(java.lang.String mime)` Returns the IANA character set name associated with a certain MIME name.
`protected void`	`installInitialCaches()` Installs the (three) initial caches and loads charset names from `*.conf` file.

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

- Field Detail
  - cacheMIMEByName
```
protected java.util.Hashtable<java.lang.String,java.lang.String> cacheMIMEByName
```
    Container for fast acquisition of the preferred MIME name by IANA name. Key is normalized IANA name (String), value is preferred MIME name (String).
  - cacheNameByMIME
```
protected java.util.Hashtable<java.lang.String,java.lang.String> cacheNameByMIME
```
    Container for fast acquisition of IANA character set names by preferred MIME name. Key is normalized MIME name (String), value is IANA name (String).
  - cacheAliasesByName
```
protected java.util.Hashtable<java.lang.String,java.lang.String[]> cacheAliasesByName
```
    Container for fast acquisition of the character set aliases by IANA name. Key is normalized IANA name (String), value is aliases array (String[]).
  - cacheNameByAlias
```
protected java.util.Hashtable<java.lang.String,java.lang.String> cacheNameByAlias
```
    Container for fast acquisition of the character set aliases by IANA name. Key is normalized alias (String), value is IANA name (String).
  - cacheNormalized
```
protected java.util.Hashtable<java.lang.String,java.lang.String> cacheNormalized
```
    Container for fast acquisition of normalized IANA character set names. Key is normalized name (String), value is IANA original (String).
  - resourceFile
```
protected java.lang.String resourceFile
```
    Target resource file (without path) with IANA character set definitions
- Constructor Detail
  - IANACharsets
```
public IANACharsets()
```
    Constructor method.
    Simply calls installInitialCaches which installs the initial caches and loads data from the *.conf file. See the method for details on how errors are propagated. As already said above you can implement your own subclasses with a constructor that reads the basic mapping data from a file other than the default *.conf file. To do this you have to call the installInitialCaches method with a different parameter. There is no need to call the superclass constructor first since this would cause unnecessary loading. If you implement a subclass the factory class cannot be used!
    
    Since:
    
    1.5
- Method Detail
  - installInitialCaches
```
protected void installInitialCaches()
```
    Installs the (three) initial caches and loads charset names from *.conf file.
    From the resource file we set pairs to the caches cacheAliasesByName, cacheMIMEByName, and cacheNormalized. Throws java.lang.RuntimeException if the names file could not be read. This is absolutely necessary.
    
    Since:
    
    1.5
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Cares for proper cleanup when is not needed any longer (helps gc).
    The caches are cleared here to allow for a faster garbage collecting.
    
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable
    Since:
    
    1.5
  - getMIMEByName
```
public java.lang.String getMIMEByName(java.lang.String name)
```
    Returns the preferred MIME name associated with a certain IANA character set name.
    You can pass the IANA name case-insensitive, for example "Big5" or "bIg5" will cause the same result to be returned. This applies to the IANA specification (see http://www.iana.org/assignments/character-sets.
    Throws NullPointerException if name is null. If a preferred MIME name does not exist for the IANA name then null is returned.
    
    Parameters:
    name - The IANA name of interest, don't pass null values
    
    Returns:
    The preferred MIME name, null if IANA name does not exist
    Since:
    
    1.5
  - getNameByMIME
```
public java.lang.String getNameByMIME(java.lang.String mime)
```
    Returns the IANA character set name associated with a certain MIME name.
    You can pass the MIME name case-insensitive, for example "Big5" or "bIg5" will cause the same result to be returned. This applies to the IANA specification (see http://www.iana.org/assignments/character-sets.
    Throws NullPointerException if mime is null. If a IANA name does not exist for the MIME name then null is returned.
    
    Parameters:
    mime - The MIME name of interest, don't pass null values
    
    Returns:
    The IANA name, null if MIME name does not exist
    Since:
    
    1.5
  - getAliasesByName
```
public java.lang.String[] getAliasesByName(java.lang.String name)
```
    Returns the aliases associated with a certain IANA character set name.
    You can pass the IANA name case-insensitive, for example "Big5" or "bIg5" will cause the same result to be returned. This applies to the IANA specification (see http://www.iana.org/assignments/character-sets.
    Throws NullPointerException if name is null. If aliases do not exist for the IANA name then null is returned.
    
    Parameters:
    name - The IANA name of interest, don't pass null values
    
    Returns:
    The character set alias(es), null if IANA name does not exist
    Since:
    
    1.5
  - getNameByAlias
```
public java.lang.String getNameByAlias(java.lang.String alias)
```
    Returns the IANA character set name associated with a certain alias.
    You can pass the alias case-insensitive, for example "latin1" or "LaTiN1" will cause the same result to be returned. This applies to the IANA specification (see http://www.iana.org/assignments/character-sets.
    Throws NullPointerException if alias is null. If a IANA name does not exist for the alias then null is returned.
    
    Parameters:
    alias - The alias of interest, don't pass null values
    
    Returns:
    The IANA name, null if MIME name does not exist
    Since:
    
    1.5
  - getAllMIME
```
public java.util.Vector<java.lang.String> getAllMIME()
```
    Returns the sorted list with supported MIME character set names.
    The returned list holds the preferred MIME names for IANA character sets if defined. If there is no special name defined for use with MIME then the original IANA name is used. MIME names can be used for the encoding attribute of XML files for example but it is not sure that all XML parsers will support any IANA character set.
    This method returns Vector containers with String objects ready to use with JComboBox instances.
    
    Returns:
    The container with sorted MIME character set names
    Since:
    
    1.5
  - getAllNames
```
public java.util.Vector<java.lang.String> getAllNames()
```
    Returns the sorted list with supported IANA character set names.
    This method returns Vector containers with String objects ready to use with JComboBox instances.
    
    Returns:
    The container with sorted IANA character set names
    Since:
    
    1.5

Class IANACharsets

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

cacheMIMEByName

cacheNameByMIME

cacheAliasesByName

cacheNameByAlias

cacheNormalized

resourceFile

Constructor Detail

IANACharsets

Method Detail

installInitialCaches

finalize

getMIMEByName

getNameByMIME

getAliasesByName

getNameByAlias

getAllMIME

getAllNames