Dynamic PostGIS based layers
Just some background: all configuration files can now be found in the WEB-INF directory of the webapp. All paths given here are relative to this location. To start, it is recommended to extract/modify an already existing WMS configuration such as the CITE WMS setup instead of creating one from scratch.
1. Setting up the service
1.1. Setting up the database connection
In conf/jdbc create a new file (e.g. conn.xml) with the following content:
<PooledConnection xmlns="http://www.deegree.org/jdbc"> <Url>jdbc:postgresql://localhost/dynamic</Url> <User>postgres</User> <Password>postgres</Password> <PoolMinSize>5</PoolMinSize> <PoolMaxSize>20</PoolMaxSize> </PooledConnection>
Now you've configured a database connection which can be used from all services that can use connections.
1.2. Setting up the WMS configuration
Open the file conf/services/wms.xml. You can use a dynamic layer anywhere were you can also use any other layer (do not use it as root layer, though). The dynamically generated layers will be inserted at the location of the dynamic layer element. A minimal configuration may look like this:
<?xml version="1.0" encoding="UTF-8"?> <deegreeWMS xmlns="http://www.deegree.org/services/wms" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" configVersion="0.5.0" xsi:schemaLocation="http://www.deegree.org/services/wms http://schemas.deegree.org/wms/0.5.0/wms_configuration.xsd"> <ServiceConfiguration> <UnrequestableLayer> <Title>Root Layer</Title> <CRS>EPSG:31466 EPSG:31467 EPSG:31468 EPSG:4326 EPSG:25832</CRS> <DynamicLayer> <PostGIS>conn</PostGIS> </DynamicLayer> </UnrequestableLayer> </ServiceConfiguration> </deegreeWMS>
What you've configured here is a dynamic PostGIS layer that is based upon the connection with ID conn. IDs are given implicitly from the file name of the connection configuration (without the .xml suffix).
1.3. Setting up the database
The database DDL script can currently only be downloaded from the deegree-core svn, it will drop and recreate the required tables.
With this, you're done and can start the WMS. Of course, you don't have layers and styles in the database yet, but we'll get to that next.
2. The database structure
In general, all IDs used are integers. The connections between the layers, styles and parts of the styles is done via these keys. The ID fields are all called id. The id fields are not mentioned below any more. By default, they are defined using a sequence.
2.1. Adding new layers
To add a new layer, simply add a row into the layers table.
The layers table has the following fields:
- name: you should give new layers a name, if you want them to be requestable
- title: optional, used as title in the WMS capabilities output. If not set, the name will be used.
- connectionid: optional, defaults to the connection of the layer database connection itself
- sourcetable: optional, if used, the sourcequery and bboxquery will be generated automatically
sourcequery: optional, can be used to use a custom query (e.g. a more complex JOIN query). The query must have one ? where the WKT bounding box will be placed as varchar, and must select geometries as WKB. Example for PostGIS:
select field1, field2, asbinary(geom_field) as geom, field_other as field3 from table where geom_field && st_geomfromtext(?, -1)
crs: must be set to the EPSG code of the geometries, e.g. EPSG:25832. This does not have anything to do with the database mechanisms (SRID codes), and is merely there to let deegree know about the CRS. If your table uses an SRID constraint and you use a custom query, you must set the proper code in the query!
bboxquery: if sourcetable is not used, this must be a query that has a column called bbox which contains the bounding box of the data, as WKT. This can be a constant query, or a query making use of the spatial functions of your database. Here are two examples:
select astext(st_estimated_extent('mytable', 'geom_field')) as bbox select 'POLYGON((2572281 5611325.5,2572281 5627156,2585666.25 5627156,2585666.25 5611325.5,2572281 5611325.5))' as bbox
namespace: optional, the desired namespace of the resulting features. http://www.deegree.org/app is the default.
- symbolcodes: optional, if set, it can be a comma separated list of style ids that are used for all features with no specialized symbolization.
- symbolfield: optional, if set, it can be a comma separated list of style ids that override the layer default styles from the symbolcodes field.
2.2. Adding new styles
2.2.1. Main styles table
To add a new style, simply add a row into the styles table.
The styles correspond to the SLD/SE (StyledLayerDescriptor 1.0.0/SymbologyEncoding 1.1.0) Rule construct and have the following fields:
- type: optional, should be one of POLYGON, LINE, POINT or TEXT (case does not matter).
- name: optional, is used to identify the style in the WMS capabilities. If not set, the id will be used.
- fk: optional, should be set to the id of the actual style definition (see below).
- minscale: optional, can be used to set the lower scale barrier for which this style should be used. Default is negative infinity.
- maxscale: optional, can be used to set the upper scale barrier for which this style should be used. Default is positive infinity.
sld: optional, can be used to store a predefined SLD/SE snippet which is loaded instead of constructing one from the style tables. Please note that importing of SLD level styles is not supported, the style should start with FeatureTypeStyle as root element (but may still be in the SLD namespace).
You should either use the sld field, or type plus fk (but not both).
All of the 'symbolizer' tables (points, lines, polygons, texts) have the optional uom field, which can be used to specify the unit of measure which should be used to interpret numeric values in the actual styling information. This is based on the SE concept, and allows for pixel (which is the default), meter/metre, foot (currently not very well supported, testdata would be welcome) and mm (which is actually not contained in SE). One can get very pleasant looking, scaling maps using meter as UOM (and a metric coordinate system for the data!).
The points table only contains one field:
- graphic_id: optional, should contain an id from the graphics table (see below)
The lines table contains the following fields:
- stroke_id: optional, should contain an id from the strokes table (see below)
- perpendicularoffset: optional, contains a value in the UOM specifying the perpendicular offset (default is 0), as specified in SE.
The polygons table contains the following fields:
- fill_id, stroke_id: optional, should contain an id from the fills/strokes table
- displacementx, displacementy, perpendicularoffset: all optional, contain values in the UOM as specified in SE
The texts table contains the following fields:
- labelexpr: must contain an OGC filter expression (as defined in the filter encoding specification, 1.1.0). Example:
<PropertyName xmlns="http://www.opengis.net/ogc" xmlns:app="http://www.deegree.org/app">app:ortsname</PropertyName>
- font_id, fill_id, lineplacement_id, halo_id: all optional, refer to the tables specified below.
- rotation, displacementx, displacementy, anchorx, anchory: all optional, contain values in the UOM as specified in SE
2.2.6. Style components
This section contains a description of the various style components, that are reused from all styles. Readers should refer to the SE specification for full documentation of the various fields. Only literal values are allowed here, no OGC filter expressions. Since the fields are fairly self-explanatory for readers familiar with SE, only deegree specifics are mentioned here.
- fills: no specifics
- strokes: positionpercentage can be used to specify the location of a graphical stroke with respect to the geometry. A value of 50 will paint the graphic approximately in the middle of a given line.
- lineplacements: generalizeline is currently not supported, work on line placement rendering (and label rendering in general) is still not finished.
- graphics: the various possibilities to define a graphic are mutually exclusive, so don't specify a wellknownname if you want a raster image. svg is used as vector graphics, and the style of the svg is ignored (use fills and strokes to redefine a styling). base64raster can be used to specify any bitmap image that can be read by Java ImageIO (base64 encoded obviously). Styling of raster images along a line is not supported (and possibly never will be as it does not look very nice).
To run the tools, use the d3toolbox, which can be downloaded from the artefacts server. To see which tools are available, just run the appropriate d3toolbox script in the bin directory, to run a tool, just add the tool name as argument.
3.1. Importing SLD/SE styles into the database
There is a rudimentary tool that can be used to import existing SE/SLD styles (as above from FeatureTypeStyle downwards) into the styles database. Run the toolbox with PostgreSQLImporter to get a command line help.
3.2. Checking styles database
There is a tool that tries to load all files in the database, and can be used to remove broken styles automatically. Run the toolbox with StyleChecker to get a command line help.