Package gov.nasa.worldwind.ogc.kml

Class KMLNetworkLink

  • All Implemented Interfaces:
    MessageListener, KMLRenderable, XMLEventParser, java.beans.PropertyChangeListener, java.util.EventListener
    public class KMLNetworkLink
extends KMLAbstractContainer
implements java.beans.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.

    • Field Detail

      • networkResource

        protected java.util.concurrent.atomic.AtomicReference<KMLRoot> networkResource
        Indicates the network resource referenced by this KMLNetworkLink. Initially null.

      • networkResourceRetrievalTime

        protected java.util.concurrent.atomic.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.

      • firstRetrievalTime

        protected java.util.concurrent.atomic.AtomicLong firstRetrievalTime

      • linkFetched

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

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

      • 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​(java.lang.String namespaceURI)
        Construct an instance.
        Parameters:
        namespaceURI - the qualifying namespace URI. May be null to indicate no namespace qualification.

    • Method Detail

      • propertyChange

        public void propertyChange​(java.beans.PropertyChangeEvent evt)
        Forward property change events from the inner KMLRoot to this object's parent KMLRoot.
        Specified by:
        propertyChange in interface java.beans.PropertyChangeListener
        Parameters:
        evt - Event to forward.

      • getRoot

        public KMLRoot getRoot()
        Overridden to cache the root instead of climbing the parse tree each time.
        Overrides:
        getRoot in class KMLAbstractObject

      • getRefreshVisibility

        public java.lang.Boolean getRefreshVisibility()

      • getFlyToView

        public java.lang.Boolean getFlyToView()

      • getNetworkLink

        public KMLLink getNetworkLink()

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

      • 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)

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

      • hasNetworkLinkControl

        protected boolean hasNetworkLinkControl()

      • 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 null, this link draws the kmlRoot 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()

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

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

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

      • retrieveNetworkResource

        protected void retrieveNetworkResource​(java.lang.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

      • computeExpiryRefreshTime

        protected long computeExpiryRefreshTime​(KMLRoot root,
                                        java.lang.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.

      • isLinkCacheable

        public boolean isLinkCacheable()
        Indicates whether the network resource references by this KMLNetworkLink should be retrieved to the WorldWind 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.

      • reset

        protected void reset()