gov.nasa.worldwind.ogc.kml
Class KMLNetworkLink

java.lang.Object
  gov.nasa.worldwind.util.xml.AbstractXMLEventParser
      gov.nasa.worldwind.ogc.kml.KMLAbstractObject
          gov.nasa.worldwind.ogc.kml.KMLAbstractFeature
              gov.nasa.worldwind.ogc.kml.KMLAbstractContainer
                  gov.nasa.worldwind.ogc.kml.KMLNetworkLink

All Implemented Interfaces:

MessageListener, KMLRenderable, XMLEventParser, PropertyChangeListener, EventListener

public class KMLNetworkLink
extends KMLAbstractContainer
implements PropertyChangeListener

Represents the KML NetworkLink element and provides access to its contents.

During rendering, KMLNetworkLink retrieves and loads its network resource whenever necessary. Upon a successful retrieval, KMLNetworkLink sends an AVKey.RETRIEVAL_STATE_SUCCESSFUL property change event to this link's property change listeners. Once retrieved and loaded, KMLNetworkLink stores its network resource by calling setNetworkResource, draws its network resource during preRendering and rendering, and forwards property change events from the network resource to its property change listeners.

During retrieval, KMLNetworkLink attempts to use either the Link or the Url. The Link is the preferred method for encoding a KML NetworkLink's address since KML version 2.1, therefore we give it priority over Url.

Nested Class Summary

protected static class

KMLNetworkLink.RequestTask Attempts to find this network link resource file locally, and if that fails attempts to find it remotely.

Field Summary

protected AtomicLong	firstRetrievalTime
protected boolean	invalidTarget Flag that is raised if the link retrieves a files that is not a KML document.
protected KMLLink	link
protected boolean	linkFetched Flag to indicate that the Link has been fetched from the hash map.
protected AtomicReference<KMLRoot>	networkResource Indicates the network resource referenced by this KMLNetworkLink.
protected AtomicLong	networkResourceRetrievalTime Time, in milliseconds since the Epoch, at which this KMLNetworkLink's network resource was last retrieved.
protected KMLRoot	root Cache the root of this network link.

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

features

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

balloon, region, styleSelectors, visibility

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

KMLNetworkLink(String namespaceURI)
Construct an instance.

Method Summary

void	applyChange(KMLAbstractObject sourceValues)
protected long	computeExpiryRefreshTime(KMLRoot root, String address) Indicates the expiration time of a linked resource.
protected void	doPreRender(KMLTraversalContext tc, DrawContext dc) Pre-renders the network resource referenced by this KMLNetworkLink.
protected void	doRender(KMLTraversalContext tc, DrawContext dc) Renders the network resource referenced by this KMLNetworkLink.
String	getDescription()
Boolean	getFlyToView()
protected KMLLink	getLinkOrUrl() Returns this NetworkLink's Link element or its Url element, depending on which is available.
String	getName()
KMLLink	getNetworkLink()
KMLRoot	getNetworkResource() Indicates the network resource referenced by this KMLNetworkLink.
Boolean	getRefreshVisibility()
KMLRoot	getRoot() Overridden to cache the root instead of climbing the parse tree each time.
Object	getSnippet()
KMLLink	getUrl()
protected boolean	hasNetworkLinkControl()
protected boolean	isFeatureActive(KMLTraversalContext tc, DrawContext dc) Indicates whether this KMLAbstractContainer is active and should be rendered on the specified DrawContext.
boolean	isLinkCacheable() Indicates whether the network resource references by this KMLNetworkLink should be retrieved to the World Wind cache or to a temporary location.
protected boolean	mustRetrieveNetworkResource() Returns whether this KMLNetworkLink must retrieve its network resource.
void	onChange(Message msg)
void	onMessage(Message msg) Invoked when a message is received.
void	propertyChange(PropertyChangeEvent evt) Forward property change events from the inner KMLRoot to this object's parent KMLRoot.
protected void	requestResource(DrawContext dc) Thread's off a task to determine whether the resource is local or remote and then retrieves it either from disk cache or a remote server.
protected void	reset()
protected void	retrieveNetworkResource(String address) Initiates a retrieval of the network resource referenced by this KMLNetworkLink.
void	setNetworkResource(KMLRoot kmlRoot) Specifies the network resource referenced by this KMLNetworkLink, or null if this link has no resource.

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

