com.esri.arcgis.geodatabase
Class XmlPropertySet

java.lang.Object
  extended by com.esri.arcgis.geodatabase.XmlPropertySet
All Implemented Interfaces:
IPersistStreamInit, IXmlPropertySet, IXmlPropertySet2, com.esri.arcgis.interop.RemoteObjRef, IClone, IPersist, IPropertySet, ISupportErrorInfo, IXMLSerialize, Serializable

public class XmlPropertySet
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IPersistStreamInit, IPropertySet, IXmlPropertySet, IXmlPropertySet2, ISupportErrorInfo, IClone, IXMLSerialize

ESRI XML PropertySet object.

Remarks

Creating a new XmlPropertySet

When a new XmlPropertySet is created, it contains no XML header or document elements (the exception to this is in VB6 and VBA, see below). Attempting to use a newly-created XmlPropertySet in almost any way will raise an error until the header and root element are added. There are three ways to do this:

Using the IPropertySet interface on an XmlPropertySet

Accessing an instance of the XmlPropertySet class through the IPropertySet interface varies slightly from the interface's typical use. In a typical property set, there is a 1:1 relationship between properties and values, but because metadata can contain multiple occurrences of a property, the relationship between properties and values in an XmlPropertySet is 1:N. This has an effect on the types of objects returned through the outbound parameters of methods such as GetProperty and GetProperties. The following paragraphs describe the differences in the behavior of each member between a typical property set and an XmlPropertySet containing metadata.

One note that applies to all "getter" methods on this interface is that binary enclosures of type Picture will not be returned as text values, but as IPicture references. Binary enclosures of type Image or Base64 will be extracted to the current user's temporary directory, and a path to the temporary file will be the property's value.

Count: In a typical property set, this returns the total number of properties. When called on an XmlPropertySet, it returns the number of top-level elements. In a metadata document, this will always be one, the Metadata element.

GetAllProperties: An XmlPropertySet's implementation of this method behaves similar to that of a regular property set. Each leaf node is returned as an element in the returned arrays, with the array of names containing the semi-qualified name of each property ("/Metadata" is omitted).

GetProperties: In a typical property set, an array containing strings is provided to this method, and the variant passed to the values parameter is populated with the corresponding values, as strings. Due to the 1:N relationship between properties and values in an XmlPropertySet, however, the values variant does not return an array of strings, but rather a jagged two-dimensional array (an array of arrays) that contain strings. For example, if an array containing a single string, "idinfo/keywords/theme/themekey", was passed to this method, the outbound values parameter would contain an array with a single element, an array of strings. That array would (for many datasets) contain several strings. See this coclass' associated code for a concrete example of this.

Although the names parameter of this method accepts a variant, it must actually be an array of strings (not a variant containing strings), or an error will occur.

This method accepts XSL patterns as valid input strings. If a provided XSL pattern matches multiple properties, the values of these properties will all be returned within a single array in the outbound values parameter. For example, passing an array with the string "*" into the names parameter would return an array with a single "inner" array, with the inner array would contain all top-level elements. See this coclass' associated code for a concrete example of this.

GetProperty: As with GetProperties, the 1:N relationship between properties and values has an effect on the outbound variant parameter of this method. Rather than returning a string, as is the case with typical property sets, an array of strings is returned (one string for each matching property). Also similar to GetProperties, an XSL pattern can be provided as name parameter, with all of the matching properties' values being returned in the values array.

IsEqual: Normally used to compare property sets, this method will always return false when called on an XmlPropertySet, regardless of whether or not the property sets being compared are equal.

RemoveProperty: This method accepts XSL patterns as valid input, meaning that multiple properties can be deleted with a single call. If deleting a single instance of a property (where there are multiple occurrences) is intended, a value or attribute filter can be applied to the property's name, or an indexer may be used. If the specified property is a node containing other properties, all of the sub-nodes will also be removed.

