gov.nasa.worldwind.ogc.kml
Class KMLLink

java.lang.Object
  gov.nasa.worldwind.util.xml.AbstractXMLEventParser
      gov.nasa.worldwind.ogc.kml.KMLAbstractObject
          gov.nasa.worldwind.ogc.kml.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 Summary

protected static String	DEFAULT_VIEW_FORMAT
protected String	finalHref If this link's href does not need to be modified with a query string, this value is the resource address.
protected URL	hrefURL The URL for the raw href.
protected ScheduledFuture	refreshTask Scheduled task that will update the when it runs.
protected AtomicLong	updateTime The time, in milliseconds since the Epoch, at which the linked content was most recently updated.

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

KMLLink(String namespaceURI)
Construct an instance.

Method Summary

void	applyChange(KMLAbstractObject sourceValues)
protected 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.
protected Long	computeRefreshTime()
protected Sector	computeVisibleBounds(DrawContext dc) Returns a Sector that specifies the current visible bounds on the globe.
String	getAddress(DrawContext dc) Returns the address of the resource specified by this KML link.
String	getHref()
String	getHttpQuery()
Double	getRefreshInterval()
String	getRefreshMode()
long	getUpdateTime() Returns the time at which the linked resource was last updated.
Double	getViewBoundScale()
String	getViewFormat()
String	getViewRefreshMode()
Double	getViewRefreshTime()
protected boolean	isLocalReference(URL url) Returns whether the resource specified by the url is a local resource.
void	onMessage(Message msg) Schedule the link to refresh when an View.VIEW_STOPPED message is received, and the link's view refresh mode is onStop.
Object	parse(XMLEventParserContext ctx, XMLEvent inputEvent, Object... args) Parse the event and initialize the parser's values to those found in the event.
protected ScheduledFuture	scheduleDelayedTask(Runnable task, long delay, TimeUnit timeUnit) Schedule a task to mark a link as updated after a delay.
protected void	scheduleRefreshIfNeeded() Schedule a task to refresh the link if the refresh mode requires it.
void	setExpirationTime(long time) Specifies the time at which the linked resource expires.
void	setField(String keyName, Object value) Overridden to mark onChange links as updated when a field set.
void	setUpdateTime(long updateTime) Specifies the time at which the linked resource was last updated.

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

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, parseCharacterContent, removeField, setField, setFields, setParent

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_VIEW_FORMAT

protected static final String DEFAULT_VIEW_FORMAT

See Also:

Constant Field Values

finalHref

protected 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 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 ScheduledFuture refreshTask

Scheduled task that will update the when it runs. Used to implement onInterval refresh mode.

updateTime

protected AtomicLong updateTime

The time, in milliseconds since the Epoch, at which the linked content was most recently updated.

Constructor Detail

KMLLink

public KMLLink(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 KMLAbstractObject

buildQueryString

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

computeRefreshTime

protected Long computeRefreshTime()

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.

getAddress

public 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] - World Wind client version.
• [clientName] - World Wind client name.
• [kmlVersion] - KML version supported by World Wind.
• [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:

IllegalArgumentException - if dc is null.

See Also:

getHref(), getViewFormat(), getHttpQuery(), Configuration

getHref

public String getHref()

getHttpQuery

public String getHttpQuery()

getRefreshInterval

public Double getRefreshInterval()

getRefreshMode

public String getRefreshMode()

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.

getViewBoundScale

public Double getViewBoundScale()

getViewFormat

public String getViewFormat()

getViewRefreshMode

public String getViewRefreshMode()

getViewRefreshTime

public Double getViewRefreshTime()

isLocalReference

protected boolean isLocalReference(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.

onMessage

public void onMessage(Message msg)

Schedule the link to refresh when an View.VIEW_STOPPED message is received, and the link's view refresh mode is onStop.

Specified by:

onMessage in interface MessageListener

Overrides:

onMessage in class KMLAbstractObject

Parameters:

msg - The message that was received.

parse

public Object parse(XMLEventParserContext ctx,
                    XMLEvent inputEvent,
                    Object... args)
             throws 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:

XMLStreamException - if an exception occurs during event-stream reading.

scheduleDelayedTask

protected ScheduledFuture scheduleDelayedTask(Runnable task,
                                              long delay,
                                              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.

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

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.

setField

public void setField(String keyName,
                     Object value)

Overridden to mark onChange links as updated when a field set.

Overrides:

setField in class AbstractXMLEventParser

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.