IXmlPropertySet (ArcObjects Java API)

This interface uses XPath, a way to select a node or groups of nodes that match a selection criteria, as parameters in several methods and properties (CountX property, DeleteProperty method, SetAttribute method, SetPropertyX method, and SimpleGetProperty method). XPath provides a simple query language for identifying nodes in an XML document based on attribute, name, and values.

An important point when using XPath 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 XPath include:

node: Finds all node elements.
parent/child: Finds all child elements within parent elements.
parent\/*: Finds all elements within parent elements.
parent[child = "val1"]: Finds all parent elements with a child element that has a value of "val1".
node[@Sync]: Finds all node elements with a Sync attribute.
node[@Sync = "TRUE"]: Finds all node elements with a Sync attribute that has a value of "TRUE".
node[@Sync != "TRUE"]: Finds all node elements with a Sync attribute that has a value other than "TRUE".
desc[. = "myDesc"]: Finds all desc elements that have a value of "myDesc".
attr[5]: Finds the 6th attr element (the indexer is zero-based).

For more examples of XPath, see the MSDN article, XPath Examples.

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. See the XmlPropertySet coclass documentation for more information.

Product Availability

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

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 XPath to specify metadata elements. The method then adds or replaces the element value.

Remarks

The Name parameter uses XPath to specify metadata elements. Additional information on XPath 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 XPath to describe the location and condition of XML nodes in metadata. XPath includes a set of expressions, allowing for more defined queries and filters. More information on XPath 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, calling this method on XML similar to that shown below with the parameters "approved", "no", and true would not only delete the "idinfo/timeperd/timeinfo/sngdate/caldate" element, but would also delete 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 XPath to locate and process items in XML documents. More information on XPath 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).

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 XPath pattern. For instance "idinfo/keywords/theme/themekey" locates all theme keywords. For more information on XPath, 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

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.esri.arcgis.geodatabase Interface IXmlPropertySet

Superseded By

Remarks

Product Availability

getCountX

Product Availability

getPropertiesByAttribute

Description

Remarks

Product Availability

Supported Platforms

setPropertyX

Description

Remarks

Product Availability

Supported Platforms

deleteProperty

Description

Remarks

Product Availability

Supported Platforms

deletePropertyByAttribute

Description

Product Availability

Supported Platforms

simpleGetProperty

Remarks

Product Availability

Supported Platforms

saveAsFile

Remarks

Product Availability

Supported Platforms

isNew

Remarks

Product Availability

Supported Platforms

setAttribute

Remarks

Product Availability

Supported Platforms

transformImages

Remarks

Product Availability

Supported Platforms

initExisting

Remarks

Product Availability

Supported Platforms

com.esri.arcgis.geodatabase
Interface IXmlPropertySet