NlfExample 1.5 : Manual

Table of contents

You must have JavaScript enabled in your browser to generate the table of contents.

1  Overview

NlfExample is a Java console application (ie, an application without a graphical user interface) that demonstrates some of the aspects of the uk.org.blankaspect.nlf API. Its usefulness is likely to result not from running the program but from inspecting the relevant parts of its source code.

2  Requirements

NlfExample is a Java application that requires a Java runtime environment that supports Java SE 8 (Java 1.8), such as Oracle's Java Runtime Environment (JRE), version 8 or later.

NlfExample must be able to find the NLF library's JAR file, nlf.jar, on its class path.

3  Installing and running NlfExample

To install NlfExample, copy its JAR file, nlfExample.jar, and the NLF library, nlf.jar, to suitable locations on your system, then provide a means of running NlfExample with a command line.

The suggested means of running the application is to use the java tool. Assuming that your PATH environment variable includes the path to the java tool, and assuming that you have copied nlf.jar to the directory lib in the current directory and nlfExample.jar to the directory bin in the current directory, the command

java -classpath bin/nlfExample.jar;lib/nlf.jar NlfExample app-arguments

will run the NlfExample application with the arguments app-arguments.

3.1  Command-line arguments

Valid arguments are of two types: options and commands. Both must have '--' prefixed to them; there are no single-character short forms that have a single-hyphen prefix. The name and value of an option may be separated with whitespace or with a '=' character.

In keeping with convention, the command-line syntax for the NlfExample application (shown below and in response to the --help command) implies that the application is invoked with the command nlfExample. However, this is only a convention; the actual form of a command line that invokes NlfExample is described above.

Making the same assumptions as above, the following command line will run NlfExample, generating a temporary NLF, which is deleted when the program terminates. A plain-text representation of the NLF will be written to out.txt, and the NLF will be converted to XML and written to out.xml.

java -classpath bin/nlfExample.jar;lib/nlf.jar NlfExample --output out.txt --xml out.xml

4  What NlfExample does

When it is run with the --generate command, NlfExample generates an NLF document and writes the document to a file. It then reads and parses the document that it has just written, and writes a plain-text representation of the structure and content of the document to another file or to the console. If the appropriate option was specified, it also converts the NLF document to XML, and writes the resulting XML document to a file.

This procedure, pointless in itself, is intended to demonstrate some of the aspects of the uk.org.blankaspect.nlf API through inspection of its source code. The relevant source file is NlfProcessor.java, which contains Javadoc comments that describe the operation of the processor.

The text below is the output of a --generate command.

List-instance ID = NLF-Example
local namespace name = http://ns.blankaspect.org.uk/example/nlf/example-1
name = http://ns.blankaspect.org.uk/example/nlf/example-1|NLF-Example
pathname = NLF-Example
|
+-- Chunk ID = crc
|   name = http://ns.blankaspect.org.uk/example/nlf/example-1|crc
|   pathname = NLF-Example.crc
|   size = 4 (0x4)
|   data = (hex) B4 27 CE 15
|   =================================================================================
+-- List-instance ID = Alpha
|   local namespace name = http://ns.blankaspect.org.uk/example/nlf/poet-europe
|   name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|Alpha
|   pathname = NLF-Example.Alpha
|   [attr] text = "true"
|   [attr] language = "en-GB"
|   |
|   +-- Chunk ID = blake-rose
|   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|blake-rose
|   |   pathname = NLF-Example.Alpha.blake-rose
|   |   size = 22 (0x16)
|   |   data = "O rose, thou art sick!"
|   |   -----------------------------------------------------------------------------
|   +-- Chunk ID = blake-tyger
|   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|blake-tyger
|   |   pathname = NLF-Example.Alpha.blake-tyger
|   |   size = 30 (0x1E)
|   |   data = "In what furnace was thy brain?"
|   |   =============================================================================
|   +-- List-instance ID = Beta
|   |   local namespace name =
|   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|Beta
|   |   pathname = NLF-Example.Alpha.Beta
|   |   [attr] text = "true"
|   |   [attr] language = "fr-FR"
|   |   |
|   |   +-- Chunk ID = baudelaire-serpent
|   |   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|baudelaire-serpent
|   |   |   pathname = NLF-Example.Alpha.Beta.baudelaire-serpent
|   |   |   size = 33 (0x21)
|   |   |   data = "Tes yeux, où rien ne se révèle"
|   |   |   =========================================================================
|   |   +-- List-instance ID = Gamma
|   |   |   local namespace name = http://ns.blankaspect.org.uk/example/nlf/poet-usa
|   |   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-usa|Gamma
|   |   |   pathname = NLF-Example.Alpha.Beta.Gamma
|   |   |   [attr] text = "true"
|   |   |   [attr] language = "en-US"
|   |   |   |
|   |   |   +-- Chunk ID = whitman-myself
|   |   |   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-usa|whitman-myself
|   |   |   |   pathname = NLF-Example.Alpha.Beta.Gamma.whitman-myself
|   |   |   |   size = 43 (0x2B)
|   |   |   |   data = "The friendly and flowing savage, who is he?"
|   |   |   |   ---------------------------------------------------------------------
|   |   |   +-- Chunk ID = whitman-faces
|   |   |   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-usa|whitman-faces
|   |   |   |   pathname = NLF-Example.Alpha.Beta.Gamma.whitman-faces
|   |   |   |   size = 25 (0x19)
|   |   |   |   data = "Snakes nest in that mouth"
|   |   |   |   ---------------------------------------------------------------------
|   |   |   +-- Chunk ID = whitman-osceola
|   |   |       name = http://ns.blankaspect.org.uk/example/nlf/poet-usa|whitman-osceola
|   |   |       pathname = NLF-Example.Alpha.Beta.Gamma.whitman-osceola
|   |   |       size = 32 (0x20)
|   |   |       data = "When his hour for death had come"
|   |   |   =========================================================================
|   |   +-- Chunk ID = baudelaire-revenant
|   |   |   name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|baudelaire-revenant
|   |   |   pathname = NLF-Example.Alpha.Beta.baudelaire-revenant
|   |   |   size = 33 (0x21)
|   |   |   data = "Comme les anges à l’œil fauve"
|   |   |   -------------------------------------------------------------------------
|   |   +-- Chunk ID = baudelaire-voyage
|   |       name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|baudelaire-voyage
|   |       pathname = NLF-Example.Alpha.Beta.baudelaire-voyage
|   |       size = 42 (0x2A)
|   |       data = "Amer savoir, celui qu’on tire du voyage!"
|   |   =============================================================================
|   +-- Chunk ID = blake-london
|       name = http://ns.blankaspect.org.uk/example/nlf/poet-europe|blake-london
|       pathname = NLF-Example.Alpha.blake-london
|       size = 33 (0x21)
|       data = "The mind-forg’d manacles I hear"
|   =================================================================================
+-- List-instance ID = Delta
|   local namespace name =
|   name = http://ns.blankaspect.org.uk/example/nlf/example-1|Delta
|   pathname = NLF-Example.Delta
|   [attr] text = "true"
|   |
|   +-- Chunk ID = random
|       name = http://ns.blankaspect.org.uk/example/nlf/example-1|random
|       pathname = NLF-Example.Delta.random
|       size = 39 (0x27)
|       data = "C6C38F7D6C56291668C0D1CA95668B6B0349624"
=====================================================================================
The CRC value is correct.
Last modified: 2015-05-20