SetProperties: This method accepts a string array (containing property names or XSL patterns) and a variant containing strings, which are the values the properties (or all properties matching the provided pattern) should be set to. Unlike GetProperties, which retrieves a jagged two-dimensional array of strings as its values parameter, this method must be given a simple array of strings, and any specified properties or patterns with multiple occurrences are assigned the same value.

SetProperty: Calling this method on an XmlPropertySet is equivalent to calling IXmlPropertySet.SetPropertyX, with the propType parameter set to esriXPTText, the action parameter set to esriXSPAAddOrReplace, and the syncing parameter set to False. For more information, see the IXmlPropertySet.SetPropertyX documentation.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:
Serialized Form

Constructor Summary
XmlPropertySet()
          Constructs a XmlPropertySet using ArcGIS Engine.
XmlPropertySet(Object obj)
          Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
XmlPropertySet theXmlPropertySet = (XmlPropertySet) obj;
 
Method Summary
 void assign(IClone src)
          Assigns the properties of src to the receiver.
 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.
 void deletePropertyByNameAndAttribute(String name, String attribute, String value, boolean deleteParent)
          Deletes the specified elements which have the specified attribute value.
 void deserialize(IXMLSerializeData data)
          Deserializes an object from XML.
 boolean equals(Object o)
          Compare this object with another
 IClone esri_clone()
          Clones the receiver and assigns the result to *clone.
 void getAllProperties(Object[] names, Object[] values)
          The name and value of all the properties in the property set.
 void getAttribute(String name, String attribute, Object[] value)
          Returns the set of values for the specified attribute from the specified elements.
 void getClassID(GUID[] pClassID)
          getClassID
static String getClsid()
          getClsid.
 int getCount()
          The number of properties contained in the property set.
 int getCountX(String name)
          Number of occurrances of an element in the metadata.
 void getProperties(Object names, Object[] values)
          The values of the specified properties.
 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.
 Object getProperty(String name)
          The value of the specified property.
 void getSizeMax(_ULARGE_INTEGER[] pCbSize)
          getSizeMax
 String getXml(String name)
          Returns the XML corresponding to the specified element as a string.
 int hashCode()
          the hashcode for this object
 void initExisting()
          Initializes an XmlPropertySet and adds the Esri group of elements.
 void initGeneric(String rootName)
          Initializes an XmlPropertySet without adding the Esri group of elements.
 void initNew()
          initNew
 void interfaceSupportsErrorInfo(GUID riid)
          interfaceSupportsErrorInfo
 void isDirty()
          isDirty
 boolean isEqual(IClone other)
          Indicates if the receiver and other have the same properties.
 boolean isEqual(IPropertySet propertySet)
          True if the property set is the same as the input property set.
 boolean isIdentical(IClone other)
          Indicates if the receiver and other are the same object.
 boolean isNew()
          Indicates if a new XmlPropertySet was created on retrieving the metadata.
 boolean isOverwriteSyncAttribute()
          Indicates if the Sync attribute will be ignored when setting an element's value.
 void load(IStream pStm)
          load
 void removeProperty(String name)
          Removes a property from the set.
 void save(IStream pStm, int fClearDirty)
          save
 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 serialize(IXMLSerializeData data)
          Serializes an object to XML.
 void setAttribute(String name, String attribute, Object value, int action)
          Sets the attribute of the specified element.
 void setOverwriteSyncAttribute(boolean overwriteSyncAttributes)
          Indicates if the Sync attribute will be ignored when setting an element's value.
 void setProperties(Object names, Object values)
          The values of the specified properties.
 void setProperty(String name, Object value)
          The value of the specified property.
 void setPropertyX(String name, Object value, int propType, int action, boolean syncing)
          Sets the value of the specified element.
 void setXml(String xml)
          Replaces existing metadata with the content defined in the XML.
 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.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef
getJintegraDispatch, release
 

Constructor Detail

XmlPropertySet

public XmlPropertySet()
               throws IOException,
                      UnknownHostException
