Package gov.nasa.worldwind.ogc.kml

Class KMLLink

  • All Implemented Interfaces:
    MessageListener, XMLEventParser
    Direct Known Subclasses:
    KMLIcon
    public class KMLLink
extends KMLAbstractObject
    Represents the KML Link element and provides access to its contents. The Link maintains a timestamp that indicates when the resource was last updated. The timestamp is updated based on the link's refresh mode. Code that uses a resource loaded from a Link should keep track of when the resource was retrieved, and periodically check that timestamp against the timestamp returned by getUpdateTime().

    • Field Detail

      • DEFAULT_VIEW_FORMAT

        protected static final java.lang.String DEFAULT_VIEW_FORMAT
        See Also:
        Constant Field Values

      • updateTime

        protected java.util.concurrent.atomic.AtomicLong updateTime
        The time, in milliseconds since the Epoch, at which the linked content was most recently updated.

      • finalHref

        protected java.lang.String finalHref
        If this link's href does not need to be modified with a query string, this value is the resource address.

      • hrefURL

        protected java.net.URL hrefURL
        The URL for the raw href. Will be null if the href is not a remote URL or this link has a query string

      • refreshTask

        protected java.util.concurrent.ScheduledFuture refreshTask
        Scheduled task that will update the when it runs. Used to implement onInterval refresh mode.

    • Constructor Detail

      • KMLLink

        public KMLLink​(java.lang.String namespaceURI)
        Construct an instance.
        Parameters:
        namespaceURI - the qualifying namespace URI. May be null to indicate no namespace qualification.

    • Method Detail

      • getHref

        public java.lang.String getHref()

      • getRefreshMode

        public java.lang.String getRefreshMode()

      • getRefreshInterval

        public java.lang.Double getRefreshInterval()

      • getViewRefreshMode

        public java.lang.String getViewRefreshMode()

      • getViewRefreshTime

        public java.lang.Double getViewRefreshTime()

      • getViewBoundScale

        public java.lang.Double getViewBoundScale()

      • getViewFormat

        public java.lang.String getViewFormat()

      • getHttpQuery

        public java.lang.String getHttpQuery()

      • setField

        public void setField​(java.lang.String keyName,
                     java.lang.Object value)
        Overridden to mark onChange links as updated when a field set.
        Overrides:
        setField in class AbstractXMLEventParser

      • getUpdateTime

        public long getUpdateTime()
        Returns the time at which the linked resource was last updated. This method is safe to call from any thread.
        Returns:
        The time at which the linked content was most recently updated. See System.currentTimeMillis() for its numerical meaning of this timestamp.

      • setUpdateTime

        public void setUpdateTime​(long updateTime)
        Specifies the time at which the linked resource was last updated. This method is safe to call from any thread.
        Parameters:
        updateTime - The time at which the linked content was most recently updated. See System.currentTimeMillis() for its numerical meaning of this timestamp.

      • setExpirationTime

        public void setExpirationTime​(long time)
        Specifies the time at which the linked resource expires. If the link's update mode is onExpire, the link will mark itself updated at this time.
        Parameters:
        time - Time, in milliseconds since the Epoch, at which the link expires. Zero indicates no expiration.

      • scheduleRefreshIfNeeded

        protected void scheduleRefreshIfNeeded()
        Schedule a task to refresh the link if the refresh mode requires it. In the case of an onInterval and onExpire refresh modes, this method schedules a task to update the link after the refresh interval elapses, but only if such a task has not already been scheduled (only one refresh task is active at a time).

      • computeRefreshTime

        protected java.lang.Long computeRefreshTime()

      • scheduleDelayedTask

        protected java.util.concurrent.ScheduledFuture scheduleDelayedTask​(java.lang.Runnable task,
                                                                   long delay,
                                                                   java.util.concurrent.TimeUnit timeUnit)
        Schedule a task to mark a link as updated after a delay. The task only executes once.
        Parameters:
        task - Task to schedule.
        delay - Delay to wait before executing the task. The time unit is determined by {code timeUnit}.
        timeUnit - The time unit of delay.
        Returns:
        Future that represents the scheduled task.

      • parse

        public java.lang.Object parse​(XMLEventParserContext ctx,
                              javax.xml.stream.events.XMLEvent inputEvent,
                              java.lang.Object... args)
                       throws javax.xml.stream.XMLStreamException
        Parse the event and initialize the parser's values to those found in the event. Overridden to set a default refresh mode of onChange if the refresh mode is not specified.
        Specified by:
        parse in interface XMLEventParser
        Overrides:
        parse in class AbstractXMLEventParser
        Parameters:
        ctx - a current parser context.
        inputEvent - the event to parse.
        args - an optional list of arguments that may by used by subclasses.
        Returns:
        if parsing is successful, returns this, otherwise returns null.
        Throws:
        javax.xml.stream.XMLStreamException - if an exception occurs during event-stream reading.

      • getAddress

        public java.lang.String getAddress​(DrawContext dc)
        Returns the address of the resource specified by this KML link. If the resource specified in this link's href is a local resource, this returns only the href, and ignores the viewFormat and httpQuery. Otherwise, this returns the concatenation of the href, the viewFormat and the httpQuery for form an absolute URL string. If the the href contains a query string, the viewFormat and httpQuery are appended to that string. If necessary, this inserts the & character between the href's query string, the viewFormat, and the httpQuery.

        This substitutes the following parameters in viewFormat and httpQuery:

        • [bboxWest],[bboxSouth],[bboxEast],[bboxNorth] - visible bounds of the globe, or 0 if the globe is not visible. The visible bounds are scaled from their centroid by this link's viewBoundScale.
        • [lookatLon], [lookatLat] - longitude and latitude of the position on the globe the view is looking at, or 0 if the view is not looking at the globe.
        • [lookatRange] - distance between view's eye position and the point on the globe the view is looking at.
        • [lookatTilt], [lookatHeading] - view's tilt and heading.
        • [lookatTerrainLon], [lookatTerrainLat], [lookatTerrainAlt] - terrain position the view is looking at, or 0 if the view is not looking at the terrain.
        • [cameraLon], [cameraLat], [cameraAlt] - view's eye position.
        • [horizFov], [vertFov] - view's horizontal and vertical field of view.
        • [horizPixels], [vertPixels] - width and height of the viewport.
        • [terrainEnabled] - always true
        • [clientVersion] - WorldWind client version.
        • [clientName] - WorldWind client name.
        • [kmlVersion] - KML version supported by WorldWind.
        • [language] - current locale's language.
        If the viewFormat is unspecified, and the viewRefreshMode is one of onRequest, onStop or onRegion, this automatically appends the following information to the query string: BBOX=[bboxWest],[bboxSouth],[bboxEast],[bboxNorth]. The [clientName] and [clientVersion] parameters of the httpQuery may be specified in the configuration file using the keys AVKey.NAME and AVKey.VERSION. If not specified, this uses default values of Version.getVersionName() and Version.getVersion() for [clientName] and [clientVersion], respectively.
        Parameters:
        dc - the DrawContext used to determine the current view parameters.
        Returns:
        the address of the resource specified by this KML link.
        Throws:
        java.lang.IllegalArgumentException - if dc is null.
        See Also:
        getHref(), getViewFormat(), getHttpQuery(), Configuration

      • isLocalReference

        protected boolean isLocalReference​(java.net.URL url)
        Returns whether the resource specified by the url is a local resource.
        Parameters:
        url - the URL to test.
        Returns:
        true if the url specifies a local resource, otherwise false.

      • buildQueryString

        protected java.lang.String buildQueryString​(DrawContext dc)
        This returns the concatenation of the query part of href (if any), the viewFormat and the httpQuery to form the link URL's query part. This returns null if this link's href does not specify a URL. This substitutes parameters in viewFormat according to the specified DrawContext's current viewing parameters, and substitutes parameters in httpQuery according to the current Configuration parameters.
        Parameters:
        dc - the DrawContext used to determine the current view parameters.
        Returns:
        the query part of this KML link's address, or null if this link does not specify a URL.

      • computeVisibleBounds

        protected Sector computeVisibleBounds​(DrawContext dc)
        Returns a Sector that specifies the current visible bounds on the globe. If this link specifies a viewBoundScale, this scales the visible bounds from its centroid by that factor, but limits the bounds to [-90,90] latitude and [-180,180] longitude. This returns Sector.EMPTY_SECTOR if the globe is not visible.
        Parameters:
        dc - the DrawContext for which to compute the visible bounds.
        Returns:
        the current visible bounds on the specified DrawContext.