The full configuration allows use of the full set of parameters that can be used for controlling the deegree WMS. This includes the parameters mentioned in the OGC WMS 1.1.1 specification for the Capabilities document, but also additional specific technical parameters as for example descriptions of data sources for each layer or the maximum cache size.
In the following, the elements of the configuration file will be described in detail. Appendix A includes the complete configuration document.
After the root element, some deegree-WMS-specific parameters are defined. The <RootDirectory> defines the file system directory where all documents and folders needed by deegree are stored (besides documents that are referenced in the configuration by absolute paths). The <DefaultOnlineResource> is the URL by which the WMS operations can be invoked. This parameter can be overwritten by the URLs defined in the request-definitions. Both parameters are mandatory. You have to adjust the <RootDirectory> and <DefaultOnlineResource> to your system.
<DeegreeParam>
<!-- mandatory -->
<RootDirectory>C:/deegree</RootDirectory>
<!-- mandatory -->
<DefaultOnlineResource xlink="http://www.w3.org/1999/xlink" type="simple"
xlink:href="http://www.deegree.org/wms"/>
<CacheSize>100</CacheSize>
<MaxLifeTime>3600</MaxLifeTime>
<RequestTimeLimit>15</RequestTimeLimit>
<!-- determines the quality of the map/image generated from a GetMap request.
the parameter only will be evaluated if the desired format is able to handle it.
the range of values is 0 ... 1, where 1 is best and 0 is worst. default is 0.95 -->
<MapQuality>0.95</MapQuality>
<!-- maximum map width that can be requested. default = 1000 -->
<MaxMapWidth>1000</MaxMapWidth>
<!-- maximum map height that can be requested. default = 1000 -->
<MaxMapHeight>1000</MaxMapHeight>
<!-- copyright note that will be drawn at the left side of the maps bottom -->
<CopyRight>(c) deegree WMS 2003</CopyRight>
<!-- returns the URl where the DTD for OGC WMS capabilities DOCTYPE definiton
is located. default = http://schemas.opengis.net/wms/1.1.1/WMS_MS_Capabilities.dtd -->
<DTDLocation>
<OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple"
xlink:href="http://schemas.opengis.net/wms/1.1.1/WMS_MS_Capabilities.dtd"/>
</DTDLocation>
<!-- define a proxy server if the WMS is seperated by a firewall from the DTD-location or the
locations of connected REMOTEWFS, REMOTEWCS and REMOTEWMS -->
<Proxy proxyHost="131.220.106.104" proxyPort="1234"/>
</DeegreeParam>The <CacheSize> parameter defines the size of the cache available to deegree-WMS in megabyte (this does not affect the cache for data sources). This parameter is optional, its default value is 100 MB. With the <MaxLifeTime> the user defines the time interval after which the internal processes of the WMS will be stopped if there are no requests active. If this parameter is not supplied, its default is 3600 seconds. By <RequestTimeLimit> the maximum time span is defined after which a request has to be processed. If this value is exceeded the processing is cancelled and an exception will be thrown. Its default value is 15 seconds.
Afterwards a <MapQuality> parameter is defined, by which the quality of the created maps can be controlled. Values for this parameter are between 0 (lowest quality) and 1 (best quality) with the default value being 0.95. This parameter is only used for image formats supporting different quality values (e.g. jpeg).
The following two parameters limit the maximum size of a map that can be requested via WMS. It has to be considered that requesting large maps is very taxing on a server as the processing cost increases with the square of the border length of a map. For example, the creation a map having 1000x1000 pixel takes four times the memory than creating a map with size 500x500 pixel. Default is 1000 pixel for width and height.
With the <CopyRight> parameter it is possible to write a copyright remark in the lower left corner of each map. In case this parameter is not supplied no output is produced.
The <DTDLocation> Element encapsulates an online resource that refrences the location of the DTD defining the capabilities format. As default this the DTD located at the opengis schema server. But if the WMS shall be used behind a firewall, proxy or just local it may be useful to define another location.
If the WMS runs behind a firewall/proxy it is necessary to publish the proxy server address and port to the WMS (Java runtime environment) if data from remote datasources outside the firewall are included in the WMS. Because in this case the WMS has to access servers from outside the firewall the network connection have to be passed throught the proxy. Alternatively the proxy paramteres can be passed to the Java runtime environment by commandline parameters when starting the servlet engine (see java documentation).
The following definition of service metadata is adopted from the WMS 1.1.1 specification.
<Service> <Name>deegree wms</Name> <Title>deegree wms</Title> <Abstract>wms reference implementation</Abstract> <KeywordList> <Keyword>deegree</Keyword> <Keyword>wms</Keyword> </KeywordList> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.deegree.org"/> <ContactInformation> <ContactPersonPrimary> <ContactPerson>Markus Müller</ContactPerson> <ContactOrganization>lat/lon</ContactOrganization> </ContactPersonPrimary> <ContactPosition>Senior Consultant</ContactPosition> <ContactAddress> <AddressType>XXXX</AddressType> <Address>Meckenheimer Allee 176</Address> <City>Bonn</City> <StateOrProvince>NRW</StateOrProvince> <PostCode>53115</PostCode> <Country>Germany</Country> </ContactAddress> <ContactVoiceTelephone>0049228732838</ContactVoiceTelephone> <ContactFacsimileTelephone>0049228732838</ContactFacsimileTelephone> <ContactElectronicMailAddress>info@lat-lon.de</ContactElectronicMailAddress> </ContactInformation> <Fees>none</Fees> <AccessConstraints>none</AccessConstraints> </Service>
The request-definition (GetCapabilities, GetMap and GetFeatureInfo) is in its form very similar to the definitions in OGC WMS 1.1.1 specification. However, some of the mandatory elements are declared optional. In case they are not supplied, deegree uses the corresponding default values. It is for example possible to not reference any of the requests explicitely. By default, GetCapabilities, GetMap and GetFeatureInfo will be initialized.
The following example is used to explain this by means of a GetMap request.
<GetMap> <!-- default = image/gif; image/png; image/jpg --> <Format>image/gif</Format> <Format>image/png</Format> <Format>image/jpeg</Format> <Format>image/tif</Format> <Format>image/bmp</Format> <Format>image/svg+xml</Format> <DCPType> <HTTP> <Get> <!-- default = %DefaultOnlineResource% --> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href=" http://www.deegree.org/wms "/> </Get> </HTTP> </DCPType> </GetMap>
You have to adjust the "xlink:href" attribute of the <OnlineResource> element to your system.
In case no <GetMap> element is defined, a GetMap with the formats image/gif, image/png and image/jpg will be initialized using the <DefaultOnlineResource> as web address for http-POST and GET. If a <GetMap> element is defined supplying information regarding Online-Resources but not the format, the above mentioned formats will be supported and initialized.
If only http-GET is defined, only this protocol is supported. Otherwise, if only http-POST is defined, http-GET is complemented as it is mandatory. The behaviour of the server regarding the image formats is likewise, all mandatory image formats will be initialized even if not defined by the user. An exception to this behaviour is the format image/png that is initialized anyway, as the OGC WMS 1.1.1 specification suggests the support of one format able to define an alpha-channel.
[1]
The behaviour of the initialization for GetCapabilities and GetFeature is similar to GetMap. configuration of the operations DescribeLayer, GetLegendGraphic, GetStyles and PutStyles is also optional, but they will not be initialized with default values.
The format definition of GetFeatureInfo-Requests is distinct to the other format definitions. Its default format is application/vnd.ogc.gml. Further, used-defined formats are however possible. These are created using XSLT-transformations of the original GML output format. For allowing users (WMS-administrators) to define the output format without restrictions, it is possible to set the attribute ‘filter’ for the <Format>-elements of the GetFeatureInfo definition (with the exception of <Format>application/vnd.ogc.se_xml</Format>). This attribute references an XSLT-script, performing the output formatting.
<GetFeatureInfo> <Format>application/vnd.ogc.gml</Format> <Format>text/html</Format> <Format filter="file:///c:/deegreewms/wms/toXML.xsl"> application/vnd.ogc.wms_xml</Format> <DCPType> <HTTP> <Get> <OnlineResource xlink:type="simple" xlink:href="http://www.deegree.org/wms?" xmlns:xlink="http://www.w3.org/1999/xlink"/> </Get> </HTTP> </DCPType> </GetFeatureInfo>
In this example the XSLT-script file:///c:/deegree/wms/toXML.xsl is used as filter for the output format 'application/vnd.ogc.wms_xml', but there is no filter definition for 'text/html'. In this special case deegree is using a default filter defined by %RootDirectory%/WEB-INF/XML/featureinfo2html.xsl.
Do not forget to adjust the "xlink:href" attribute of the <OnlineResource> element to your system.
Just as there are default initializations for the output formats for GetMap, GetCapabilities and GetFeatureInfo, the same is true fort he Exception formats supplied by deegree-WMS.
<Exception> <!-- default = application/vnd.ogc.se_xml --> <Format>application/vnd.ogc.se_xml</Format> <Format>application/vnd.ogc.se_inimage</Format> <Format>application/vnd.ogc.se_blank</Format> </Exception>
If this information is not supplied, the default value 'application/vnd.ogc.se_xml' is used. If one or more Exception-formats are defined, this default format is complemented.
The next element defines if the WMS is capable of supporting SLDs.
<UserDefinedSymbolization SupportSLD="0" UserLayer="0" UserStyle="0" RemoteWFS="0"/>
This element as well as its attributes are optional. Its lacking indicates that the WMS is not able to support SLD, even if the WMS is technically capable to handle this kind of requests.
In the following, the layers known to the WMS are defined. Some elements here are not defined by the WMS 1.1.1 specification, especially those creating the association between layer and its data source.
It is possible, that a WMS supplies no layer definitions, indicating it serves no data of its own (a ‘component’ WMS as defined in the SLD specification). Such a server is nonetheless capable of serving maps by obtaining data directly or indirectly from the SLD documents sent to it.
The additional elements of the deegree-WMS configuration define the association of a layer with a data source (i.e. from a WFS or WCS).
<Layer queryable="1" cascaded="0" opaque="1" noSubsets="1"> <Name>Europe</Name> <Title>Datenlayer 1</Title> <Abstract>erster testdatenlayer</Abstract> <DataSource> <!-- default = equals the layer name and must be equal to the feature type or the layer name of the conected OWS --> <Name>Europe</Name> <!— name of the property that contains the geometries for this layer . this element will only be solved if the data source is a LOCALWFS or a REMOTEWFS default = '/GEOM' --> <GeometryProperty>/GEOM</GeometryProperty> <!—possible values: LOCALWFS, LOCALWCS, REMOTEWFS, REMOTEWCS, REMOTEWMS --> <!-- default = LOCALWFS --> <Type>LOCALWFS</Type> <!-- default is %Type%_capabilities.xml at the directory %RootDirectory%/WEB-INF/xml; default can only be used if data source type is LOCALXXX otherwise reference to the capabilities of the remote service must be set --> <OWSCapabilities> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.lat-lon.de/documents/capabilities.xml"/> </OWSCapabilities> <ScaleHint min="0" max="1000"/> <!-- optional; the filter expression will be completed with the requested bounding box --> <FilterCondition> <wfs:Query typeName="Europe" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" xmlns:wfs="http://www.opengis.net/wfs"> <wfs:PropertyName>/Europe/Name</wfs:PropertyName> <wfs:PropertyName>/Europe/Area</wfs:PropertyName> <wfs:PropertyName>/Europe/Border</wfs:PropertyName> <ogc:Filter> <ogc:And> <ogc:PropertyIsLessThan> <ogc:PropertyName>/Europe/Area</ogc:PropertyName> < ogc:Literal>50000</ogc:Literal> </ogc:PropertyIsLessThan> <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="\"> <ogc:PropertyName>/Europe/Administrator/City</ogc:PropertyName> <ogc:Literal>53115 Bonn</ogc:Literal> </ogc:PropertyIsLike> </ogc:And> </ogc:Filter> </wfs:Query> </FilterCondition> </DataSource>
After the optional element <Abstract>, <DataSource> is defined. It is also optional and will be replaced by a default value if not supplied. <DataSource> can be provided multiple times in case a scale-dependent definition is needed that uses different FeatureTypes/layers.
The <Name> element of the DataSource supplies the name of the FeatureType or Layer of the data that is supplied by the afterwards described OWS. This means that the name of the degree WMS layer and the name of the associated data provided by a OWS do not have to be identical. If <Name> is not defined the name of the layer is used. In case of a cascaded remote OWS the value of this field can be overwritten by the definition of a filter.
After the FeatureType/Layer name the properties of the data source are defined, that includes the necessary geometries (<GeometryProperty>). As a WFS can use arbitrarily defined properties to store geometries, this element is only needed if the data store is a LOCALWFS or a REMOTEWFS. Its default value is ‘/GEOM’.
The third subelement of <DataSource> declares the type of the data source. Five different values are possible for this:
LOCALWFS -> deegree-WFS running in the same Virtual Machine
REMOTEWFS -> any other WFS
LOCALWCS -> deegree-WCS running in the same VM
REMOTEWCS -> any other WCS
REMOTEWMS -> other WMS which is used for cascading
To be able to use the full set of opportunities the deegree WMS offeres you should read the deegree WFS and WCS documentation. How to configure access to database and and file-based raster and vector datasource is explained detailed in these documents. If you use use a remote OWS as datasource you may have to study its configuration documentation.
If no <OWSCapabilities> is supplied, only the values LOCALWFS and LOCALWCS are valid. In case a WCS or a REMOTEWMS is defined as data source, it is necessary to assure that they can deliver their data as image/gif, image/png, image/tif, image/jpg or as image/bmp.
<Type> is also optional, its default value is LOCALWFS.
<OWSCapabilities> specifies access to the capabilities of a remote data source. If for example a REMOTEWFS is defined as data source, the <OWSCapabilities> - respectively the <OnlineResource> - has to point to the Capabilities-document of the WFS.
<OWSCapabilities> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.lat-lon.de/documents/capabilities.xml"/> </OWSCapabilities>
In case neither <Type> nor <OWSCapabilities> are supplied it is assumed that the data source is a LOCALWFS whose Capabilities are in a document named LOCALWFS_capabilities.xml in the directory %RootDirectory%/WEB-INF/XML/.
If LOCALWCS is defined as <Type> and no <OWSCapabilities> element is supplied it is assumed that the Capabilities of the WCS are in a document named LOCALWCS_capabilities.xml in the directory %RootDirectory%/WEB-INF/XML/.
The optional element <ScaleHint> indicates the span of scales for which the respective data source is valid, it corresponds to the element defined by OGC WMS 1.1.1. If multiple data sources are defined for one layer, the spans supplied by <ScaleHint> must not overlap.
As last sub-element of <DataSource> a <FilterCondition> can be defined, that constrains the data delivered by a data source. For example a layer might be associated only with the features of the feature type ‘Europe’ (Type = REMOTEWFS or LOCALWFS), whose areas is smaller than 50000 m² and whose data administrator is working in Bonn.
<!-- optional; the filter expression will be enhanced by the bounding box of the current request --> <FilterCondition> <wfs:Query typeName="Europe" xmlns:gml="http://www.opengis.net/gml" xmlns:wfs="http://www.opengis.net/wfs" xmlns:ogc="http://www.opengis.net/ogc"> <wfs:PropertyName>/Europe/Name</wfs:PropertyName> <wfs:PropertyName>/Europe/Area</wfs:PropertyName> <wfs:PropertyName>/Europe/Border</wfs:PropertyName> <ogc:Filter> <ogc:And> <ogc:PropertyIsLessThan> <ogc:PropertyName>/Europe/Area</ogc:PropertyName> <ogc:Literal>50000</ogc:Literal> </ogc:PropertyIsLessThan> <ogc:PropertyIsLike wildCard="*" singleChar="?" escape="\"> <ogc:PropertyName>/Europe/Administrator/City</ogc:PropertyName> <ogc:Literal>53115 Bonn</ogc:Literal> </ogc:PropertyIsLike> </ogc:And> </ogc:Filter> </wfs:Query> </FilterCondition>
The filter expression must be applicable to the defined type of the data source, meaning that for example the filter defined above can only be used in conjunction with a WFS, that stores features belonging to the feature type Europe. The <typeName> of the query in this case overwrites the value of the element <Name> defined above.
The following example shows the <FilterCondition> for a REMOTEWMS:
<FilterCondition> <WMSRequest><![CDATA[WMTVER=1.0.0&LAYERS=Ortsteile,Bezirke& STYLES=style1,default&FORMAT=JPG&BGCOLOR=0xFFFFFF& TRANSPARENT=true]]></WMSRequest> </FilterCondition>
In this case the filter expression is overwriting several parameters of the layers (Name of the data store, styles) and of a incoming request (WMTVER, FORMAT, BGCOLOR, TRANSPARENT). Other parameters (SRS, WIDTH, HEIGHT, BBOX, EXCEPTION, REQUEST) must not be overwritten, as this might lead to inconsistencies when processing GetMap and GetFeatureInfo-Requests.
A filter for a WCS is similar to one for WFS:
<FilterCondition> <WMSRequest><![CDATA[version=0.7&Layer=world&Format=jpg]]></WMSRequest> </FilterCondition>
To all filters a BoundingBox is dynamically added, when a GetMap-request is processed.
As all sub-elements of the <DataSource> elements are optional and can be initialized by default values, the element itself is also optional. If no <DataSource> is supplied, a LOCALWFS is assumed to be the data source, with Capabilities having the name 'LOCALWFS_capabilities.xml' in the %RootDirectory%/WEB-INF/XML/ directory.
The following elements are optional elements defined by WMS 1.1.1. They are not modified by the deegree-configuration and not initialized by default values.
<SRS>EPSG:31467</SRS> <SRS>EPSG:31465</SRS> <LatLonBoundingBox minx="7" miny="43" maxx="12" maxy="56"/> <BoundingBox SRS="EPSG:31465" minx="12324" miny="23345" maxx="34456" maxy="34456" resx="4" resy="4"/> <BoundingBox SRS="EPSG:31466" minx="22324" miny="33345" maxx="44456" maxy="54456" resx="4" resy="4"/> <BoundingBox SRS="EPSG:31467" minx="32324" miny="43345" maxx="54456" maxy="64456" resx="4" resy="4"/> <Extent name="time" default="2000-10-17" nearestValue="1"> 2000-10-17,2000-12-17,2001-01-17</Extent> <Extent name="elevation" default="0">0/1000/100</Extent>
Notice that the deegree WMS supports automatic coordinate reference system (CRS) for vector data. This means each layer based on a vector data set like it comes from a shape file or a Oracle Spatial database is a available in nearly 180 CRS; you just have to define the ones you like for each layer or group of layers through <SRS> elements like in the code fragment above. A list of supported CRS is given in appendix A.
Next are the styles definitions of a layer that are also optional. A <StyleResource> element was added here, giving information about the resource where the style is defined. The resource where a style is defined must be a valid Styled Layer Descriptor document (see below)
<Style> <Name>teststyle</Name> <Title>ein teststype</Title> <!-- default = %RootDirectory%WEB-INF/xml//styles.xml --> <StyleResource>file:///c:/deegree/WEB-INF/xml/styles.xml</ StyleResource > <Abstract>dies ist nur ein test</Abstract> <LegendURL width="50" height="50"> <Format>image/jpg</Format> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.deegree.org/legend/teststyle.jpg"/> </LegendURL> <StyleSheetURL> <Format>/xsl</Format> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.deegree.org/legend/teststyle.xsl"/> </StyleSheetURL> <StyleURL> <Format>/css</Format> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.deegree.org/legend/teststyle.css"/> </StyleURL> </Style>
Default for <StyleResource> is %RootDirectory%/WEB-INF/xml/styles.xml.
Besides individually defined styles, each layer knows a default-style, that can be address either by the name 'default' or with a missing style parameter. If there is no style defined for a layer and cannot be inherited, such a layer knows exclusively the default style. deegree-WMS allows definition of distinct default styles for each layer individually. For this purpose a style can be defined in %RootDirectory%/WEB-INF/xml/styles.xml with its name beginning with 'default:' and displaying the name of the layer (default:%layername%). If for example a layer named 'Europe' is defined the name of its default style is default:Europe. If no individual default style is provided, the internal default style of deegree is used (area = 50% gray, lines = 1 pixel width an black, points = 7 pixel square 30% gray.
The Short-Configuration is not a distinct form of the deegree-WMS configuration but the consequent application of default values and initializations. The following example configures the Full-Configuration that was described in the above chapter in short form:
<WMT_MS_Capabilities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\java\source\deegree\xml\wms1.1.1.xsd" version="1.1.1" updateSequence="1.0.0"> <DeegreeParam> <RootDirectory>C:/deegree</RootDirectory> <DefaultOnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.deegree.org/wms"/> </DeegreeParam> <Service> <Name>deegree wms</Name> <Title>deegree wms</Title> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href="http://www.deegree.org"/> </Service> <Capability> <Layer queryable="0" noSubsets="0"> <Name>TestTopLevelLayer</Name> <Title>TestTopLevelLayer</Title> <LatLonBoundingBox minx="5" miny="42" maxx="15" maxy="56"/> <Layer queryable="1" noSubsets="1"> <Name>Eurpe</Name> <Title>Datenlayer 1</Title> </Layer> </Layer> </Capability> </WMT_MS_Capabilities>
At the beginning of the configuration file you will find the already mentioned deegree-specific parameters, defining the root directory and the URL, by which all operations can be accessed. Cache size and the maximum process lifetime are set to default values. The Service section only consists of the minimum set of parameters that have to be supplied (<Name>, <Title> and <OnlineResource>). The descriptions of the operations served by the WMS are missing, GetMap, GetFeatureInfo und GetCapabilities will be supported by default. Output formats are also defined by default values and the DefaultOnlineResource is used.
The description of the available layers is restricted to a minimum. The parent layer supplies besides a name and title a bounding box that is inherited by all child layers. EPSG:4326 is used as default coordinate reference system. The association to a data store is also initialized by defaults (LOCALWFS with a feature type that has the layer name). As there are no styles define, the layer only knows the default styles.
[1] DEVELOPERS NOTE:
deegree uses specialized handler classes to perform a GetMap and GetFeatureInfo request. As default these are org.deegree_impl.services.wms.GetMapHandler and org.deegree_impl.services.wms.GetFeatureInfoHandler To offer the capability to enhance the deegree WMS without changing the deegree code base it is possible to dynamicly link other classes into the WMS to handle requests. For this the <GetMap> and the <GetFeatureInfo> elements has an optional attribute named 'responsibleClass' to set a userdefined class for handling requests. So the example given above would become:
<GetMap responsibleClass="org.deegree_impl.services.wms.GetMapHandler"> <Format>image/gif</Format> … <DCPType> <HTTP> <Get> <OnlineResource xlink="http://www.w3.org/1999/xlink" type="simple" xlink:href=" http://www.deegree.org/wms "/> </Get> </HTTP> </DCPType> </GetMap>
(for method and interface definitions see deegree java doc)