Extracting Metadata - Merging Metadata
(Page 22 of 22 )
Merging metadata into a monolithic metadata file combines identical elements for seamless use in code generation. The merge process is complicated by one additional twist. The organization of the metadata—where things are found— should be independent from the metadata source. This means information from different sources can’t just be appended to the same file but must be seamlessly intermixed in an intimate merge.
In Chapter 3 you’ll see how to combine multiple processes, including merge processes, into one script. You’ll see how to use a script to determine the order in which files are merged. Doing this at the last minute allows you to handle the monolithic file as a transient and leave it out of source control. This is really helpful when you have several people doing independent code generation on different parts of your application or closely related applications. Even though the file is transient, you need a copy of the most recent version for debugging, so you’ll save it to disk.
There are two types of metadata files: those that contain a root element corresponding to a section in the output metadata file and those that contain a different root element that contains the attribute FreeForm="true". This small difference indicates a broader difference in the history of the files. Although it isn’t technically required, files corresponding to a single metadata header are programmatically created. Files where the root node wraps one or more child nodes corresponding to section headers are manually created as freeform metadata files. Including the high-level root, even when you’re editing a single section, allows you to add additional sections with minimal disruption. Combining several section headers in a single freeform file helps keep files from getting too small and scattered.
The merge is cumulative. It adds new child elements where they’re missing and new attributes to existing elements. If the same attribute appears for the same element in multiple merge source files, the last one wins and will overwrite the previous values. The expectation is that you’ll merge manual freeform meta-data last and allow it to overwrite any values extracted programmatically. This allows you to smoothly override values, but be sure you debug against the monolithic metadata file.
CAUTION -- Because each metadata file can overwrite values in other metadata files as they’re merged, use a copy of the monolithic file to check input during debugging.
The merge process is short and recursive, so I’ll walk through the code. The MergeFreeForm class has a single public method that accepts an XML output document and a filename. It loads the file and checks the FreeForm attribute. If it doesn’t exist or doesn’t have a value of true, then the root is treated as the metadata section header. If the attribute is true, then the second-level nodes are treated as the section headers. This is the only difference between the two types of source files:
Public Class MergeFreeForm
Public Shared Sub Merge( _
ByVal outDoc As Xml.XmlDocument, _
ByVal fileName As String)
Dim mergeDoc As New Xml.XmlDocument
Dim rootNode As Xml.XmlNode
mergeDoc.Load(filename)
rootNode = mergeDoc.ChildNodes(1)
If Tools.GetAttributeOrEmpty(rootNode, "FreeForm") = "true" Then
' If its a freeform file, regardless of the root element name,
' attempt to merge all child nodes of root
For Each node As Xml.XmlNode In rootNode.ChildNodes
MergeNode(outDoc.ChildNodes(1), node, Nothing)
Next
Else
MergeNode(outDoc.ChildNodes(1), rootNode, Nothing)
End If
End Sub
The MergeNode method is recursive. It searches the target file for an element matching the source node’s element name and a matching value of the Name attribute (if the Name attribute is present). This step is simple and unambiguous because it assumes precisely the same structure in the source and target node. If the SelectSingleNode method doesn’t find the node already in the target, the node is added. If SelectSingleNode finds the node, MergeNode checks the target node for the presence of each attribute from the source node. If the attribute doesn’t exist yet, it’s created. If the attribute exists, its value is updated:
Private Shared Sub MergeNode( _
ByVal outParent As Xml.XmlNode, _
ByVal node As Xml.XmlNode, _
ByVal nameAttrib As Xml.XmlAttribute)
Dim nsmgr As New Xml.XmlNamespaceManager(outParent.OwnerDocument.NameTable)
Dim predicate As String = ""
nsmgr.AddNamespace(node.Prefix, node.NamespaceURI)
If Not nameAttrib Is Nothing Then
predicate = "[@Name='" & nameAttrib.Value & "']"
End If
Dim testNode As Xml.XmlNode = outParent.SelectSingleNode( _
node.Name & predicate, nsmgr) If testNode Is Nothing Then outParent.AppendChild(outParent.OwnerDocument.ImportNode(node, True))
Else
' Node exists, add attributes, then children
For Each attrib As Xml.XmlAttribute In node.Attributes
If testNode.Attributes(attrib.Name) Is Nothing Then testNode.Attributes.Append(xmlHelpers.NewAttribute( _ testNode.OwnerDocument, attrib.Name, attrib.Value))
Else
testNode.Attributes(attrib.Name).Value = attrib.Value
End If
Next
CAUTION -- Attribute values are overwritten. The last value wins.
Finally, MergeNode recursively calls itself for all child nodes. If you aren’t familiar with recursive algorithms, you might have to look at this a couple of times, but it’s a nice example of a simple, effective recursive algorithm. You’ll see recursive algorithms frequently in this book because they’re so handy when you’re working with nested data such as XML documents:
For Each childNode As Xml.XmlNode In node.ChildNodes
MergeNode(testNode, childNode, childNode.Attributes("Name"))
Next
End If
End Sub
End Class
Namespace usage might be a little confusing here. I’m assuming you’ll prefix everything, including your freeform data. I anticipate you may use different namespaces for different sections of your metadata. Thus, the name-space manager is created for the current node. Namespace prefixes are discussed in Appendix A . The key factor here is that the XPath expression’s prefix will be from the node you’re searching for—from the source document you’re merging from.
It doesn’t matter whether this prefix matches the target prefix as long as the namespaces pointed to by both prefixes match. This code will work just fine even if you vary the prefix you’re using for a specific namespace. But don’t do that! A major problem will arise if you add any new elements. These new elements will have a prefix from the source and won’t be understood in the context of the target document. You could work on solving this problem, but I can’t imagine a reason you’d use different prefixes for the same namespace in different source documents. It’d be really hard for a maintenance programmer to keep up with the mental calisthenics of switching from one prefix to another.
TIP Use consistent namespaces.
Summary Extracting metadata is the process of gathering information from metadata sources and organizing it as an XML file that’s friendly to code generation. Available types of metadata include the following:
- Schema definitions such as XSD
- Databases such as SQL Server
- Web Services via WSDLs
- Manually entered freeform metadata
- External sources, such as mainframes, Excel, and so on
- Existing applications and source code
- Design tools such as UML
If you’re working with XSD, it’s helpful to convert the XSD to friendly XML prior to code generation.
To extract from SQL Server, Oracle, or another SQL-92 compliant databases, use the SQL-92 information schema views. Extracting most metadata from databases is straightforward, but stored procedure intent, recordset naming, and the mapping between columns and the underlying data columns are difficult. Going to the trouble of extracting this information provides richer information for code generation. You can get this information via careful naming and inference, extended properties, or manually entered freeform data.
You can use freeform metadata to include any additional metadata. This freeform metadata can be manually entered or programmatically derived. In the intimate merge of metadata described in this chapter, files that merged later can overwrite previously merged files. This allows you to incorporate manual overrides late in the merge process.
Additional Reading To find more information about the topics covered, try the following resources:
- In addition to covering Web Services , Building XML Web Services for the Microsoft .NET Platform by Scott Short (Microsoft Press, 2002) contains some concise sections on other X-Stuff subjects, including XSD.
- Professional UML with Visual Studio .NET by Andrew Filev, Tony Loton, Kevin McNeish, Ben Schoellmann, John Slater, and Chaur G. Wu (Wrox, 2002) discusses using UML with Visual Studio and discusses Visio’s limited code generation capabilities.
 This is from Code Generation in Microsoft .NET, by Kathleen Dollard (Apress, ISBN 1590591372). Check it out at your favorite bookstore today. Buy this book now. |
| DISCLAIMER: The content provided in this article is not warranted or guaranteed by Developer Shed, Inc. The content provided is intended for entertainment and/or educational purposes in order to introduce to the reader key ideas, concepts, and/or product reviews. As such it is incumbent upon the reader to employ real-world tactics for security and implementation of best practices. We are not liable for any negative consequences that may result from implementing any information covered in our articles or tutorials. If this is a hardware review, it is not recommended to open and/or modify your hardware. |
/ 17 
