Resource Traversal

A resource traversal occurs when the KML reader uses a resource reference to retrieve a file external to the current KML file. The KML reader is capable of traversing the following types of resource references:

  • <NetworkLink><Link><href>
  • <GroundOverlay><Icon><href>
  • <ScreenOverlay><Icon><href>
  • <PhotoOverlay><Icon><href>
  • <SchemaData @schemaUrl>
  • <Placemark><Model><Link><href>

At this time, <Placemark><styleUrl> is not traversed.

Resource Location

Resources can either be local, or remote. Local resources are located on either the local file system, or a mounted network drive. Examples of local resources would be C: emp\foo.jpg or \\FILES\data\bar.kml. Remote resources are resources that are accessed via internet protocols. The KML reader supports the ftp and http protocols.

The value of the reader’s Traverse NetworkLinks parameter determines how resource references are handled.

  • All: All resource references are traversed
  • Local: Only local references to resources are traversed (that is, a NetworkLink reference to a local file will be traversed, but a reference to a file on a remote web server will not).
  • No: No resource references are traversed. This may limit some of the reader’s functionality.

Relative References

Resource references often refer to resources in a location that is relative to the referring resource. An example would be roads.kml referring to schema.kml via a schemaUrl. The KML reader attempts to resolve relative references into an absolute reference by maintaining a record of the location from which the referring resource was retrieved. For example if roads.kml is retrieved from http://example.com/roads.kml, the KML reader will attempt to load schema.kml from http://example.com/schema.kml.

Remote Resources Downloads

Files downloaded as a result of traversing remote resource references are each stored in unique folders in $(FME_TEMP). Unique download locations ensure that files with similar filenames do not overwrite each other. Upon the completion of the translation, all downloaded files will be removed. To override this behavior, the KML reader's Delete Downloaded Files parameter can be set to No.

Resources can also be downloaded from remote web services, for example http://example.com/mapdata.php?layer=roads, may return KML data. As part of the downloading process, the reader performs two actions:

  1. The mime-type of the server’s response is compared against a set of expected mime-types. I.e. to verify that it is KML data (or image data for Overlays).
  2. Any non-alphanumeric characters in the resulting filename are replaced by underscores. The appropriate file extension is also provided as needed. For example, if the above service responded with KML data, it would be stored in mapdata_php_layer_roads.kml.

Traversal Depth

The KML reader is capable of limiting resource traversal depth. This option allows users to control how much data the KML reader retrieves in a give translation. For example, if reading a complex dataset from a web-service, it is possible for a.kml to refer to b.kml, which refers to c.kml, etc. By default, the traversal depth is capped at 5, but can be increased as necessary using the KML reader’s Maximum NetworkLinks Traversal Depth parameter.

There are no restrictions on traversal breadth, i.e. the number of traversals per file.

Network Errors

The KML reader has the option of ignoring, but logging, network errors that are encountered during the translation. Service provider issues or temporary network outages may cause such errors.

By default, network errors will not result in a fatal error; the Fail on Network Errors reader parameter can be used to change the default behavior.