data.web.tutorials-01.jsp Maven / Gradle / Ivy
Show all versions of ddmsence Show documentation
DDMSence: Tutorial #1 (Essentials)
<%@ include file="../shared/header.jspf" %>
Tutorial #1: Essentials
Essentials is a simple reader application which loads an XML file containing a DDMS Resource and displays it in three different formats: the
original XML, HTML, and Text. 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 three separate panes.
Figure 1. The three output formats
The top pane contains the result of calling toXML() on the Resource object. It should be identical to the data from the file.
The two lower panes contain the results of calling toHTML() and toText(), 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);
// The three output formats
String xmlFormat = getResource().toXML();
String htmlFormat = getResource().toHTML();
String textFormat = getResource().toText();
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, and Text 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 XML file is initially validated by the underlying XML parsers to confirm that it is well-formed and adheres to the DDMS schema.
- As the objects are built in Java, the schema rules are revalidated in Java. This is not essential for file-based metacards, but
becomes more important when we are building from scratch.
- Next, any rules mandated in the DDMS Specification but not implemented in the schema are validated (such as constraints on latitude/longitude values). This is done with
custom Java code, and you can create your own rules with ISO Schematron.
- Any warnings which do not actually result in an invalid component are stored on the component, and can be retrieved via
getValidationWarnings().
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.
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
<%@ include file="../shared/footer.jspf" %>