addFeature, beginRendering, doAddEventContent, endRendering, getFeatures, mergeFeatures, preRenderFeatures, removeFeature, renderFeatures

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

addStyleSelector, getAddress, getAddressDetails, getAuthor, getBalloon, getExtendedData, getLink, getOpen, getPhoneNumber, getRegion, getSnippetText, getStyleSelectors, getStyleUrl, getSubStyle, getTimePrimitive, getView, getVisibility, hasStyle, hasStyleSelectors, mergeStyleSelectors, preRender, render, renderBalloon, setBalloon, setRegion, setTimePrimitive, setView, setVisibility

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

getId, getTargetId

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

allocate, doAddCharacters, doAddEventAttribute, 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

firstRetrievalTime

protected AtomicLong firstRetrievalTime

invalidTarget

protected boolean invalidTarget

Flag that is raised if the link retrieves a files that is not a KML document. In this case, do not attempt to retrieve the resource again until the link changes. If the link changes then target file may also have changed.

link

protected KMLLink link

linkFetched

protected boolean linkFetched

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

networkResource

protected AtomicReference<KMLRoot> networkResource

Indicates the network resource referenced by this KMLNetworkLink. Initially null.

networkResourceRetrievalTime

protected AtomicLong networkResourceRetrievalTime

Time, in milliseconds since the Epoch, at which this KMLNetworkLink's network resource was last retrieved. Initially -1, indicating that the network resource has not been retrieved.

root

protected KMLRoot root

Cache the root of this network link. Accessing the root by climbing up a deep network link tree can be a performance bottleneck.

Constructor Detail

KMLNetworkLink

public KMLNetworkLink(String namespaceURI)

Construct an instance.

Parameters:

namespaceURI - the qualifying namespace URI. May be null to indicate no namespace qualification.

Method Detail

applyChange

public void applyChange(KMLAbstractObject sourceValues)

Overrides:

applyChange in class KMLAbstractContainer

computeExpiryRefreshTime

protected long computeExpiryRefreshTime(KMLRoot root,
                                        String address)

Indicates the expiration time of a linked resource. The expiration time is specified by (in order of priority): a NetworkLinkControl/expires element in the target document, a HTTP Cache-Control header, or an HTTP Expires header.

Parameters:

root - Root of target resource.

address - Address of linked resource.

Returns:

The expiration time of the resource, in milliseconds since the Epoch. Zero indicates that there is no expiration time.

doPreRender

protected void doPreRender(KMLTraversalContext tc,
                           DrawContext dc)

Pre-renders the network resource referenced by this KMLNetworkLink. If this link must retrieve its network resource, this initiates a retrieval and does nothing until the resource is retrieved and loaded. Once the network resource is retrieved and loaded, this calls setNetworkResource(KMLRoot) to specify this link's new network resource, and sends an AVKey.RETRIEVAL_STATE_SUCCESSFUL property change event to this link's property change listeners.

Overrides:

doPreRender in class KMLAbstractContainer

Parameters:

tc - the current KML traversal context.

dc - the current draw context.

See Also:

getNetworkResource()

doRender

protected void doRender(KMLTraversalContext tc,
                        DrawContext dc)

Renders the network resource referenced by this KMLNetworkLink. This does nothing if this link has no network resource.

Overrides:

doRender in class KMLAbstractContainer

Parameters:

tc - the current KML traversal context.

dc - the current draw context.

getDescription

public String getDescription()

Overrides:

getDescription in class KMLAbstractFeature

getFlyToView

public Boolean getFlyToView()

getLinkOrUrl

protected KMLLink getLinkOrUrl()

Returns this NetworkLink's Link element or its Url element, depending on which is available. Link is the preferred method for encoding a NetworkLink since KML version 2.1, therefore we give it priority. If a Link is not specified, the deprecated Url element is returned.

Returns:

this NetworkLink's Link element, if one is specified. Otherwise, this NetworkLink's Url element. Returns null if neither Link or a Url are specified.

getName

public String getName()

Overrides:

getName in class KMLAbstractFeature

getNetworkLink

public KMLLink getNetworkLink()

getNetworkResource

public KMLRoot getNetworkResource()

Indicates the network resource referenced by this KMLNetworkLink. This returns null if this link has no resource.

Returns:

this link's network resource, or null to indicate that this link has no resource.

See Also:

setNetworkResource(KMLRoot)

getRefreshVisibility

public Boolean getRefreshVisibility()

getRoot

public KMLRoot getRoot()

Overridden to cache the root instead of climbing the parse tree each time.

Overrides:

getRoot in class KMLAbstractObject

getSnippet

public Object getSnippet()

Overrides:

getSnippet in class KMLAbstractFeature

getUrl

public KMLLink getUrl()

hasNetworkLinkControl

protected boolean hasNetworkLinkControl()

isFeatureActive

protected boolean isFeatureActive(KMLTraversalContext tc,
                                  DrawContext dc)

Indicates whether this KMLAbstractContainer is active and should be rendered on the specified DrawContext. This returns true if this container's visibility is unspecified (null) or is set to true.

Regions do not apply directly to KML containers, because a descendant features can override the container's Region with its own. Since a descendant Region may be larger or have a less restrictive LOD range than this container, we cannot determine the visibility of the entire tree based on this container's Region. A container's Region is inherited by any descendants that do not specify a Region, and Region visibility is determined at the leaf nodes. Overridden to apply region culling according to the same rules as in KMLAbstractFeature. This prevents retrieving network links in inactive regions.

Overrides:

isFeatureActive in class KMLAbstractContainer

Parameters:

tc - the current KML traversal context. This parameter is ignored.

dc - the draw context. This parameter is ignored.

Returns:

true if this container should be rendered, otherwise false.

isLinkCacheable

public boolean isLinkCacheable()

Indicates whether the network resource references by this KMLNetworkLink should be retrieved to the World Wind cache or to a temporary location. This returns true if all of the following conditions are met, and false otherwise:

• This network link has either a Link or a Url element.
• The Link or Url element's refreshMode is not onInterval or onExpire.
• The Link or Url element's viewRefreshMode is not onStop.

Returns:

true if this link's network resource can should be stored in a cache, or false if it should be stored in a temporary location.

mustRetrieveNetworkResource

protected boolean mustRetrieveNetworkResource()

Returns whether this KMLNetworkLink must retrieve its network resource. This always returns false if this KMLNetworkLink has no KMLLink.

Returns:

true if this KMLNetworkLink must retrieve its network resource, otherwise false.

onChange

public void onChange(Message msg)

Overrides:

onChange in class KMLAbstractObject

onMessage

public void onMessage(Message msg)

Description copied from interface: MessageListener

Invoked when a message is received.

Specified by:

onMessage in interface MessageListener

Overrides:

onMessage in class KMLAbstractContainer

Parameters:

msg - The message that was received.

propertyChange

public void propertyChange(PropertyChangeEvent evt)

Forward property change events from the inner KMLRoot to this object's parent KMLRoot.

Specified by:

propertyChange in interface PropertyChangeListener

Parameters:

evt - Event to forward.

requestResource

protected void requestResource(DrawContext dc)

Thread's off a task to determine whether the resource is local or remote and then retrieves it either from disk cache or a remote server.

Parameters:

dc - the current draw context.

reset

protected void reset()

retrieveNetworkResource

protected void retrieveNetworkResource(String address)

Initiates a retrieval of the network resource referenced by this KMLNetworkLink. Once the network resource is retrieved and loaded, this calls setNetworkResource(KMLRoot) to specify this link's new network resource, and sends an AVKey.RETRIEVAL_STATE_SUCCESSFUL property change event to this link's property change listeners.

This does nothing if this KMLNetworkLink has no KMLLink.

Parameters:

address - the address of the resource to retrieve

setNetworkResource

public void setNetworkResource(KMLRoot kmlRoot)

Specifies the network resource referenced by this KMLNetworkLink, or null if this link has no resource. If the specified kmlRoot is not nullkmlRoot during preRendering and rendering, and forwards property change events from the kmlRoot to this link's property change listeners.

Parameters:

kmlRoot - the network resource referenced by this KMLNetworkLink. May be null.

See Also:

getNetworkResource()