gov.nasa.worldwind.ogc.kml
Class KMLRoot

java.lang.Object
  gov.nasa.worldwind.util.xml.AbstractXMLEventParser
      gov.nasa.worldwind.ogc.kml.KMLAbstractObject
          gov.nasa.worldwind.ogc.kml.KMLRoot

All Implemented Interfaces:

MessageListener, KMLRenderable, XMLEventParser

public class KMLRoot
extends KMLAbstractObject
implements KMLRenderable

Parses a KML or KMZ document and provides access to its contents. Instructions for parsing KML/KMZ files and streams are given in the Description section of gov.nasa.worldwind.ogc.kml.

Field Summary

protected AbsentResourceList	absentResourceList
protected double	detailHint Indicates this KML root's detail hint.
protected XMLEventReader	eventReader The event reader used to parse the document's XML.
protected InputStream	eventStream The input stream underlying the event reader.
protected KMLAbstractFeature	feature
protected boolean	featureFetched Flag to indicate that the feature has been fetched from the hash map.
protected KMLDoc	kmlDoc Reference to the KMLDoc representing the KML or KMZ file.
protected boolean	linkControlFetched Flag to indicate that the network link control element has been fetched from the hash map.
protected KMLNetworkLinkControl	networkLinkControl
protected KMLParserContext	parserContext The parser context for the document.
protected PropertyChangeSupport	propertyChangeSupport The PropertyChangeSupport that receives property change events this KMLRoot listens for, and sends property change events to this KMLRoot's listeners.

Fields inherited from class gov.nasa.worldwind.ogc.kml.KMLAbstractObject

MSG_BOX_CHANGED, MSG_GEOMETRY_CHANGED, MSG_LINK_CHANGED, MSG_STYLE_CHANGED, MSG_TIME_CHANGED, MSG_VIEW_CHANGED

Fields inherited from class gov.nasa.worldwind.util.xml.AbstractXMLEventParser

CHARACTERS_CONTENT, fields, namespaceURI, parent

Constructor Summary

KMLRoot(File docSource)
Create a new KMLRoot for a File.

KMLRoot(File docSource, boolean namespaceAware)
Create a new KMLRoot for a File.

KMLRoot(InputStream docSource, String contentType)
Create a new KMLRoot for an InputStream.

KMLRoot(InputStream docSource, String contentType, boolean namespaceAware)
Create a new KMLRoot for an InputStream.

KMLRoot(KMLDoc docSource)
Create a new KMLRoot for a KMLDoc instance.

KMLRoot(KMLDoc docSource, boolean namespaceAware)
Create a new KMLRoot for a KMLDoc instance.

KMLRoot(String namespaceURI, KMLDoc docSource)
Create a new KMLRoot with a specific namespace.

KMLRoot(String namespaceURI, KMLDoc docSource, boolean namespaceAware)
Create a new KMLRoot with a specific namespace.

KMLRoot(URL docSource, String contentType)
Create a KMLRoot for a URL.

KMLRoot(URL docSource, String contentType, boolean namespaceAware)
Create a KMLRoot for a URL.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener listener) Adds the specified property change listener that will be called for all list changes.
protected boolean	canParseContentType(String mimeType) Determines if a MIME type can be parsed as KML or KMZ.
protected void	closeEventStream() Closes the event stream associated with this context's XML event reader.
static KMLRoot	create(Object docSource) Creates a KML root for an untyped source.
static KMLRoot	create(Object docSource, boolean namespaceAware) Creates a KML root for an untyped source.
static KMLRoot	createAndParse(Object docSource) Creates a KML root for an untyped source and parses it.
protected KMLParserContext	createParserContext(XMLEventReader reader) Invoked during initialize(boolean) to create the parser context.
protected XMLEventReader	createReader(Object docSource, boolean namespaceAware) Creates the event reader.
void	evictIfExpired(String link, long expirationTime) Check a cached resource for expiration.
protected KMLAbstractFeature	findFeature() Searches this root's fields for the KML Feature element.
void	firePropertyChange(PropertyChangeEvent propertyChangeEvent) Fire a property change event.
void	firePropertyChange(String propertyName, Object oldValue, Object newValue) Fire a property change event.
protected PropertyChangeSupport	getChangeSupport() Get the PropertyChangeSupport object for this KML object.
double	getDetailHint() Indicates this KML root's detail hint, which is described in setDetailHint(double).
long	getExpiration(String link) Returns the expiration time of a file retrieved by resolveReference or resolveNetworkLink.
KMLAbstractFeature	getFeature() Returns the KML Feature element contained in the document root.
String	getHint() Returns the hint attribute of the KML element (the document root).
Object	getItemByID(String id) Finds a named element in the document.
KMLDoc	getKMLDoc() Returns the KML document for this KMLRoot.
KMLNetworkLinkControl	getNetworkLinkControl() Returns the KMLNetworkLinkControl element if the document root contains it.
protected XMLEventParserContext	getParserContext()
String	getSupportFilePath(String link)
protected void	initialize(boolean namespaceAware) Called just before the constructor returns.
void	onMessage(Message msg) Invoked when a message is received.
KMLRoot	parse(Object... args) Starts document parsing.
protected KMLRoot	parseCachedKMLFile(URL url, String linkBase, String contentType, boolean namespaceAware) Open and parse the specified file expressed as a file: URL..
void	preRender(KMLTraversalContext tc, DrawContext dc) Pre-render this element.
void	removePropertyChangeListener(PropertyChangeListener listener) Removes the specified property change listener.
void	render(KMLTraversalContext tc, DrawContext dc) Render this element.
void	requestRedraw() Request any scene containing this KML document be repainted.
Object	resolveLocalReference(String linkBase, String linkRef) Resolves a reference to a local element identified by address and identifier, where linkBase identifies a document, including the current document, and linkRef is the id of the desired element.
Object	resolveNetworkLink(String link, boolean cacheRemoteFile, long updateTime) Resolves a NetworkLink to a local or remote KML document.
Object	resolveReference(String link) Resolves a reference to a remote or local element of the form address#identifier, where "address" identifies a local or remote document, including the current document, and and "identifier" is the id of the desired element.
Object	resolveReference(String link, boolean cacheRemoteFile) Resolves a reference to a remote or local element of the form address#identifier, where "address" identifies a local or remote document, including the current document, and and "identifier" is the id of the desired element.
Object	resolveRemoteReference(String linkBase, String linkRef) Resolves a reference to a remote element identified by address and identifier, where linkBase identifies a remote document, and linkRef is the id of the desired element.
Object	resolveRemoteReference(String linkBase, String linkRef, boolean cacheRemoteFile) Resolves a reference to a remote element identified by address and identifier, where linkBase identifies a remote document, and linkRef is the id of the desired element.
void	setDetailHint(double detailHint) Specifies this KML root's detail hint.
void	setNotificationListener(XMLParserNotificationListener listener) Specifies the object to receive notifications of important occurrences during parsing, such as exceptions and the occurrence of unrecognized element types.

Methods inherited from class gov.nasa.worldwind.ogc.kml.KMLAbstractObject

applyChange, getId, getRoot, getTargetId, onChange

Methods inherited from class gov.nasa.worldwind.util.xml.AbstractXMLEventParser

allocate, doAddCharacters, doAddEventAttribute, doAddEventContent, doParseEventAttributes, doParseEventContent, freeResources, getAConstructor, getCharacters, getField, getField, getFields, getNamespaceURI, getParent, hasField, hasField, hasFields, mergeFields, newInstance, overrideFields, parse, parseCharacterContent, removeField, setField, setField, setFields, setParent

Methods inherited from class java.lang.Object

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

Field Detail

absentResourceList

protected AbsentResourceList absentResourceList

detailHint

protected double detailHint

Indicates this KML root's detail hint. Modifies the default relationship of KML scene resolution to screen resolution as viewing distance changes. Values greater than 0 increase the resolution. Values less than 0 decrease the resolution. Initially 0.

eventReader

protected XMLEventReader eventReader

The event reader used to parse the document's XML.

eventStream

protected InputStream eventStream

The input stream underlying the event reader.

feature

