Special characters Java package

Using xchars is as easy as this:
SpecialCharacters xchars = SpecialCharacters.getInstance(null);
String translated = xchars.xml2Display(xcharsString);
, where xcharsString is a String containing xchars XML markup[1], which would be translated to the default encoding (this default can be set different for every xchars element).
For this to work, the XML configuration file must be in the classpath, with its standard naming (specialCharacters.xml).
Needles to say, the xchars jar file must be in your classpath, too.
If you want to use a configuration file with a different name, just substitute the null keyword with your file name.
If you need the configuration file to be outside your classpath, you can use this other method:
SpecialCharacters xchars = SpecialCharacters.getInstance(path, null); // [2]
, where path is the path to the directory where the XML file lives. As before, you can substitute null with the name you gave to your configuration file, if it's different from the default (specialCharacters.xml).
In case you want to force a encoding:
String translated = xchars.xml2Display(xcharsString, encoding);
, where encoding is one of the predefined ones (see uk.ac.ebi.xchars.domain.EncodingType).
A sample application (XCharsDemo) is provided. Compile and launch it as follows:
javac -cp .:xchars-x.x.x.jar XCharsDemo.java
java -cp .:xchars-x.x.x.jar XCharsDemo "here <arrow>right</arrow> text"
, where x.x.x is the current XChars version.


[1] The valid xchars XML markup is defined in the configuration file (named specialCharacters.xml by default). In the provided one you will find definitions and some examples. You can always tweak the configuration to your needs.
Besides, you can check the input string for validity (always recommended):
if (!xchars.validate(xcharsString)){ /* ERROR! */ }
[2] SpecialCharacters is a singleton, so you don't have to worry about calling the getInstance methods more than once. You can do it safely, but after the first call you will always get the same object (i.e. you cannot change the configuration, except for the path to images in case you want to use gif or jpeg encodings).