com.esri.arcgis.geodatabase
Interface IXmlPropertySet

All Superinterfaces:
Serializable
All Known Implementing Classes:
XmlPropertySet

public interface IXmlPropertySet
extends Serializable

Provides access to members that manage metadata.

Superseded By

IXmlPropertySet2

Remarks

XSL Patterns (also known as XPath), a way to select a node or groups of nodes that match a selection criteria, are used as parameters in several IXmlPropertySet methods and properties (CountX property, DeleteProperty method, SetAttribute method, SetPropertyX method, and SimpleGetProperty method). XSL Patterns provide a simple query language for identifying nodes in an XML document based on attribute, name, and values.

An important point when using XSL patterns is that the names of properties and attributes, as well as the values of both, are case sensitive. Also, because metadata always has a <metadata> root node, it can be omitted from patterns used with this interface. For example, "/metadata/node/subnode" should just be "node/subnode".

Some basic examples of XSL patterns include:

For more examples of XSL patterns, see the MSDN article, XPath Examples. The Microsoft XML SDK (xmlsdk25.exe) also contains a good tutorial.

When using this interface on a newly-created XmlPropertySet, the property set should be cast to the IXmlPropertySet2 interface and the InitGeneric method should be called (with the exception of when working in VB6 or VBA). See the XmlPropertySet coclass documentation for more information.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux


Method Summary
 void deleteProperty(String name)
          Deletes the specified elements.
 void deletePropertyByAttribute(String attribute, String value, boolean deleteParent)
          Deletes the elements which have the specified attribute value.
 int getCountX(String name)
          Number of occurrances of an element in the metadata.
 void getPropertiesByAttribute(String attribute, String value, boolean noValues, Object[] tags, Object[] values)
          Returns the set of names and values for elements which have the specified attribute value.
 void initExisting()
          Initializes an XmlPropertySet and adds the Esri group of elements.
 boolean isNew()
          Indicates if a new XmlPropertySet was created on retrieving the metadata.
 void saveAsFile(String xslPath, String header, boolean outputANSI, String[] outPath)
          Transforms the metadata using an XSL stylesheet if specified, writes out the header if specified, and saves it in a file.
 void setAttribute(String name, String attribute, Object value, int action)
          Sets the attribute of the specified element.
 void setPropertyX(String name, Object value, int propType, int action, boolean syncing)
          Sets the value of the specified element.
 String simpleGetProperty(String name)
          The values of the specified property.
 void transformImages(String path, Object[] fileNames)
          Transforms encoded thumbnail and image enclosures to files and links them into the metadata.
 

Method Detail

getCountX

int getCountX(String name)
              throws IOException,
                     AutomationException
Number of occurrances of an element in the metadata.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Parameters:
name - The name (in)
Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getPropertiesByAttribute

void getPropertiesByAttribute(String attribute,
                              String value,
                              boolean noValues,
                              Object[] tags,
                              Object[] values)
                              throws IOException,
                                     AutomationException
Returns the set of names and values for elements which have the specified attribute value.

Description

The GetPropertiesByAttribute method returns the set of metadata elements where the specific XML attribute has the specified value.

Remarks

The Attribute parameter specifies the name of the attribute within the Xml metadata element. The Value parameter is the string the attribute is evaluated to or equals. For instance in the example <idinfo/citation/citeinfo/title Sync="TRUE"> the Sync Attribute has a Value of "TRUE".

When used to retrieve a property of type esriXPTBinaryEnclosure or esriXPTImage, the file is extracted from the metadata to a temporary directory and the path of the file is returned as the value. With properties of type esriXPTPicture, the value is an IPicture.