Constructs a XmlPropertySet using ArcGIS Engine.

Throws:
IOException - if there are interop problems
UnknownHostException - if there are interop problems

XmlPropertySet

public XmlPropertySet(Object obj)
               throws IOException
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
XmlPropertySet theXmlPropertySet = (XmlPropertySet) obj;

Construct a XmlPropertySet using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to XmlPropertySet.

Parameters:
obj - an object returned from ArcGIS Engine or Server
Throws:
IOException - if there are interop problems
Method Detail

getClsid

public static String getClsid()
getClsid.


equals

public boolean equals(Object o)
Compare this object with another

Overrides:
equals in class Object

hashCode

public int hashCode()
the hashcode for this object

Overrides:
hashCode in class Object

isDirty

public void isDirty()
             throws IOException,
                    AutomationException
isDirty

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isDirty in interface IPersistStreamInit
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

load

public void load(IStream pStm)
          throws IOException,
                 AutomationException
load

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
load in interface IPersistStreamInit
Parameters:
pStm - A reference to a com.esri.arcgis.system.IStream (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

save

public void save(IStream pStm,
                 int fClearDirty)
          throws IOException,
                 AutomationException
save

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
save in interface IPersistStreamInit
Parameters:
pStm - A reference to a com.esri.arcgis.system.IStream (in)
fClearDirty - The fClearDirty (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getSizeMax

public void getSizeMax(_ULARGE_INTEGER[] pCbSize)
                throws IOException,
                       AutomationException
getSizeMax

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getSizeMax in interface IPersistStreamInit
Parameters:
pCbSize - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

initNew

public void initNew()
             throws IOException,
                    AutomationException
initNew

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
initNew in interface IPersistStreamInit
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getClassID

public void getClassID(GUID[] pClassID)
                throws IOException,
                       AutomationException
getClassID

Description

IPersist is a Microsoft interface. Please refer to MSDN for information about this interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getClassID in interface IPersist
Parameters:
pClassID - A Structure: com.esri.arcgis.support.ms.stdole.GUID (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

getCount

public int getCount()
             throws IOException,
                    AutomationException
The number of properties contained in the property set.

Remarks

The Count value will always be one when used with the esriGeodatabase.XmlPropertySet coclass. For more information, see the remarks for the XmlPropertySet coclass.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getCount in interface IPropertySet
Returns:
The count
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.system.IXmlPropertySet, com.esri.arcgis.system.IXmlPropertySet2

getProperty

public Object getProperty(String name)
                   throws IOException,
                          AutomationException
The value of the specified property.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getProperty in interface IPropertySet
Parameters:
name - The name (in)
Returns:
A Variant
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPropertySet.getProperties(java.lang.Object, Object[]), IPropertySet.getAllProperties(Object[], Object[])

getProperties

public void getProperties(Object names,
                          Object[] values)
                   throws IOException,
                          AutomationException
The values of the specified properties.

Remarks

The GetProperties method returns values from a PropertySet CoClass.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getProperties in interface IPropertySet
Parameters:
names - A Variant (in)
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:
IPropertySet.getAllProperties(Object[], Object[]), IPropertySet.getProperty(String)

getAllProperties

public void getAllProperties(Object[] names,
                             Object[] values)
                      throws IOException,
                             AutomationException
The name and value of all the properties in the property set.

Remarks

The GetAllProperties retrieves all names and values in the property set.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getAllProperties in interface IPropertySet
Parameters:
names - 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:
IPropertySet.getProperties(java.lang.Object, Object[]), IPropertySet.getProperty(String)

setProperty

public void setProperty(String name,
                        Object value)
                 throws IOException,
                        AutomationException
The value of the specified property.

Remarks

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setProperty in interface IPropertySet
Parameters:
name - The name (in)
value - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.system.IXmlPropertySet, com.esri.arcgis.system.IXmlPropertySet2, IPropertySet.setProperties(java.lang.Object, java.lang.Object)

setProperties

public void setProperties(Object names,
                          Object values)
                   throws IOException,
                          AutomationException
The values of the specified properties.

Remarks

Using the Name parameter to locate the specified element, the SetProperties method populates the elements, or adds an new element if it already exists, and sets the value to the coorseponding Values parameter.

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

esriXmlSetPropertyAction constants are NOT available to handle situations where an element value already exists. Upon encountering elements that already have values, the new values will replace or add values to existing elements. For more control dealing with elements the IXmlPropertySet::SetPropertyX should be used.

In order to populated nodes further along in the Xml tree, nodes necessary to navigate must first be established. For instance in order to populate the "idinfo/ptcontact/cntinfo/cntperp/cntorg" node each subsequent nodes, "idinfo", "idinfo/ptcontact", "idinfo/ptcontact/cntinfo" and "idinfo/ptcontact/cntinfo/cntperp" must already be in place.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setProperties in interface IPropertySet
Parameters:
names - A Variant (in)
values - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IPropertySet.setProperty(String, java.lang.Object), com.esri.arcgis.system.IXmlPropertySet,

This method is not interop compliant and hence unsupported in Java. Use setProperty() instead.


isEqual

public boolean isEqual(IPropertySet propertySet)
                throws IOException,
                       AutomationException
True if the property set is the same as the input property set.

Remarks

This method indicates whether two property sets are equal.

Note that it will always return false if the property set is an esriGeodatabase.XmlPropertySet (for metadata). See the XmlPropertySet coclass' documentation for more information.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isEqual in interface IPropertySet
Parameters:
propertySet - A reference to a com.esri.arcgis.system.IPropertySet (in)
Returns:
The isEqual
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

removeProperty

public void removeProperty(String name)
                    throws IOException,
                           AutomationException
Removes a property from the set.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
removeProperty in interface IPropertySet
Parameters:
name - The name (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
com.esri.arcgis.system.IXmlPropertySet

getCountX

public 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.

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

getPropertiesByAttribute

public 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

Specified by:
getPropertiesByAttribute in interface IXmlPropertySet
Specified by:
getPropertiesByAttribute in interface IXmlPropertySet2
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

public 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

Specified by:
setPropertyX in interface IXmlPropertySet
Specified by:
setPropertyX in interface IXmlPropertySet2
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

public 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

Specified by:
deleteProperty in interface IXmlPropertySet
Specified by:
deleteProperty in interface IXmlPropertySet2
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

public 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

Specified by:
deletePropertyByAttribute in interface IXmlPropertySet
Specified by:
deletePropertyByAttribute in interface IXmlPropertySet2
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

public 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

Specified by:
simpleGetProperty in interface IXmlPropertySet
Specified by:
simpleGetProperty in interface IXmlPropertySet2
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

public 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

Specified by:
saveAsFile in interface IXmlPropertySet
Specified by:
saveAsFile in interface IXmlPropertySet2
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

public 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

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

setAttribute

public 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

Specified by:
setAttribute in interface IXmlPropertySet
Specified by:
setAttribute in interface IXmlPropertySet2
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

public 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

Specified by:
transformImages in interface IXmlPropertySet
Specified by:
transformImages in interface IXmlPropertySet2
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

public 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

Specified by:
initExisting in interface IXmlPropertySet
Specified by:
initExisting in interface IXmlPropertySet2
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet

initGeneric

public void initGeneric(String rootName)
                 throws IOException,
                        AutomationException
Initializes an XmlPropertySet without adding the Esri group of elements.

Remarks

The InitGeneric method initializes an XmlPropertySet without adding the ESRI group of elements.

This method is available to the XmlProperty CoClass through the IXmlPropertySet2 Interface.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
initGeneric in interface IXmlPropertySet2
Parameters:
rootName - The rootName (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet2.initExisting()

getXml

public String getXml(String name)
              throws IOException,
                     AutomationException
Returns the XML corresponding to the specified element as a string.

Remarks

The GetXml method returns both the metadata element tag (including attributes/values pairs) and the corresponding value as string.

Specifying an XML element with children nodes will return all children elements and values also.

Because the return variable is of type string, specifying enclosures, images or pictures return the data encoded as Base64 inside of XML tags (unless TransformImages has been called).

If repeating elements are specified, i.e. "idinfo/keywords/theme/themekey", nothing will be returned. More detailed criteria are necessary when specifying the Name parameter. This can be achieved with an XPath query. More information on XPath can be found at the IXmlPropertySet documentation and through documentation below.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getXml in interface IXmlPropertySet2
Parameters:
name - The name (in)
Returns:
The xml
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet2.saveAsFile(String, String, boolean, String[]), IXmlPropertySet2.setXml(String)

setXml

public void setXml(String xml)
            throws IOException,
                   AutomationException
Replaces existing metadata with the content defined in the XML.

Remarks

The SetXML method replaces the entire metadata document with the Xml string supplied in the XML parameter.

To target specific XML elements, the SetPropertyX method should be used.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setXml in interface IXmlPropertySet2
Parameters:
xml - The xml (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet2.getXml(String)

deletePropertyByNameAndAttribute

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

Remarks

The DeletePropertyByNameAndAttribute method provides additional parameters to delete XML elements and their corresponding values from metadata documents. Similar actions can be accomplished through other methods (DeleteProperty, DeletePropertyByAttribute) and XPath strings. For instance the following lines of pseudocode accomplish the same action;

xmlPropertySet.DeletePropertyByNameAndAttribute("idinfo/keywords/theme/themekey", "new", "yes", False)
xmlPropertySet.DeleteProperty("idinfo/keywords/theme/themekey[@new='yes']")

The Name parameter uses XPath to describe the location and condition of XML nodes in metadata. More information on XPath can be found at the IXmlPropertySet documentation.

If children elements of the specified Name parameter exist, the DeletePropertyByNameAndAttribute method will also remove them from the XML Document.

The Attribute parameter must contain a valid string character. Otherwise the DeleteProperty method should be used for deleting elements without having to specify attributes.

By setting the attribute Value parameter to "", all elements that match the Name and Attribute parameter will be deleted. The DeletePropertyByAttribute method should be used to delete elements without specifying attribute values.

The deleteParent parameter is a Boolean expression that indicates if the parent element of the Name parameter should be deleted. Special attention should be made to this parameter when deleting a Thumbnail or Binary Enclosure. The parent of the Thumbnail element is the Enclosure element, which also happens to be a parent element of the Data element that holds the Binary information. If deleteParent is set to true when specifying the Data or Thumbnail tag, all Enclosures information will be removed.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
deletePropertyByNameAndAttribute in interface IXmlPropertySet2
Parameters:
name - The name (in)
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:
IXmlPropertySet2.deleteProperty(String), IXmlPropertySet2.deletePropertyByAttribute(String, String, boolean)

getAttribute

public void getAttribute(String name,
                         String attribute,
                         Object[] value)
                  throws IOException,
                         AutomationException
Returns the set of values for the specified attribute from the specified elements.

Description

The Name parameter determines the location of the XML element.

Because XML elements may contain multiple attributes/value pairs, the Attribute parameter is used to specify the attribute.

The Value argument is returned containing the attribute values.

Remarks

The GetAttribute method returns the attribute value of the specified metadata element.

The Name parameter uses XPath to describe the location and condition of XML nodes in metadata. More information on XPath can be found at the IXmlPropertySet documentation.

The Attribute must contain a valid string. If no string is declared (""), a run time error will occur.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
getAttribute in interface IXmlPropertySet2
Parameters:
name - The name (in)
attribute - The attribute (in)
value - A Variant (out: use single element array)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:

The Values parameter must be a Object to hold multiple values.


setOverwriteSyncAttribute

public void setOverwriteSyncAttribute(boolean overwriteSyncAttributes)
                               throws IOException,
                                      AutomationException
Indicates if the Sync attribute will be ignored when setting an element's value.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
setOverwriteSyncAttribute in interface IXmlPropertySet2
Parameters:
overwriteSyncAttributes - The overwriteSyncAttributes (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet2.setPropertyX(String, java.lang.Object, int, int, boolean), IXmlPropertySet2

isOverwriteSyncAttribute

public boolean isOverwriteSyncAttribute()
                                 throws IOException,
                                        AutomationException
Indicates if the Sync attribute will be ignored when setting an element's value.

Remarks

By default the OverwriteSyncAttribute property is set to false. If the property is changed it remains true for the time the object is held in memory. Once the object is released, the OverwriteSyncAttribute is set back to false.

The OverwriteSyncAttribute property is set for an entire property set and not individual properties.

When the property is set to true, the syncing parameter used and the SetPropertyX methods is ignored. The SetPropertyX action, determined by the esriXmlSetPropertyAction, is then carried out. Otherwise if the OverwriteSyncAttribute property remains false, the esriXmlSetPropertyAction and value of the syncing parameter in the SetPropertyX determine the action.

A complete understanding of the syncing parameter is recommended when setting and getting the OverwriteSyncAttribute property. See the documentation for IXmlPropertySet.SetPropertyX for more information.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isOverwriteSyncAttribute in interface IXmlPropertySet2
Returns:
The overwriteSyncAttributes
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.
See Also:
IXmlPropertySet2.setPropertyX(String, java.lang.Object, int, int, boolean), IXmlPropertySet2

interfaceSupportsErrorInfo

public void interfaceSupportsErrorInfo(GUID riid)
                                throws IOException,
                                       AutomationException
interfaceSupportsErrorInfo

Description

Indicates whether the interface supports IErrorInfo.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
interfaceSupportsErrorInfo in interface ISupportErrorInfo
Parameters:
riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

esri_clone

public IClone esri_clone()
                  throws IOException,
                         AutomationException
Clones the receiver and assigns the result to *clone.

Product Availability

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

Specified by:
esri_clone in interface IClone
Returns:
A reference to a com.esri.arcgis.system.IClone
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

assign

public void assign(IClone src)
            throws IOException,
                   AutomationException
Assigns the properties of src to the receiver.

Description

Use Assign method to assign the properties of source object to receiver object. Both objects need to have the same CLSIDs. Both source and receiver objects need to be instantiated.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
assign in interface IClone
Parameters:
src - A reference to a com.esri.arcgis.system.IClone (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isEqual

public boolean isEqual(IClone other)
                throws IOException,
                       AutomationException
Indicates if the receiver and other have the same properties.

Description

IsEqual returns True if the receiver and the source have the same properties. Note, this does not imply that the receiver and the source reference the same object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isEqual in interface IClone
Parameters:
other - A reference to a com.esri.arcgis.system.IClone (in)
Returns:
The equal
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

isIdentical

public boolean isIdentical(IClone other)
                    throws IOException,
                           AutomationException
Indicates if the receiver and other are the same object.

Description

IsIdentical returns true if the receiver and the source reference the same object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
isIdentical in interface IClone
Parameters:
other - A reference to a com.esri.arcgis.system.IClone (in)
Returns:
The identical
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

serialize

public void serialize(IXMLSerializeData data)
               throws IOException,
                      AutomationException
Serializes an object to XML.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
serialize in interface IXMLSerialize
Parameters:
data - A reference to a com.esri.arcgis.system.IXMLSerializeData (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

deserialize

public void deserialize(IXMLSerializeData data)
                 throws IOException,
                        AutomationException
Deserializes an object from XML.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:
deserialize in interface IXMLSerialize
Parameters:
data - A reference to a com.esri.arcgis.system.IXMLSerializeData (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.