JeeWiz Architect's Guide - Character Encoding


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 6. Running And Configuring JeeWiz

6.8 Character Encoding

"Character encoding" defines the way that files are encoded - such as ASCII, ISO-8859-1 or UTF-8. Although UTF-8 is becoming the preferred character encoding format worldwide, a legitimate use of JeeWiz is to read and write documents in other encodings.

Therefore, the default character encoding format at all stages in JeeWiz is UTF-8, but facilities are provided to read and write other documents. Corresponding changes have been made to the Ant and Velocity integrated with JeeWiz, so they too have a default encoding of UTF-8.

6.8.1	Encoding Of Specifications
6.8.2	Encoding Of Meta-programs - inputEncoding
6.8.3	Encoding Of Pattern Output
6.8.4	Encoding Of Output

6.8.1 Encoding Of Specifications

Specifications are defined in XML.

The default encoding for XML is UTF-8. If another encoding is used, it must be specified in the XML declaration (i.e. '<?xml version='1.0' encoding='...' ?>).

JeeWiz does not need to make any provision for the encoding of specifications: the necessary variation is provided by the XML specification.

6.8.2 Encoding Of Meta-programs - inputEncoding

The default encoding for JeeWiz meta-programs is UTF-8.

The user can set the 'inputEncoding' property at start of day to use a non-default encoding. For example, it is possible to switch the encoding of the meta-programs to ISO 8859 by running JeeWiz as follows:

ant "-Dpass=inputEncoding=ISO-8859-1"

The term 'meta-programs' covers the reading of all constituents of the meta-programs, namely

templates, including VM_global_library.vm files
patterns
component.methods.

The Java language defines that property files are encoded in ISO 8859-1, and this applies to

build properties (.jwp) files
system.properties
component.properties

Note that there is no way of stating that a particular input document has an encoding different from the defined input encoding. If you need to encode non-standard characters in some of the meta-programs, you can

convert all meta-program files to the desired encoding and then use the 'inputEncoding' property to run JeeWiz, or
include special characters in system.properties files e.g.
uUmlaut=\u00FC
For example, see the base system.properties file.
Define other encodings as properties in component/system.properties file for specific output formats, such as "uUmlaut=ü" and then reference these in programs (e.g. ${uUmlaut}).

Note that the standard meta-programs (templates, patterns and component.methods files) distributed by NT/e use the ASCII subset (only characters 0-127 decimal). It is recommended to developers that they restrict the character set of meta-programs to ASCII. By doing this, the system can be used with different character sets by changing only properties files (*.jwp and *.properties), which can be done by a translator who is not a programmer. [ There is even a case for having template directories whose sole purpose is to hold the translatable words and phrases required.]

6.8.3 Encoding Of Pattern Output

The output of patterns is kept internally by the JeeWiz engine as a Java string. This means that the encoding of patterns (conversion to a byte output format) is not relevant: the string is fed directly into the XML reader as characters, so no byte conversion is required.

However, JeeWiz always adds an XML declaration, in case there is useful information in it apart from the encoding information. Therefore, you must not add your own XML declaration to the output of a pattern. In other words, do not put '<?xml encoding="UTF-8">' or similar at the start of a pattern.

We believe there should be no reason to change the XML declaration. However, if you need to do this, the XML declaration inserted by the engine into the output of patterns comes by default from the specified xmlDeclaration in the build configuration properties.

This can be changed in a particular pattern by the setPatternXmlDeclaration() method on model oobjects, in a call such as

$this.setPatternXmlDeclaration( "<?xml version='1.0' encoding='ISO-8859-1'?>" )

This is a one-shot: it only lasts for the current pattern (and any number of #parse and Velocity method invocations). Subsequent patterns will revert to using the configured xmlDeclaration unless the setPatternXmlDeclaration() method is called again.

6.8.4 Encoding Of Output

The encoding of the output of a JeeWiz run - i.e. the encoding of files created by the <jwVelocity> task - is defined by the start-of-day property 'outputEncoding'. This defines the default output for all types of templates, i.e. everything that gets written to a file. (Pattern output is separate, as described above.) So to set the default output encoding to UTF-16 at start of day say

ant "-Dpass2=outputEncoding=UTF-16"

The output encoding can also be specified for a single execution of <jwVelocity> - see the Velocity task documentation.