org.opengis.cite.kml2.util

Class KMLUtils

java.lang.Object

org.opengis.cite.kml2.util.KMLUtils

public class KMLUtils
extends Object

Provides various utility methods for reading or manipulating KML and KMZ resources.

Constructor Summary

Constructors

Constructor and Description
KMLUtils()

Method Summary

Modifier and Type	Method and Description
static Set<String>	findElementIdentifiers(Source kmlSource, String xpath) Finds KML elements selected by the given XPath expression and returns their identifiers.
static AltitudeMode	getAltitudeMode(Element element) Gets the altitude mode for the given KML element.
static Map<String,net.sf.saxon.s9api.ItemType>	getDeclaredFields(net.sf.saxon.s9api.XdmNode schema) Gets information about the fields declared in a custom schema.
static Document	parseKMLDocument(File file) Parses the content of the given file as a KML resource and returns the resulting DOM document node.
static Document	parseKMLDocumentInArchive(File file) Reads the given KMZ archive file and parses the first root-level KML document found within it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KMLUtils

public KMLUtils()

Method Detail

parseKMLDocument

public static Document parseKMLDocument(File file)
                                 throws IOException,
                                        SAXException

Parses the content of the given file as a KML resource and returns the resulting DOM document node.

Parameters:

file - A file containing a KML resource (KML or KMZ).

Returns:

A Document object representing a KML document (the root element is kml:kml), or null if one cannot be found.

Throws:

IOException - If the file cannot be read for some reason (e.g. it doesn't exist).

SAXException - If the file does not contain well-formed XML.

parseKMLDocumentInArchive

public static Document parseKMLDocumentInArchive(File file)
                                          throws IOException,
                                                 SAXException

Reads the given KMZ archive file and parses the first root-level KML document found within it. The main KML document is conventionally named doc.kml but this is not required; the .kml extension is expected, however.

Parameters:

file - A File object that presumably represents a KMZ file (ZIP archive).

Returns:

A KML document, or null if a root-level KML file could not be found in the archive.

Throws:

IOException - The file is not a valid ZIP archive or some other I/O error occurred.

SAXException - If a KML document was found but it is not well-formed.

See Also:

"OGC 12-007r1, Annex C: KMZ Files (Normative)", What is a KMZ File?

findElementIdentifiers

public static Set<String> findElementIdentifiers(Source kmlSource,
                                                 String xpath)

Finds KML elements selected by the given XPath expression and returns their identifiers. This method can be used to find custom schemas and shared styles that occur in a KML document and may be referenced by identifier.

A shared style is any element that may substitute for kml:AbstractStyleSelectorGroup (kml:Style, kml:StyleMap) that satisfies all of the following conditions:

1. its parent element is kml:Document
2. it has a non-empty 'id' attribute value

A custom schema (kml:Schema) may be defined in order to add user-defined data that occurs within a child kml:ExtendedData element of a KML feature.

Parameters:

kmlSource - A Source for reading a KML document.

xpath - An XPath (2.0) expression that selects the KML objects of interest.

Returns:

A set (possibly empty) of identifiers for shared resources defined in the source.

See Also:

"OGC KML 2.3, 6.4: Shared Styles", "OGC KML 2.3, 9.10: Schema"

getAltitudeMode

public static AltitudeMode getAltitudeMode(Element element)

Gets the altitude mode for the given KML element. The schema component kml:AltitudeModeGroup includes the elements kml:altitudeMode and kml:seaFloorAltitudeMode, for which the following values are declared:

• clampToGround (default)
• relativeToGround
• absolute
• clampToSeaFloor
• relativeToSeaFloor

Parameters:

element - A KML element.

Returns:

The AltitudeMode that applies this element, or the default if not explicitly set.

getDeclaredFields

public static Map<String,net.sf.saxon.s9api.ItemType> getDeclaredFields(net.sf.saxon.s9api.XdmNode schema)

Gets information about the fields declared in a custom schema.

Parameters:

schema - A node representing a kml:Schema element.

Returns:

A Map containing the names (keys) and data types of the fields (kml:SimpleField, kml:SimpleArrayField) declared in the schema.