Example 2 - Setting Alignment Options

What Example 2 Demonstrates

Byte alignment has a significant impact on the overall size of an EXI file.

XML, by definition, is a text-based standard. The smallest unit of storage is a byte (for a single character), even if the actual value could be expressed using a smaller space. For example, if the value were 1 or 0, an XML file would store it as a byte value, even though it could be stored in a single bit.

EXI files, by default, are bit-packed. Information is stored using the fewest number of bits required, regardless of the byte boundaries. Conceptually, this allows 8 Boolean values to be stored in a single Byte, versus 8 separate bytes for the letters T or F. In a large data set, this can provide significant savings.

The byte-aligned option encodes the document content aligned on byte boundaries. This usually results in EXI streams that are larger than the bit-packed equivalent. However, these files can be viewed with a text editor for troubleshooting encoding and decoding routines.

The pre-compression option performs all transformations on the XML file except for the final step of applying the DEFLATE algorithm. The primary purpose of pre-compression is to avoid a duplicate compression step when compression capability is built in to the transport protocol.

When the compress option is selected, the W3C specification states explicitly that alignment options are ignored, and the file is processed per the specification to achieve the smallest possible size.

Example 2 adds the Alignment radio button group to the UI. By changing the alignment option, you can encode files and compare their finished size. It can be interesting to peek inside the output files using a text editor to see their relative readability. Since compression and alignment are mutually exclusive, it makes sense to include compression in the Alignment radio button group.

How to Use Example 2

To install and run Example 2:

EncodeEXI

This example adds a string argument for the alignment type.

    public void encodeEXI(
        String sourceFile, 
        String destinationFile,
        String alignment
    ) 

This allows you to try the different settings and see how they impact the size of the file using your own data. In practice, you will already know the best setting and be able hard code the optimal value in your custom routine.

The code itself is unremarkable. Alignment is bit-packed by default. You can change the alignment using the alignment radio buttons in the user interface. The radio button label is passed as a String argument to EncodeEXI(). Based on the String value, the alignment type is passed to the Transmogrifier using an enumerated value.

            Transmogrifier transmogrifier = new Transmogrifier();
            
            // Set alignment and compression
            if (alignment.equals("bitPacked"))
                    transmogrifier.setAlignmentType(AlignmentType.bitPacked);
            if (alignment.equals("compress"))
                    transmogrifier.setAlignmentType(AlignmentType.compress);
            if (alignment.equals("preCompress"))
                    transmogrifier.setAlignmentType(AlignmentType.preCompress);
            if(alignment.equals("byteAligned"))
                    transmogrifier.setAlignmentType(AlignmentType.byteAligned);

DecodeEXI

When you decode a file, you need to set the alignment to match the settings when the file was encoded. The code looks exactly the same as in EncodeEXI(), except it sets the value on the EXIReader rather than the Transmogrifier.

    public void decodeEXI(
            String sourceFile, 
            String destinationFile,
            String alignment
    )
.
.
.
            EXIReader reader = new EXIReader();
        
            // Set alignment and compression
            if (alignment.equals("bitPacked"))
                    reader.setAlignmentType(AlignmentType.bitPacked);
            if (alignment.equals("compress"))
                    reader.setAlignmentType(AlignmentType.compress);
            if (alignment.equals("preCompress"))
                    reader.setAlignmentType(AlignmentType.preCompress);
            if(alignment.equals("byteAligned"))
                    reader.setAlignmentType(AlignmentType.byteAligned);