The noValues parameter is currently reserved and has no effect.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
attribute - The attribute (in)
value - The value (in)
noValues - The noValues (in)
tags - A Variant (out: use single element array)
values - A Variant (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
XmlPropertySet.setAttribute(String, String, java.lang.Object, int),

The pTags and pValues parameters must be of Objects. pTags returns the Xml metadata tags ("idinfo/citation/citeinfo/title"), while the corresponding pValues returns the value held within the opening and closing tags ("New Title").


setPropertyX

void setPropertyX(String name,
                  Object value,
                  int propType,
                  int action,
                  boolean syncing)
                  throws IOException,
                         AutomationException
Sets the value of the specified element.

Description

The SetPropertyX method uses uses XSL Patterns to specify metadata elements. The method then adds or replaces the element value.

Remarks

The Name parameter uses XSL Patterns to specify metadata elements. Additional information on XSL Patterns can be found in the IXmlPropertySet documentation. The Value parameter is the property the will be set to.

The propType parameter is a required esriXmlPropertyType constant. By selecting the constant, the type of data stored within the metadata element (normal text, generic binary enclosures, images, links, picture object, binary enclosures containing an image) is set.

The Action parameter is a esriXmlSetPropertyAction constant. These constants allows several options when encountering different scenarios in metadata. The esriXmlSetPropertyAction constants work differently depending on the presence/absence of the XML element. It is important to be familiar with the different actions. For instance, if the Name expression fails to located the specified XML element, all esriXmlSetPropertyAction constants (except esriXSPAReplaceIfExists) will add the XML element. The table below better explains the action constants:

Action Constant Element Exists Element Does Not Exist
esriXSPAAddOrReplace Replaces element Adds a new element
esriXSPAAddIfNotExists Nothing happens Adds a new element
esriXSPAReplaceIfExists Replaces element Nothing happens
esriXSPAAddDuplicate Adds an additional element Adds a new element

The Boolean syncing parameter provides an additional degree of control when creating or modifying an element. The parameter indicates whether or not synchronization is taking place. The parameter's setting can override the action parameter. When creating a new element, if the parameter is true, the element is given a Sync attribute with a value of "TRUE". When modifying an existing element, if the syncing parameter is false the element is always modified, and if it has a Sync attribute, the attribute is removed. If the syncing parameter is true when modifying an element, the element's Sync attribute is first inspected; if it has a value of "TRUE", modification occurs, but if it has another value (or no Sync attribute) the modification will not occur.

More information can be found in the white paper "Synchronization in ArcCatalog" May. 2001.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
name - The name (in)
value - A Variant (in)
propType - A com.esri.arcgis.geodatabase.esriXmlPropertyType constant (in)
action - A com.esri.arcgis.geodatabase.esriXmlSetPropertyAction constant (in)
syncing - The syncing (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
XmlPropertySet.setAttribute(String, String, java.lang.Object, int)

deleteProperty

void deleteProperty(String name)
                    throws IOException,
                           AutomationException
Deletes the specified elements.

Description

The DeleteProperty method removes the specified XML element(s) within an XML document, including all elements contained by the specified elements.

Remarks

The Name parameter uses XSL Patterns to describe the location and condition of XML nodes in metadata. XSL Patterns includes a set of expressions, allowing for more defined queries and filters. More information on XSL Patterns can be found in the IXmlPropertySet documentation.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
name - The name (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet.setPropertyX(String, java.lang.Object, int, int, boolean), IXmlPropertySet.deletePropertyByAttribute(String, String, boolean)

deletePropertyByAttribute

void deletePropertyByAttribute(String attribute,
                               String value,
                               boolean deleteParent)
                               throws IOException,
                                      AutomationException
Deletes the elements which have the specified attribute value.

Description

If true,the Boolean deleteParent parameter removes of the metadata parent element. As an example, the following line of code:

    pXPS.DeletePropertyByAttribute "approved", "no", True

not only deletes the "idinfo/timeperd/timeinfo/sngdate/caldate" element, but also deletes the parent "idinfo/timeperd/timeinfo/sngdate" element.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
attribute - The attribute (in)
value - The value (in)
deleteParent - The deleteParent (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet.getPropertiesByAttribute(String, String, boolean, Object[], Object[]), IXmlPropertySet.deleteProperty(String)

simpleGetProperty

String simpleGetProperty(String name)
                         throws IOException,
                                AutomationException
The values of the specified property.

Remarks

The SimpleGetProperty method returns the value of the specified Name expression as string.

The Name expression uses XSL Patterns to locate and process items in XML documents. XSL Patterns includes a small set of expressions that allow for more defined queries and filters. More information on XSL Patterns is available at IXmlPropertySet Interface.

Requesting a property which contains other properties will return the name of one of the child properties.

Using this method to locate Enclosures and Images will extract the files to a temporary directory (if not already extracted) and return the path to the temporary files. Using it to request a property of type Picture will return an IPicture reference.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
name - The name (in)
Returns:
The value
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet.getPropertiesByAttribute(String, String, boolean, Object[], Object[]), IXmlPropertySet.getCountX(String)

saveAsFile

void saveAsFile(String xslPath,
                String header,
                boolean outputANSI,
                String[] outPath)
                throws IOException,
                       AutomationException
Transforms the metadata using an XSL stylesheet if specified, writes out the header if specified, and saves it in a file.

Remarks

The xslPath parameter is the path of the stylesheet to use when creating output. The stylesheet determines the type of file created by this method (examples are HTML and text files). The location of ESRI-provided stylesheets differs depending on the version of ArcGIS. The xslPath parameter must be specified when programming in VB6 or .NET. It is not mandatory in C++, but if none is specified XML is the default output.

If included, the string header is placed before the root object. A placeholder (an empty string) is still necessary even if header is not included.

Unless the boolean parameter outputANSI is true the output file will be Unicode. No differences are found between the two formats for XML, HTML, or Text documents. The outputANSI parameter is used for the FGDC utility MP which only supports ANSI.

The outPath defines the location for the files to be saved. If a file already exists, it is overwritten. A valid outPath string must be specified, otherwise output is not created.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
xslPath - The xslPath (in)
header - The header (in)
outputANSI - The outputANSI (in)
outPath - The outPath (in/out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isNew

boolean isNew()
              throws IOException,
                     AutomationException
Indicates if a new XmlPropertySet was created on retrieving the metadata.

Remarks

The IsNew Boolean property reflects the initial state of the XML metadata document when accessed. If no metadata document exists when accessed, a new metadata document is created containing the ESRI defined tags (these are used by ArcCatalog to maintain the metadata document) "ESRI, MetaID, CreaDate, CreaTime, SyncOnce", and the Boolean attribute IsNew is set to "True". If an XML metadata file exists when initially accessed, the Boolean property is False.

Even if the options to automatically create metadata (available though the user interface from the Tools Menu > Option Command > Metadata Tab) have been unchecked, metadata is still created when accessed programmatically.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Returns:
The isNew
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet.initExisting()

setAttribute

void setAttribute(String name,
                  String attribute,
                  Object value,
                  int action)
                  throws IOException,
                         AutomationException
Sets the attribute of the specified element.

Remarks

The SetAttribute method adds or replaces XML attributes and sets the attribute value.

If the Name expression defines repeating elements, the SetAttribute method will change all elements that satisfy the XSL pattern. For instance "idinfo/keywords/theme/themekey" locates all theme keywords. For more information on XSL patterns, see the IXmlPropertySet interface.

The Action parameter is a esriXmlSetPropertyAction constant. These constants allow several options when encountering different scenarios in metadata. Possible scenarios range from metadata elements which already exist and have attribute value to non-existent metadata elements. How to handle the different cases is determined by the Action parameter. The esriXmlSetPropertyAction constants work differently depending on the presence/absence of the XML element as well as the presence/absence of the attribute. It is important to be familiar with the different actions. For instance, if the Name expression fails to located the specified XML element, all esriXmlSetPropertyAction constants, except "Replace If Exist", will Add the XML element, attribute, and attribute value. The table below better explains the action constants:

Action Constant Element and Attribute Exist Element exists, Attribute does not Element does not exist
esriXSPAAddOrReplace Replaces attribute value Adds attribute and value Adds element, attribute and value
esriXSPAAddIfNotExists Nothing happens Nothing happens Adds element, attribute and value
esriXSPAReplaceIfExists Replaces attribute value Adds attribute and value Nothing happens
esriXSPAAddDuplicate Adds additional element, attribute and value Adds additional element, attribute and value Adds element, attribute and value

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
name - The name (in)
attribute - The attribute (in)
value - A Variant (in)
action - A com.esri.arcgis.geodatabase.esriXmlSetPropertyAction constant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet.setPropertyX(String, java.lang.Object, int, int, boolean), IXmlPropertySet.deleteProperty(String)

transformImages

void transformImages(String path,
                     Object[] fileNames)
                     throws IOException,
                            AutomationException
Transforms encoded thumbnail and image enclosures to files and links them into the metadata.

Remarks

Do NOT save metadata after applying the TransformImage method, otherwise the img tags will be saved and the enclosures themselves will be lost. To further explore this, open the metadata file in a Browser that supports XML, an XML editor, or text editor. At the same time look at the file in ArcCatalog with the XML stylesheet. Search for the element Binary, then notice the differences in the documents as they appear in ArcCatalog.

Thumbnails and image enclosures are not stored in the Binary/Thumbnail/Data and Binary/Enclosure/Data elements respectively. TransformImage is used to decode Thumbnails and images and save them to files, then replace the original elements with HTML <img> tags that contain links to those files. For example, ArcCatalog applies this method to the metadata each time it is opened, this lets you see Thumbnails and Image Enclosures in ArcCatalog.

Path names are created using the supplied string, Path. In the example below, Path is set to "c:\temp\", while the file name is "expImg" (an incremental number is added to the file name for each transformation; expImg0, expImg1, expImg2, etc). The appropriate file extension is added. If no Path is supplied, images are written to temp directory location determined by user environment variables.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
path - The path (in)
fileNames - A Variant (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

initExisting

void initExisting()
                  throws IOException,
                         AutomationException
Initializes an XmlPropertySet and adds the Esri group of elements.

Remarks

The InitExisting method can be used to add ESRI elements MetaID, CreaDate, CreaTime, and SyncOnce to existing non-ESRI metadata and XML documents. XML documents created outside ArcCatalog won't ever have these elements, unless you call the InitExisting method.

Upon synchronization, SyncOnce is replaced with SyncDate and SyncTime. Automatic updates and other editing operations in the user interface, or programmatic updates through the IXmlPropertySetEdit::SetProperty, will add ModDate and ModTime.

Anytime ArcGIS creates metadata, automatic or not, theses ESRI elements will be added.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet