Tutorial #1: Essentials

Essentials is a simple reader application which loads an XML file containing a DDMS Resource and displays it in four different formats: the original XML, HTML, Text, and JSON. The source code for this application provides an example of how to create DDMS components from an XML file.

Getting Started

Essentials can be run from the command line with the class, buri.ddmsence.samples.Essentials. The application accepts a single optional parameter: the name of a file to load upon startup.

Please see the "Getting Started" section for classpath details and command line syntax.

Walkthrough

When the application first opens, go to the File menu and choose Open.... You will be able to select an XML file containing a DDMS resource (also called a "metacard"). Sample files from various versions of DDMS can be found in the data/sample/ directory. Let's start by selecting the sample file, 3.1-identifierPostalAddressExample.xml and clicking on the Open button.

Figure 1. Selecting an existing DDMS Record from an XML file

The application will convert the XML file into a Java object model and then display the results in four separate tabs.

Figure 1. The four output formats

The first tab contains the result of calling toXML() on the Resource object. It should be identical to the data from the file. The next three tabs contain the results of calling toHTML(), toText(), and toJSON(), respectively, on the Resource object.

Now, let's take a look at the source code in /src/samples/buri/ddmsence/samples/Essentials.java to see how this was accomplished. The important lines are found in the loadFile() method. First, we try to guess the version of DDMS used in the file, based upon the XML namespace. Next, we create a DDMSReader instance that will load the file. Finally, we store the loaded resource in the _resource variable:

DDMSVersion fileVersion = guessVersion(file);
// The DDMS reader builds a Resource object from the XML in the file.
_resource = getReader(fileVersion).getDDMSResource(file);

// Apply pretty-printing to JSON
PropertyReader.setProperty("output.json.prettyPrint", "true");

// The four output formats
String xmlFormat = getResource().toXML();
String htmlFormat = getResource().toHTML();
String textFormat = getResource().toText();
String jsonFormat = getResource().toJSON();

Figure 3. The main Essentials code

The remaining code in this method merely renders the data on the screen.

As you can see from the code, building an object model from an XML file only requires a single-line call to DDMSReader.getDDMSResource(). The conversion of the Resource into XML, HTML, Text, and JSON is built-in to the Object. The primary purpose of the DDMSReader class is to load a metacard from an XML file. You can also use the getElement() methods of the DDMSReader to load XOM Elements representing any of the global DDMS components.

Now that you have seen a valid Resource, let's try opening an invalid one. Return to the File menu and select the sample file, 3.0-invalidResourceExample.xml from the samples directory. This XML file is invalid, because it tries to use an incorrect security classification (SuperSecret).

Opening this file should display the following error message:

Could not create the DDMS Resource: nu.xom.ValidityException: cvc-enumeration-valid: 
Value 'SuperSecret' is not facet-valid with respect to enumeration '[U, C, S, TS, R, CTS, 
CTS-B, CTS-BALK, NU, NR, NC, NS, CTSA, NSAT, NCA]'. It must be a value from the enumeration. 
at line 18, column 110 in file:///DDMSence/data/sample/3.0-invalidResourceExample.xml

Figure 4. A sample error message

This error comes from the underlying XML-parsing libraries which are attempting to validate the XML file against the DDMS schema before building the object model. Objects are always validated upon instantiation, so it is impossible to have fully-formed, but invalid DDMS components at any given time.

Validation from an XML file proceeds in the following order:

The Essentials program can open metacards of any supported DDMS Version. An example is provided in the file, 2.0-earlierVersionExample.xml. Working with a other versions of DDMS is covered in the Power Tips section.

Output Formats

The HTML and Text output formats are based upon the suggestions in the DDMS specification. Where the specification is unclear or inconsistent, DDMSence attempts to be consistent across components. Specific instances where DDMSence diverges from the DDMS suggestions are noted in the class comments for the affected components.

The DDMS specification provides no guidance on JSON output, but the format is generally based upon the patterns used in the HTML and Text outputs. If you are unsure of how the JSON output will appear for a particular component, you can use the Essentials application as a visual aid. Here are a few rules of thumb which describe this format:

Additional configurable properties are available to control the formatting of the output.

Conclusion

In this tutorial, you have seen how DDMS Resources can be built from an existing XML file and transformed into various outputs. You have also had a small taste of the validation that occurs when a Resource is built.

The next tutorial, covering the Escort application, will show how a DDMS Resource can be constructed from scratch.

<ddms:identifier
   ddms:qualifier="http://metadata.dod.mil/mdr/ns/MDR/0.1/MDR.owl#URI"
   ddms:value="http://www.whitehouse.gov/news/releases/2005/06/20050621.html" />

Figure 5. A DDMS Identifier element in XML

Identifier identifier1 = new Identifier("http://metadata.dod.mil/mdr/ns/MDR/0.1/MDR.owl#URI",
   "http://www.whitehouse.gov/news/releases/2005/06/20050621.html");

Figure 6. Building a DDMS Identifier from scratch

Tutorial #1: Essentials (you are here)
Tutorial #2: Escort
Tutorial #3: Escape
Back to Samples Documentation