protected KMLAbstractFeature feature

featureFetched

protected boolean featureFetched

Flag to indicate that the feature has been fetched from the hash map.

kmlDoc

protected KMLDoc kmlDoc

Reference to the KMLDoc representing the KML or KMZ file.

linkControlFetched

protected boolean linkControlFetched

Flag to indicate that the network link control element has been fetched from the hash map.

networkLinkControl

protected KMLNetworkLinkControl networkLinkControl

parserContext

protected KMLParserContext parserContext

The parser context for the document.

propertyChangeSupport

protected PropertyChangeSupport propertyChangeSupport

The PropertyChangeSupport that receives property change events this KMLRoot listens for, and sends property change events to this KMLRoot's listeners. Lazily initialized in getChangeSupport. Initially null.

Constructor Detail

KMLRoot

public KMLRoot(File docSource)
        throws IOException

Create a new KMLRoot for a File.

Parameters:

docSource - the File containing the document.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the KML document.

KMLRoot

public KMLRoot(File docSource,
               boolean namespaceAware)
        throws IOException

Create a new KMLRoot for a File.

Parameters:

docSource - the File containing the document.

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the KML document.

KMLRoot

public KMLRoot(InputStream docSource,
               String contentType)
        throws IOException

Create a new KMLRoot for an InputStream.

Parameters:

docSource - the input stream containing the document.

contentType - the content type of the stream data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. The content is treated as KML for any other value or a value of null.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the KML document.

KMLRoot

public KMLRoot(InputStream docSource,
               String contentType,
               boolean namespaceAware)
        throws IOException

Create a new KMLRoot for an InputStream.

Parameters:

docSource - the input stream containing the document.

contentType - the content type of the stream data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. The content is treated as KML for any other value or a value of null.

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the KML document.

KMLRoot

public KMLRoot(KMLDoc docSource)
        throws IOException

Create a new KMLRoot for a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.

Parameters:

docSource - the KMLDoc instance representing the KML document.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the KML document.

KMLRoot

public KMLRoot(KMLDoc docSource,
               boolean namespaceAware)
        throws IOException

Create a new KMLRoot for a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.

Parameters:

docSource - the KMLDoc instance representing the KML document.

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the KML document.

KMLRoot

public KMLRoot(String namespaceURI,
               KMLDoc docSource)
        throws IOException

Create a new KMLRoot with a specific namespace. (The default namespace is defined by KMLConstants.KML_NAMESPACE).

Parameters:

namespaceURI - the default namespace URI.

docSource - the KML source specified via a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an I/O error occurs attempting to open the document source.

KMLRoot

public KMLRoot(String namespaceURI,
               KMLDoc docSource,
               boolean namespaceAware)
        throws IOException

Create a new KMLRoot with a specific namespace. (The default namespace is defined by KMLConstants.KML_NAMESPACE).

Parameters:

namespaceURI - the default namespace URI.

docSource - the KML source specified via a KMLDoc instance. A KMLDoc represents KML and KMZ files from either files or input streams.

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an I/O error occurs attempting to open the document source.

KMLRoot

public KMLRoot(URL docSource,
               String contentType)
        throws IOException

Create a KMLRoot for a URL.

Parameters:

docSource - the URL identifying the document.

contentType - the content type of the data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. Any other non-null value causes the content to be treated as plain KML. If null is specified the content type is read from the server or other end point of the URL. When a content type is specified, the content type returned by the URL's end point is ignored. You can therefore force the content to be treated as KML or KMZ regardless of what a server declares it to be.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the document.

KMLRoot

public KMLRoot(URL docSource,
               String contentType,
               boolean namespaceAware)
        throws IOException

Create a KMLRoot for a URL.

Parameters:

docSource - the URL identifying the document.

contentType - the content type of the data. Specify KMLConstants.KML_MIME_TYPE for plain KML and KMLConstants.KMZ_MIME_TYPE for KMZ. Any other non-null value causes the content to be treated as plain KML. If null is specified the content type is read from the server or other end point of the URL. When a content type is specified, the content type returned by the URL's end point is ignored. You can therefore force the content to be treated as KML or KMZ regardless of what a server declares it to be.

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Throws:

