Parameter Filters¶

Parameter filters provide templates for extracting arbitrary parameters from requests. This allows using GeoWebCache in scenarios such as time series data, multiple styles for the same layer or with CQL filters set by the client.

There are four types of parameter filters:

String filters (<stringParameterFilter>)
Floating point number filters (<floatParameterFilter>)
Integer filters (<integerParameterFilter>)
Regular expression filters (<regexParameterFilter>)

A given layer can have multiple types of parameter filters.

If a request does not comply with the allowed values of the set parameter, the request will fail, usually with an error such as:

400: <value> violates filter for parameter <key>

String filter¶

GeoWebCache can also use an allowable list of string values in a parameter filter for a given key. If the string in the request matches one of the string specified in the parameter filter, the request will proceed.

When specifying a string filter, three pieces of information are required:

Key (<key>). The key is not case sensitive.
Default value (<defaultValue>).
List of strings (<values>, <string>). The strings are case sensitive.

This information is presented in the following schema inside the <wmsLayer> tag:

<parameterFilters>
  <stringParameterFilter>
    <key> ...  </key>
    <defaultValue> ... </defaultValue>
    <values>
      <string> ... </string>
      <string> ... </string>
       ...
    </values>
  </stringParameterFilter>
</parameterFilters>

For example, it is possible to set the allowed values of the “styles” parameter to one of three values: “polygon”, “population”, with a third default blank value for when the parameter is unspecified.

The resulting parameter filter would be:

<parameterFilters>
  <stringParameterFilter>
    <key>styles</key>
    <defaultValue></defaultValue>
    <values>
      <string></string>
      <string>population</string>
      <string>polygon</string>
    </values>
  </stringParameterFilter>
</parameterFilters>

Floating point filter¶

Similar to a string filter, GeoWebCache can also recognize a list of numerical values for a given key. If the value requested matches one of the values specified in the filter, the request will proceed.

When specifying a numerical filter, four pieces of information are required:

Key (<key>). This key is not case sensitive.
Default value (<defaultValue>).
List of values (<values>, <float>).
Threshold (<threshold>).

This information is presented in the following schema inside the <wmsLayer> tag:

<parameterFilters>
  <floatParameterFilter>
    <key> ... </key>
    <defaultValue> ... </defaultValue>
    <values>
      <float> ... </float>
      <float> ... </float>
      ...
    </values>
    <threshold> ... </threshold>
  </floatParameterFilter>
</parameterFilters>

For example, given a parameter called elevation, where the allowed values are -42.5, 0, and 100 and the default value being 100, the filter would be:

<parameterFilters>
  <floatParameterFilter>
    <key>elevation</key>
    <defaultValue>-42.5</defaultValue>
    <values>
      <float>42.5</float>
      <float>0</float>
      <float>100</float>
    </values>
    <threshold>50</threshold>
  </floatParameterFilter>
</parameterFilters>

Note also the above example sets a threshold of 50. A value that is within the threshold of any of the allowed values will still proceed, albeit rounded to one of the allowed values. So in this example, a value of 75 would be successfully requested as 100.0, but a value of 200 will fail.

Thresholds are also valuable when managing possible floating point rounding errors. For example, if your data has accuracy down to the sixth decimal place, you may want to use a threshold of 1e-6 to ensure proper matching.

Note that the request value produced by the filter will always include a decimal point and floating point arithmetic has limitted precision that can means certain values can’t be correctly represented. If you are working with exclusively integer (“whole number”) values, it’s better to use the integerParameterFilter instead.

Integer filter¶

This works in much the same way as the floating point filter, but only allows whole numbers, including negatives.

Again, four pieces of information are required:

Key (<key>). This key is not case sensitive.
Default value (<defaultValue>).
List of values (<values>, <int>).
Threshold (<threshold>).

This information is presented in the following schema inside the <wmsLayer> tag:

<parameterFilters>
  <integerParameterFilter>
    <key> ... </key>
    <defaultValue> ... </defaultValue>
    <values>
      <int> ... </int>
      <int> ... </int>
      ...
    </values>
    <threshold> ... </threshold>
  </integerParameterFilter>
</parameterFilters>

If the paramter were dim_year, where the allowed values are 1996, and 2006 and the default value being 2006, the filter would be:

<parameterFilters>
  <integerParameterFilter>
    <key>dim_year</key>
    <defaultValue>2006</defaultValue>
    <values>
      <float>1996</float>
      <float>2006</float>
    </values>
    <threshold>2</threshold>
  </floatParameterFilter>
</parameterFilters>

Note also the above example sets a threshold of 2 to only cover the specific value listed and one year either side. So in this example, a value of 2007 would be successfully requested as 2006, but a value of 2008 will fail.

Note that unlike the floatParameterFilter, there is no decimal point in the requested value.

Regular expression filter¶

For a finer control of parameter values, GeoWebCache can recognize regular expressions for the value in a filter. If a requested value matches the pattern in the regular expression, the request will proceed.

Note

GeoWebCache uses standard Java regular expressions. For more information, please see the regular expression pattern documentation at: http://download.oracle.com/javase/1.5.0/docs/api/java/util/regex/Pattern.html.

When specifying a regular expression filter, three pieces of information are required:

Key (<key>). The key is not case sensitive.
Default value (<defaultValue>).
Regular expression (<regex>).

This information is presented in the following schema inside the <wmsLayer> tag:

<parameterFilters>
  <regexParameterFilter>
    <key> ... </key>
    <defaultValue> ... </defaultValue>
    <regex> ... </regex>
  </regexParameterFilter>
</parameterFilters>

Regular expressions allows you to specify the same allowed styles as in the above string filter example. To set two allowed values for the “styles” parameter: “polygon”, “population”, with a third default blank value for when the parameter is unspecified, the regular expression would be:

^(|polygon|population)$

The resulting parameter filter would be:

<parameterFilters>
  <regexParameterFilter>
    <key>styles</key>
    <defaultValue></defaultValue>
    <regex>^(|polygon|population)$</regex>
  </regexParameterFilter>
</parameterFilters>

Case normalization¶

You can normalize the case of a Regular Expression or String rule to upper or lower case by adding a normalize element. This takes a case and an optional locale. case may be NONE for no normalization, UPPER for upper case, or LOWER for lower case. locale may be any Java locale identifier supported by the JVM and the JVM default locale will be used if not specified.

<parameterFilters>
  <regexParameterFilter>
    <key>styles</key>
    <defaultValue></defaultValue>
    <normalize>
      <case>UPPER</case>
      <locale>en_CA</locale> <!-- Canadian English locale-->
    <regex>^(|polygon|population)$</regex>
  </regexParameterFilter>
</parameterFilters>

If upper or lower case normalization is used, matching with legal values will be case insensitive, otherwise it will be case sensitive. The default value is never normalized.