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 filesystem, 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_NETWORKLINK directive determines how resource references are handled.
All: All resource references are traversed
Local: Only local references to resources are traversed. I.e. a NetworkLink reference to a local file will be traversed, but a reference to a file on a remote web server will not.
None: 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 behaviour, the KML reader's DELETE_DOWNLOADED_FILES directive 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:
- 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).
- 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 MAX_NETWORKLINK_TRAVERSAL_DEPTH directive.
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_ERROR reader directive can be used to change the default behavior.