IllegalArgumentException - if the document source is null.

IOException - if an error occurs while reading the document.

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds the specified property change listener that will be called for all list changes.

Parameters:

listener - the listener to call.

Throws:

IllegalArgumentException - if listener is null

See Also:

PropertyChangeSupport

canParseContentType

protected boolean canParseContentType(String mimeType)

Determines if a MIME type can be parsed as KML or KMZ. Parsable types are the KML and KMZ MIME types, as well as "text/plain" and "text/xml".

Parameters:

mimeType - Type to test. May be null.

Returns:

true if mimeType can be parsed as KML.

closeEventStream

protected void closeEventStream()

Closes the event stream associated with this context's XML event reader.

create

public static KMLRoot create(Object docSource)
                      throws IOException

Creates a KML root for an untyped source. The source must be either a File, a URL, a InputStream, or a String identifying either a file path or a URL. For all types other than InputStream an attempt is made to determine whether the source is KML or KMZ; KML is assumed if the test is not definitive. Null is returned if the source type is not recognized.

Parameters:

docSource - either a File, a URL, or an InputStream, or a String identifying a file path or URL.

Returns:

a new KMLRoot for the specified source, or null if the source type is not supported.

Throws:

IllegalArgumentException - if the source is null.

IOException - if an error occurs while reading the source.

create

public static KMLRoot create(Object docSource,
                             boolean namespaceAware)
                      throws IOException

Creates a KML root for an untyped source. The source must be either a File, a URL, a InputStream, or a String identifying either a file path or a URL. For all types other than InputStream an attempt is made to determine whether the source is KML or KMZ; KML is assumed if the test is not definitive. Null is returned if the source type is not recognized.

Parameters:

docSource - either a File, a URL, or an InputStream, or a String identifying a file path or URL.

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Returns:

a new KMLRoot for the specified source, or null if the source type is not supported.

Throws:

IllegalArgumentException - if the source is null.

IOException - if an error occurs while reading the source.

createAndParse

public static KMLRoot createAndParse(Object docSource)
                              throws IOException,
                                     XMLStreamException

Creates a KML root for an untyped source and parses it. The source must be either a File, a URL, a InputStream, or a String identifying either a file path or a URL. For all types other than InputStream an attempt is made to determine whether the source is KML or KMZ; KML is assumed if the test is not definitive. Null is returned if the source type is not recognized.

Note: Because there are so many incorrectly formed KML files in distribution, it's often not possible to parse with a namespace aware parser. This method first tries to use a namespace aware parser, but if a severe problem occurs during parsing, it will try again using a namespace unaware parser. Namespace unaware parsing typically bypasses many problems, but it also causes namespace qualified elements in the XML to be unrecognized.

Parameters:

docSource - either a File, a URL, or an InputStream, or a String identifying a file path or URL.

Returns:

a new KMLRoot for the specified source, or null if the source type is not supported.

Throws:

IllegalArgumentException - if the source is null.

IOException - if an error occurs while reading the source.

XMLStreamException - if the KML file has severe errors.

createParserContext

protected KMLParserContext createParserContext(XMLEventReader reader)

Invoked during initialize(boolean) to create the parser context. The parser context is created by the global XMLEventParserContextFactory.

Parameters:

reader - the reader to associate with the parser context.

Returns:

a new parser context.

createReader

protected XMLEventReader createReader(Object docSource,
                                      boolean namespaceAware)

Creates the event reader. Called from the constructor.

Parameters:

docSource - the document source to create a reader for. The type can be any of those supported by WWXML.openEventReader(Object).

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Returns:

a new event reader, or null if the source type cannot be determined.

evictIfExpired

public void evictIfExpired(String link,
                           long expirationTime)

Check a cached resource for expiration. If the resource is expired, evict it from the cache.

Parameters:

link - Link that identifies the resource to check for expiration. This is the same link that was passed to resolveReference to retrieve the resource.

expirationTime - Time at which the resource expires, in milliseconds since the Epoch. If the current system time is greater than the expiration time, then the resource will be evicted.

findFeature

protected KMLAbstractFeature findFeature()

Searches this root's fields for the KML Feature element.

Returns:

the feature element, or null if none was found.

firePropertyChange

public void firePropertyChange(PropertyChangeEvent propertyChangeEvent)

Fire a property change event.

Parameters:

propertyChangeEvent - Event to fire.

firePropertyChange

public void firePropertyChange(String propertyName,
                               Object oldValue,
                               Object newValue)

Fire a property change event.

Parameters:

propertyName - Name of the property change changed.

oldValue - The previous value of the property.

newValue - The new value of the property.

getChangeSupport

protected PropertyChangeSupport getChangeSupport()

Get the PropertyChangeSupport object for this KML object. The support object will be created if it does not already exist.

Returns:

PropertyChangeSupport for this KML object.

getDetailHint

public double getDetailHint()

Indicates this KML root's detail hint, which is described in setDetailHint(double).

Returns:

the detail hint.

See Also:

setDetailHint(double)

getExpiration

public long getExpiration(String link)

Returns the expiration time of a file retrieved by resolveReference or resolveNetworkLink.

Parameters:

link - the address of the file (the same address as was previously passed to resolveReference). If null, zero is returned.

Returns:

The expiration time of the file, in milliseconds since the Epoch (January 1, 1970, 00:00:00 GMT). Zero indicates that there is no expiration time. Returns zero if te resource identified by link has not been retrieved.

getFeature

public KMLAbstractFeature getFeature()

Returns the KML Feature element contained in the document root.

Returns:

the feature element if it is specified in the document, otherwise null.

getHint

public String getHint()

Returns the hint attribute of the KML element (the document root).

Returns:

the hint attribute, or null if the attribute is not specified.

getItemByID

public Object getItemByID(String id)

Finds a named element in the document.

Parameters:

id - the element's identifier. If null, null is returned.

Returns:

the element requested, or null if there is no corresponding element in the document.

getKMLDoc

public KMLDoc getKMLDoc()

Returns the KML document for this KMLRoot.

Returns:

the KML document for this root.

getNetworkLinkControl

public KMLNetworkLinkControl getNetworkLinkControl()

Returns the KMLNetworkLinkControl element if the document root contains it.

Returns:

the element if it is specified in the document, otherwise null.

getParserContext

protected XMLEventParserContext getParserContext()

getSupportFilePath

public String getSupportFilePath(String link)
                          throws IOException

Throws:

IOException

initialize

protected void initialize(boolean namespaceAware)
                   throws IOException

Called just before the constructor returns. If overriding this method be sure to invoke super.initialize(boolean).

Parameters:

namespaceAware - specifies whether to use a namespace-aware XML parser. true if so, false if not.

Throws:

IOException - if an I/O error occurs attempting to open the document source.

onMessage

public void onMessage(Message msg)

Invoked when a message is received.

Overridden to forward the message to the root feature.

Specified by:

onMessage in interface MessageListener

Overrides:

onMessage in class KMLAbstractObject

Parameters:

msg - The message that was received.

parse

public KMLRoot parse(Object... args)
              throws XMLStreamException

Starts document parsing. This method initiates parsing of the KML document and returns when the full document has been parsed.

Parameters:

args - optional arguments to pass to parsers of sub-elements.

Returns:

this if parsing is successful, otherwise null.

Throws:

XMLStreamException - if an exception occurs while attempting to read the event stream.

parseCachedKMLFile

protected KMLRoot parseCachedKMLFile(URL url,
                                     String linkBase,
                                     String contentType,
                                     boolean namespaceAware)
                              throws IOException,
                                     XMLStreamException

Open and parse the specified file expressed as a file: URL..

Parameters:

url - the URL of the file to open, expressed as a URL with a scheme of "file".

linkBase - the original address of the document if the file is a retrieved and cached file.

contentType - the mime type of the file's content, either a KML or KMZ mime type.

namespaceAware - specifies whether to use a namespace aware event reader.

Returns:

A KMLRoot representing the file's KML contents.

Throws:

IOException - if an I/O error occurs during opening and parsing.

XMLStreamException - if a server parsing error is encountered.

preRender

public void preRender(KMLTraversalContext tc,
                      DrawContext dc)

Description copied from interface: KMLRenderable

Pre-render this element.

Specified by:

preRender in interface KMLRenderable

Parameters:

tc - the current KML traversal context.

dc - the current draw context.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes the specified property change listener.

Parameters:

listener - the listener to remove.

Throws:

IllegalArgumentException - if listener is null.

See Also:

PropertyChangeSupport

render

public void render(KMLTraversalContext tc,
                   DrawContext dc)

Description copied from interface: KMLRenderable

Render this element.

Specified by:

render in interface KMLRenderable

Parameters:

tc - the current KML traversal context.

dc - the current draw context.

requestRedraw

public void requestRedraw()

Request any scene containing this KML document be repainted.

resolveLocalReference

public Object resolveLocalReference(String linkBase,
                                    String linkRef)

Resolves a reference to a local element identified by address and identifier, where linkBase identifies a document, including the current document, and linkRef is the id of the desired element.

If linkBase refers to a local KML or KMZ file and linkRef is non-null, the return value is the element identified by linkRef. If linkRef is null, the return value is a parsed KMLRoot for the KML file identified by linkBase.

If linkBase refers a local file that is not a KML or KMZ file then linkBase is returned. If linkBase cannot be resolved to a local file then null is returned.

Parameters:

linkBase - the address of the document containing the requested element.

linkRef - the element's identifier.

Returns:

the requested element, or null if the element is not found.

Throws:

IllegalArgumentException - if the address is null.

resolveNetworkLink

public Object resolveNetworkLink(String link,
                                 boolean cacheRemoteFile,
                                 long updateTime)

Resolves a NetworkLink to a local or remote KML document. This method retrieves remote resources asynchronously using the FileStore.

The return value is a parsed KMLRoot representing the linked document. The return value is null if the linked file is not a KML file, or is not yet available in the FileStore.

The cacheRemoteFile parameter specifies whether to store a retrieved remote file in the World Wind cache or in a temporary location. This parameter has no effect if the file exists locally. The temporary location for a retrieved file does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

Parameters:

link - the address to resolve

cacheRemoteFile - true to store remote files in the World Wind cache, or false to store remote files in a temporary location. Has no effect if the address is a local file.

updateTime - the time at which the link was last updated. If a cached file exists for the specified resource, the file must have been retrieved after the link update time. Otherwise, the cache entry is considered invalid, and the file is deleted and retrieved again.

Returns:

URL to the requested file, parsed KMLRoot, or KML feature. Returns null if the document is not yet available in the FileStore.

Throws:

IllegalArgumentException - if the link is null.

resolveReference

public Object resolveReference(String link)

Resolves a reference to a remote or local element of the form address#identifier, where "address" identifies a local or remote document, including the current document, and and "identifier" is the id of the desired element.

If the address part identifies the current document, the document is searched for the specified identifier. Otherwise the document is retrieved, opened and searched for the identifier. If the address refers to a remote document and the document has not previously been retrieved and cached locally, retrieval is initiated and this method returns null. Once the document is successfully retrieved, subsequent calls to this method return the identified element, if it exists.

If the link does not contain an identifier part, this initiates a retrieval for document referenced by the address part and returns null. Once the document is retrieved this opens the the document as a KMLRoot. Subsequent calls to this method return the opened document, if it exists.

Parameters:

link - the document address in the form address#identifier.

Returns:

the requested document, the requested or element within a document, or null if the document or the element are not found.

Throws:

IllegalArgumentException - if the link is null.

resolveReference

public Object resolveReference(String link,
                               boolean cacheRemoteFile)

Resolves a reference to a remote or local element of the form address#identifier, where "address" identifies a local or remote document, including the current document, and and "identifier" is the id of the desired element.

If the address part identifies the current document, the document is searched for the specified identifier. Otherwise the document is retrieved, opened and searched for the identifier. If the address refers to a remote document and the document has not previously been retrieved and cached locally, retrieval is initiated and this method returns null. Once the document is successfully retrieved, subsequent calls to this method return the identified element, if it exists.

