Difference between revisions of "Creating projects and importing files"

From The SBN Wiki
Jump to navigation Jump to search
m (Raugh moved page Setting Up for Validation with ''Eclipse'' to Creating projects and importing files without leaving a redirect: Re-organization)
(No difference)

Revision as of 18:46, 2 September 2012

This page describes how to get started editing and validating XML files using eclipse. We'll use a set of sample files to configure the details of how eclipse interacts with XML and schemas, plus gain some experience with a few eclipse workbench basics.


Sample Files

This zip file contains a few schemas based on an older alpha-test version of PDS4 and a couple of labels that reference them. You can use them to check that your catalog file settings are working properly:

Download the file and unzip it into a temporary directory anywhere except your eclipse 'workspace' directory. (If you don't know where your 'workspace' is, start eclipse and it will tell you. If it doesn't, under the top menues select File->Switch Workspace->other... and the current workspace location will be highlighted.) The files will unpack into a directory called Play.


Creating a Project

Start up eclipse and look over the various windows and menus. (If you haven't already set your perspective to "XML", now would be a good time to do so.) There's not a lot going on at the moment. Eclipse organizes the work area by projects. You can think of a project as a sort of meta-directory: you can create files and directories underneath it, but the project file itself is just a bookkeeping mechanism. We want to play around with some schema files, so we'll have to start by creating a project to work in. Select File->New->Project, or right-click on the empty Project Explorer panel and select New->Project:

NewProjectLocation.png


You'll be presented with a dialogue box inviting you to select a wizard. We just want a plain, old project, so look under General for Project, select it and click Next>:

ProjectWizardLocation.png

Give your project a name. If, for some reason, you want to specify a workplace different from your default workplace to hold this project, now's your chance. We won't be using "working sets" for any of these PDS demos, so the rest of the dialogue can be safely ignored. Click on Finish and your project will be created. Mine's called Demo:

SeeNewProject.png


Importing Files into a Project

Now we need to import the files from the zip package we downloaded before into this new workspace. Since we want to import them into the workspace we just created, right click on the name of your new project and select Import...:

ProjectImportLocation.png

This will open the import dialogue box. Click on General to expand it and select File System - because we're importing files from elsewhere in our own file system. (You may find some of the other options intriguing - especially if you'll be using eclipse in a production environment. Explore those later.) Then click on the Next> button:

ImportDialogue.png

The next dialogue is for locating the files to be imported. Use the Browse... button to navigate to the place where you stashed the files, and select the top-level "Play" directory. Here's what the result looks like on my system:

ImportPlayForSelect.png

I don't really need an extra subdirectory in my project, so in the window on the right I check both XML files listed, and then in the window on the left I expand Play and check the two subdirectory boxes (Dictionaries and Schema). You'll see in the window on the right that when you check, for example, the Dictionaries folder on the left, all the files in it automatically appear checked in the window on the right. You can select and de-select files individually when you're importing folders.

I want to put these all in my Demo folder, which is what comes up by default (since I started by right-clicking on Demo), so we're OK there. There should be nothing to overwrite and I don't need more folders at this point, so the other options I'm leaving unchecked. Similarly for the Advanced... options. Here's what that all looks like just before I hit the Finish button:

ImportPlaySelections.png


And afterwards, if I expand the Demo folder and its subfolders in my Project Explorer window, I now see this:

DemoAfterImport.png


Checking out the Test Files

Now's a good time to browse what you've just imported. There are several ways to open a file - double click on it, right click and select Open, or via a function key. Close a file by clicking on the X in its editor tab. Go ahead and explore the interface a little. I'll wait...


OK, so here's what's in the test files package:

collection_1.0.xml
A PDS4-type label for a very simple collection. This is based on an early version of the schemas - it is not valid under the current version, so don't use it as a template for real work!
hi0173794441_9080000_001_rr.xml
A mock-up of a label for a product from the Deep Impact mission. Once again, this would not be valid with the current PDS4/Deep Impact/SBN schemas and dictionaries, so don't try to re-use it.
Dictionaries/
Contains mock-ups of local dictionaries. These really don't look like the final working format - they're just here to demonstrate how XML files can reference multiple schemas defining different namespaces.
Schemas/
This directory contains two different (and incompatible) preliminary versions of the PDS4 master schema and the associated Schematron file for each.


