csw update docs

Summary

Update a metadata record for the xpath/value provided.

XPaths

The xpath (in accordance with JDOM x-path) does not start with the root element for example:

Given the metadata:

 <gmd:MD_Metadata>
     <gmd:fileIdentifier></gmd:fileIdentifier>
  <gmd:MD_Metadata>

The xpath

gmd:MD_Metadata/gmd:fileIdentifier

will NOT select any elements. Instead one must use the xpath:

gmd:fileIdentifier

to select the gmd:fileIdentifier element.

To update the root element of the metadata use the xpath: "" (empty string)

If the full xpath matches an existing element, this element is updated. Only the first match is updated if more than one match.

If a full match cannot be performed then the as much of the xpath as possible is matched from that point new elements are created. The rules for determining where the new path is created is as follows:

• The element that matches the longest part of the xpath will be used in preference to ones that match less of the xpath
• If multiple elements are matched with the same length of the xpath then the first element will be added to.
• Matches that match an attribute (and do not match the full xpath) are not considered since they cannot have child elements attached.
• In cases where there are conditionals in the path the portion of the path up-to and including the conditional MUST exist or no update can take place.
• For example. (*//gmd:RS_Identifier)[@nilReason = 'withheld']) must exist because it cannot be used to create new child elements.
• In the case where there are brackets in the xpath (()) then that portion of the xpath must match an existing element.

If there are no matches, each missing nodes of the xpath are created and the element inserted according to the schema definition. If the XPath does not match an existing element and a new element is to be created, the xpath is restricted in what it can contain. Specifically they can not contain any condition blocks (See section on conditional blocks) or any sibling or previous or ancestor declarations. SOme forbidden elements are:

• ..
• //
• ancestor::

If the end of the xpath is an attribute:

elem/@att

the attribute (att) of the element (elem) will be set instead of the text of the element.

Note: if an attribute is to be updated then the new value must be a string and not xml.

Update Value

The update value can be a String or an XML fragment.
The rules for updating an element with Xml is as follows:

• If the xml's root element is the same as the element selected by the XPATH then node is replaced with the element. For example:
  • Xpath: gmd:fileIdentifier
  • XML: <gmd:fileIdentifier gco:nilReason='withheld'>
  • Result: the gmd:fileIdentifier element in the metadata will be completely replaced with the new one. All attributes in the metadata will be lost and replaced with the attributes in the new element.
• If the xml's root element == 'gn_replace' (a magic tag) then the children of that element will be replace the element selected from the metadata.
• If the xml's root element == 'gn_add' (a magic tag) then the children of that element will be added to the element selected from the metadata.
• If the xml's root element != the name (and namespace) of the element selected from the metadata then the xml will replace the children of the element selected from the metadata.