New DataPackage class for Morpho for handling EML2 and other metadata content standards

It is desired to create a new class for representing 'generic' dataPackage objects, with EML2 being the immediate goal. It is desired, however, to avoid being too specific so that changes in standards can easily be configured without major code re-writes. This memo attempts to describe the current design.



A simplified class diagram is shown below for discussion purposes.


MetadataObject  <----------------  AbstractDataPackage  <---------- EML200DataPackage
                                                        <---------- NBIIBioDataPackage       <----DataPackageFactory
                                                        <---------- EML2Beta6DataPackage            


The base class is 'MetadataObject'. Basically, this class just a DOM structure containing the metadata for a defined schema (the 'schemaGrammer'(i.e. doctype) is also a member variable for the class) . There is also a member called the 'xpathKeyMap'. This is supposed to be a reference to a set of mappings between generic concepts (e.g. the package name) and the specific DOM xpath to the node in the specific DOM that contains the actual concept. This map is stored in a properties file of some type (e.g. an XML file) that is read at run time. Thus, minor changes in a schema can be handled by just updating this properties file rather than changing the code.

Now, the 'AbstractDataPackage' class extends the very general purpose 'MetadataObject' class and is meant to be used specifically for representing dataPackages of different types. The class is call 'Abstract...' because there are certain actions (like 'load' and 'serialize' that a specific to the schemaGrammar. Thus the 'AbstractDataPackage' class is extended by various schema specific classes such as the three shown above (i.e. EML200DataPackage, NBIIBioDataPackage, and EML2Beta6DataPackage). Note that the xpathKeyMap used is different for each of these specific package classes.

Finally, the DataPackageFactory class is used to create a new datapackage object from a supplied DOM or from a docID of a document on metacat or stored locally. A factory method is needed so that it can determine just what schema is desired and which of the specific package classes should be used to create the object. Once created, however, methods in the AbstractDataPackage that are generic can be used to get information stored in the package.
            

xpathKeyMap
	Consider now how the xpathKeyMap works. An example in XML format for eml200 is reproduced below. It should be noted that this example is organized as a set of 'contextNode' elements. The 'package' contextNode corresponds to the root of datapackage DOM while other contextNodes, like 'entity' refer to some node in the dom other than the root. The contextNode serves as the point of departure for XPath searches. The concept allows for relative searche - e.g. one can give paths relative to the entity context node.

	An example of xpathKeyMap use is the problem of finding the "accessionNumber" for a generic metadata schema. The document below has an 'accessionNumber' element under the 'package' contextNode. It's value for eml2 is seen to be '/eml:eml/@packageId'. ONe first looks up this value in the xpathKeyMap and then applies the xpath to the eml2 dataPackage dom. We have thus added a level of indirection where specific paths are looked up in the xpathKeyMap using generic path names.

	As another example, one would look at the 'name' element under the 'entity' contextNode to get an entity name. In this case the relative path is simply 'entityName'. But how does one get the actual entity contextNode where the relative path starts? In this example, the higher level 'entities' element under the package contextNode is an xpath that will return a NodeSet of entity nodes in the eml2 dom. Each of these nodes is a starting point for the entity information (i.e. the root of the entity subtree).


<?xml version="1.0"?>  
<xpathKeyMap schemaGrammar="eml2.0.0">
<!-- element name is key, element value is Xpath for this grammar -->
  <contextNode name="package"> 
    <entities>/eml:eml/dataset/dataTable</entities> 
    <title>/eml:eml/dataset/title</title>
    <author>/eml:eml/dataset/creator/individualName/surName</author>
    <accessionNumber>/eml:eml/@packageId</accessionNumber>
    <keywords>/eml:eml/dataset/keywordSet/keyword</keywords>    
  </contextNode>
  <!-- Xpaths for entity values are defined as relative to top node of entity -->
  <contextNode name="entity"> 
    <name>entityName</name>
    <numRecords>numberOfRecords</numRecords>
    <entityDescription>entityDescription</entityDescription >
    <physical>physical</physical>
    <attributes>attributeList/attribute</attributes>
  </contextNode>
  <contextNode name="attribute"> 
    <name>attributeName</name>
    <dataType>storageType</dataType>
    <isText>count(measurementScale/nominal|measurementScale/ordinal)!=0</isText>
    <isDate>count(measurementScale/datetime)!=0</isDate>
  </contextNode>
  <contextNode name="physical"> 
    <name>objectName</name>
    <fieldDelimiter>dataFormat/textFormat/simpleDelimited/fieldDelimiter</fieldDelimiter>
    <numberHeaderLines>dataFormat/textFormat/numHeaderLines</numberHeaderLines>
    <size>size</size>
    <format>dataFormat/externallyDefinedFormat/formatName</format>
    <isText>count(dataFormat/textFormat)!=0</isText>  
    <distribution>distribution</distribution>
  </contextNode>
  <contextNode name="distribution">
    <isOnline>count(online/url)!=0</isOnline>
    <url>online/url</url>
    <isInline>count(inline)!=0</isInline>
    <inline>inline</inline>
  </contextNode>
</xpathKeyMap>