XML Catalog File Configuration

XML Catalog files provide a map from logical references in the schema and label files to physical copies of the defining PDS4 schemas that you've stashed in a directory somewhere on your system. Since PDS labels should not contain links to local versions of, for example, the namespace-defining schemas, this is a critical component to get right. Plus learning how to create and edit XML Catalog files will make your life easier in the long run if you're planning to do more than a little PDS4 label development.

Let's start by opening the collection_1.0.xml file (double-click it or whatever). If this is the first time you're opened a file in eclipse, it will probably open in "Design" view, which looks like this:

DesignView.png

Click on the Source tab at the bottom left of the editor pane to see the source code:

SourceView.png


The very first line declares that this is an XML file following version 1.0 of the XML standard and using UTF-8 character encodings. We'll come back to the <?xml-model> processing instruction in a minute. Let's focus our attention on the first line of the actual label:

   <Product_Collection xmlns="http://pds.nasa.gov/pds4/pds/v08"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

More specifically, examine the values of the two xmlns attributes. The xmln attribute tells the processing program (in this case, eclipse) that a particular namespace will be reference - the implication being that if you wish to be successful in processing the XML to follow, you should educate yourself on the details of that namespace. If your a program that wants to, for example, validate the content that follows, you'd better be able to find and read the schema document(s) that defines that namespace.

So in the <Product_Collection> we see references to two namespaces:

  xmlns="http://pds.nasa.gov/pds4/pds/v08"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

The first reference you will come to know and love, or at least recognize, as the PDS4 common namespace, in this case with a version number ("v08") indicating it is a pre-release draft. Unless otherwise stated, everything in the label is presumed to come from the pds namespace. How do I know? Because there is no namespace prefix specified, as there is for the second namespace ("xsi", in this case). So any time I see an element name, like Product_Collection, without a namespace prefix, I assume it is from the pds namespace.


What difference does it make? Try to validate this label. One way to do that is to right-click on the file name in the Project Explorer window, go about halfway down the menu, and select Validate. When you do that, you'll see a warning in the Problems pane below the editing pane:

NoGrammarConstraintsWarning.png

This is eclipse telling you that it can't do much validating unless you tell it what to validate against. Since we have the PDS4 master schema that we want to validate against, now's the time to set up an XML Catalog entry so eclipse can turn that namespace reference into a schema file location.

XML Catalog information is configured as one of the items in the Window->Preferences menu. Look towards the bottom for XML, expand it, and click on XML Catalog to see the current catalog entries:

XMLCatalogPreferences.png

The "User Specified Entries" list is where we can create additional entries to translate namespace URIs, like http://pds.nasa.gov/pds4/pds/v08</code>, into references to the copy of the master PDS4 schema file that you'll find in the Schema subdirectory of our demo project. Click the Add... button to get to this dialogue box:

AddXMLCatalogElementsBlank.png

Eclipse maintains the XML catalog internally, so we'll be adding single entries to it via this dialogue box. We're doing straightforward mappings, so select Catalog Entry from the top of the column of icons on the left.

We want to add a reference to the PDS4 master schema which we know is in our current workspace, so click the Workspace button, navigate down into the Schema folder and select the PDS4_PDS_0800k.xsd file.

XMLCatalogPref1.png

(Alternately, you can click the File System... button and select the file by navigating to it in the usual way. Either method will work, the point being that you can have a local schema repository that is not part of your personal workspace - a handy thing for group development.)

Once you've selected the schema file and clicked the OK button, eclipse sets the Key type: value to "Namepsace name" in the XML Catalog Element dialogue because it recognizes that the schema defines a namespace. This in turn a) means it successfully found and opened the file, and b) saves you the trouble of cutting and pasting the namespace into the Key: box. At this point, you can click the OK button and you'll be returned to the XML Catalog Preferences dialogue box, this time showing the new User Specified entry:

XMLCatalogPref2.png

Note that you can edit and remove the entry you just made if you find that something went wonky. We only need this one catalog mapping for the collection_1.0.xml label, so click OK and let's try it out. Right-click on the file name again, select Validate, and the warning in the Problems pane should disappear and you'll see a pop-up telling you the validation completed with no errors or warnings (note that you can turn this pop-up off if you like by checking the "Do not show this dialog in future" box in the pop-up.