If the link does not contain an identifier part, this initiates a retrieval for document referenced by the address part and returns null. Once the document is retrieved this opens the the document as a KMLRoot. Subsequent calls to this method return the opened document, if it exists.

The cacheRemoteFile parameter specifies whether to store a retrieved remote document in the World Wind cache or in a temporary location. This parameter has no effect if the document exists locally. The temporary location for a retrieved document does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

Parameters:

link - the document address in the form address#identifier.

cacheRemoteFile - true to store remote documents in the World Wind cache, or false to store remote documents in a temporary location. Has no effect if the address is a local document.

Returns:

the requested document, the requested or element within a document, or null if the document or the element are not found.

Throws:

IllegalArgumentException - if the link is null.

resolveRemoteReference

public Object resolveRemoteReference(String linkBase,
                                     String linkRef)

Resolves a reference to a remote element identified by address and identifier, where linkBase identifies a remote document, and linkRef is the id of the desired element. This method retrieves resources asynchronously using the FileStore.

The return value is null if the file is not yet available in the FileStore. If linkBase refers to a KML or KMZ file and linkRef is non-null, the return value is the element identified by linkRef. If linkBase refers to a KML or KMZ and linkRef is null, the return value is a parsed KMLRoot for the KML file identified by linkBase. Otherwise the return value is a URL to the file in the file cache.

Parameters:

linkBase - the address of the document containing the requested element.

linkRef - the element's identifier.

Returns:

URL to the requested file, parsed KMLRoot, or KML feature. Returns null if the document is not yet available in the FileStore.

Throws:

IllegalArgumentException - if the linkBase is null.

resolveRemoteReference

public Object resolveRemoteReference(String linkBase,
                                     String linkRef,
                                     boolean cacheRemoteFile)

Resolves a reference to a remote element identified by address and identifier, where linkBase identifies a remote document, and linkRef is the id of the desired element. This method retrieves resources asynchronously using the FileStore.

The return value is null if the file is not yet available in the FileStore. If linkBase refers to a KML or KMZ file and linkRef is non-null, the return value is the element identified by linkRef. If linkBase refers to a KML or KMZ and linkRef is null, the return value is a parsed KMLRoot for the KML file identified by linkBase. Otherwise the return value is a URL to the file in the file cache or a temporary location, depending on the value of cacheRemoteFile.

The cacheRemoteFile parameter specifies whether to store a retrieved remote file in the World Wind cache or in a temporary location. This parameter has no effect if the file exists locally. The temporary location for a retrieved file does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

Parameters:

linkBase - the address of the document containing the requested element.

linkRef - the element's identifier.

cacheRemoteFile - true to store remote files in the World Wind cache, or false to store remote files in a temporary location. Has no effect if the address is a local file.

Returns:

URL to the requested file, parsed KMLRoot, or KML feature. Returns null if the document is not yet available in the FileStore.

Throws:

IllegalArgumentException - if the linkBase is null.

setDetailHint

public void setDetailHint(double detailHint)

Specifies this KML root's detail hint. The detail hint modifies the default relationship of KML scene resolution to screen resolution as the viewing distance changes. Values greater than 0 cause KML elements with a level of detail to appear at higher resolution at greater distances than normal, but at an increased performance cost. Values less than 0 decrease the default resolution at any given distance. The default value is 0. Values typically range between -0.5 and 0.5.

The top level KML root's detail hint is inherited by all KML elements beneath that root, including any descendant KML roots loaded by network links. If this KML root has been loaded by a network link, its detail hint is ignored.

Parameters:

detailHint - the degree to modify the default relationship of KML scene resolution to screen resolution as viewing distance changes. Values greater than 0 increase the resolution. Values less than 0 decrease the resolution. The default value is 0.

setNotificationListener

public void setNotificationListener(XMLParserNotificationListener listener)

Specifies the object to receive notifications of important occurrences during parsing, such as exceptions and the occurrence of unrecognized element types.

The default notification listener writes a message to the log, and otherwise does nothing.

Parameters:

listener - the listener to receive notifications. Specify null to indicate no listener.

See Also:

XMLParserNotification