Spatial Mapper

A spatial mapper links an Entity to a Spatial Engine. This linkage is not required and in fact, may not be possible if there is no spatial information associated with the entity.
If there is spatial information that relates to the entity and you want the users to be able to perform spatial operations (select by polygon, etc.) on the entity then a link should be set up.

The mapping is actually between the entity and an object that is managed by a spatial engine. The type of object will be different depending upon the spatial engine. For example, if the spatial engine is ArcSDE then the mapping will be between the entity and an ArcSDE Layer, for Oracle Spatial it will be between the entity and a spatially enabled table.

When adding a definition for a spatial mapping, the setup will be the same regardless of the spatial engine type but the "name" of the spatial object may be different. For example, a shapefile based spatial engine will refer to the spatial objects based on the filename which may be case sensitive depending upon the underlying operating system, but an Oracle Spatial engine will refer to a table name which may need to be fully qualified when a schema.

The spatial mapping also specified which column in the underlying table is used to uniquely identify an entity, this is set with the key attribute.
Because the key used by Weave to identify an entity may be different from that used by the underlying spatial entity to identify a feature there has to be a mapping performed between the Weave keys and the spatial engine feature ids.
Generally, this mapping is performed once at system startup and doesn't change unless Weave notices a change in the count of the available rows in the underlying table (which is checked every five minutes). This is assuming that the underlying keys/feature ids don't change and only the addition/removal of a row in the table would have an effect on the key mapping.

However there may be times when this is not suitable, for example, if the table if very large it can take a long time to read all of the key mappings and they can take up a large amount of memory, or if the key mappings do actually change frequently, so this initial key mapping can be disabled and the mapping between the Weave keys and the spatial engine feature ids can be performed on-the-fly each time Weave needs to transform a key to a feature id, or a feature id to a key. Obviously, this will have an impact on performance, since it requires a trip to the spatial engine for each transform, rather than having it done once and the transform performed in memory.

The initial loading of the key/fid mapping can be disabled, for either all spatial mappings in a spatial mapper or for a single spatial mapping, by setting the dynamic flag in the configuration.

In addition, if dynamic mapping is turned on you can indicate that the values retrieved from the spatial engine for a mapping should be kept in memory to avoid the cost of querying the spatial engine next time the mapping is required, this is done by setting the cache flag in the configuration. This can be useful if you want to avoid the longer startup time but the key/fid mappings are still fairly static (so it's safe to have them loaded once). This provides a middle ground, if suitable, between a static, loaded at startup, key/fid mapping, and a dynamic, performed each time, key/fid mapping.

Namespace

urn:com.cohga.server.spatial.mapper#1.0

Tags

mapper

Properties

Sub-tags

Content

None

Notes

• The CRS property does not perform any transform, it just tells the server how the actual data is stored in cases where the underlying spatial engine does not supply this information or supplied an incorrect value.

mapping

Properties

Sub-tags

Content

None

Notes

• The CRS property does not perform any transformation, it just tells the server how the actual data is stored in cases where the underlying spatial engine does not supply this information or supplied an incorrect value.
• Only 1 level of nesting is supported for sub-mappings.
• Only table and key are allowed in sub-mapping tags.
• Only table is required, key can be inferred from the parent mapping.

Examples

<mapper:mapper id="mapper.arcsde">
	<spatialEngine>spatialengine.arcsde</spatialEngine>
	<mapping>
		<entity>property</entity>
		<table>PROPERTY</table>
		<key>PID</key>
	</mapping>
	<mapping>
		<entity>roads</entity>
		<key>RD_NAME</key>
		<mapping>
			<table>MAJOR_ROADS</table>
		</mapping>
		<mapping>
			<table>MINOR_ROADS</table>
		</mapping>
	</mapping>
	<mapping>
		<entity>suburbs</entity>
		<table>SUBURBS</table>
		<key>LOC_NAME</key>
	</mapping>
	<mapping>
		<entity>council_buildings</entity>
		<table>BUILDINGS</table>
	</mapping>
</mapping>
<mapper:mapper id="mapper.oracle">
	<spatialEngine>spatialengine.oracle</spatialEngine>
	<mapping>
		<entity>drainage</entity>
		<table>DRAINAGE</table>
	</mapping>
</mapper:mapper>

If the data in the underlying spatial engine can change over time then the dynamic and cache flags should be set to disable caching and enable dynamic lookup of the id's. This is especially relevant if the id's change when records are added or deleted for example so should always be performed when the entity is editable.

<mapper:mapper id="mapper.edit">
	<spatialEngine>spatialengine.arcsde</spatialEngine>
	<mapping>
		<entity>grafitti</entity>
		<table>GRAFITTI</table>
		<key>PID</key>
		<dynamic>true</dynamic>
		<cache>false</cache>
	</mapping>
</mapper:mapper>

<mapper:mapper id="mapper.main">
	<spatialEngine>spatialengine.arcsde</spatialEngine>
	<mapping>
		<entity>property</entity>
		<table>PROPERTY</table>
		<key>PID</key>
		<filter><![CDATA[status = 'C']]></filter>
	</mapping>
</mapper:mapper>

Filters

<filter>lga_code == 0</filter>

<filter><![CDATA[lga_code <> 0]]></filter>

<filter><![CDATA[planno = 'LP129263']]></filter>

<filter><![CDATA[planno LIKE 'LP%']]></filter>

<filter><![CDATA[planno NOT LIKE 'LP%']]></filter>

<filter>further_de IS NULL</filter>

<filter>further_de IS NOT NULL</filter>

<filter><![CDATA[CROSS(the_geom, LINESTRING(332312 5815856, 333688 5823904))]]></filter>

<filter><![CDATA[CROSS(the_geom, LINESTRING(332312 5815856, 333688 5823904)) OR CROSS(the_geom, LINESTRING(331312 5814856, 332688 5822904))]]></filter>

<filter><![CDATA[BBOX(the_geom, 332312,5815856,333688,5816856)]]></filter>

Other Filters

<filter><![CDATA[DWITHIN(the_geom, POINT(331899 5818553), 500, meters)]]></mapper:filter>

<filter><![CDATA[BEYOND(the_geom, POINT(331899 5818553), 500, meters)]]></filter>

<filter><![CDATA[INTERSECT(the_geom, GEOMETRYCOLLECTION(LINESTRING(332312 5815856, 333688 5823904), LINESTRING(333312 5815856, 334688 5823904)))]]></filter>