[206] | 1 | .. _services-zcfg: |
---|
| 2 | |
---|
| 3 | ZCFG : the ZOO Service Configuration File |
---|
[349] | 4 | ========================================= |
---|
| 5 | |
---|
[323] | 6 | :Authors: Nicolas Bozon, Gérald Fenoy, Jeff McKenna |
---|
[315] | 7 | :Last Updated: $Date: 2014-04-30 23:28:14 +0000 (Wed, 30 Apr 2014) $ |
---|
[206] | 8 | |
---|
| 9 | .. contents:: Table of Contents |
---|
| 10 | :depth: 3 |
---|
| 11 | :backlinks: top |
---|
| 12 | |
---|
| 13 | The ZOO Service configuration file (.zcfg) describes the service and will be parsed by |
---|
| 14 | the ZOO Kernel. We will describe here what such a file contains. |
---|
| 15 | You can also take a look at the existing examples of ZCFG files in the ``cgi-env`` directory |
---|
| 16 | of each services available in the `ZOO-Project SVN source tree <http://zoo-project.org/trac/browser/trunk/zoo-services>`__. |
---|
| 17 | |
---|
| 18 | A ZOO Configuration file is divided into three distinct sections : |
---|
| 19 | |
---|
| 20 | 1. Main Metadata information |
---|
[469] | 21 | 2. List of Inputs metadata information (optional since `rev. 469 <http://zoo-project.org/trac/changeset/469>`__) |
---|
[206] | 22 | 3. List of Outputs metadata information |
---|
| 23 | |
---|
| 24 | .. Note:: The ZOO Service Configuration File is case sensitive. |
---|
| 25 | |
---|
| 26 | Main Metadata Information |
---|
| 27 | ------------------------- |
---|
| 28 | |
---|
| 29 | The fist part in a ZOO Configuration file contains the metadata information relative to the service. |
---|
| 30 | Note that the "name of your service" between brackets on the first line has to be the exact same name |
---|
| 31 | as the function you defined in your services provider code. In most cases, this name is also the name |
---|
| 32 | of the ZCFG file without the "``.zcfg``" extension. |
---|
| 33 | |
---|
| 34 | You can see below a description of the main metadata information: |
---|
| 35 | |
---|
[259] | 36 | .. code-block:: none |
---|
[206] | 37 | :linenos: |
---|
| 38 | |
---|
| 39 | [Name of your service] |
---|
| 40 | Title = Title of your service |
---|
| 41 | Abstract = Description of your service |
---|
| 42 | processVersion = Version number of your service |
---|
| 43 | storeSupported = true/false |
---|
| 44 | statusSupported = true/false |
---|
| 45 | serviceType = the programming language used to implement the service (C/Fortran/Python/Java/PHP/Javascript) |
---|
| 46 | serviceProvider = name of your services provider (shared library/Python Module/Java Class/PHP Script/JavaScript script) |
---|
| 47 | <MetaData> |
---|
| 48 | title = Metadata title of your service |
---|
| 49 | </MetaData> |
---|
| 50 | |
---|
| 51 | List of Inputs |
---|
| 52 | -------------- |
---|
| 53 | |
---|
| 54 | The list of inputs contains metadata information of each supported input, and they are grouped using a ``<DataInputs>`` node. |
---|
| 55 | |
---|
| 56 | Each input is defined as : |
---|
| 57 | |
---|
| 58 | - a name (between brackets as for the name of the service before) |
---|
| 59 | - various medata properties (``Title``, ``Abstract``, ``minOccurs`` and ``maxOccurs``) |
---|
| 60 | - a Type Of Data node (:ref:`description <typeDataNodes>`) |
---|
| 61 | |
---|
| 62 | A typical list of inputs (``<DataInputs>``) look like the following: |
---|
| 63 | |
---|
[259] | 64 | .. code-block:: none |
---|
[206] | 65 | :linenos: |
---|
| 66 | |
---|
| 67 | <DataInputs> |
---|
| 68 | [Name of the first input] |
---|
| 69 | Title = Title of the first input |
---|
| 70 | Abstract = Abstract describing the first input |
---|
| 71 | minOccurs = Minimum occurence of the first input |
---|
| 72 | maxOccurs = Maximum occurence of the first input |
---|
| 73 | <Type Of Data Node /> |
---|
| 74 | [Name of the second input] |
---|
| 75 | Title = Title of the second input |
---|
| 76 | Abstract = Abstract describing the second input |
---|
| 77 | minOccurs = Minimum occurence of the second input |
---|
| 78 | maxOccurs = Maximum occurence of the second input |
---|
| 79 | <Type Of Data Node /> |
---|
| 80 | </DataInputs> |
---|
| 81 | |
---|
| 82 | .. Note:: you can add ``<MetaData>`` node as in the main metadata information. |
---|
| 83 | |
---|
| 84 | List of Outputs |
---|
| 85 | --------------- |
---|
| 86 | |
---|
| 87 | The list of outputs is very similar to a list of inputs except it is specified as a ``<DataOutputs>`` node. |
---|
| 88 | |
---|
| 89 | A typical ``<DataOutputs>`` node looks like the following: |
---|
| 90 | |
---|
[259] | 91 | .. code-block:: none |
---|
[206] | 92 | :linenos: |
---|
| 93 | |
---|
| 94 | <DataOutputs> |
---|
| 95 | [Name of the output] |
---|
| 96 | Title = Title of the output |
---|
| 97 | Abstract = Description of the output |
---|
| 98 | <Type Of Data Node /> |
---|
| 99 | </DataOutputs> |
---|
| 100 | |
---|
| 101 | .. _typeDataNodes: |
---|
| 102 | |
---|
| 103 | Type Of Data Nodes |
---|
| 104 | ------------------ |
---|
| 105 | |
---|
| 106 | In the beginning of this ZCFG introduction, we spoke about "Type Of Data Nodes" to describe the data type of inputs and outputs. |
---|
| 107 | |
---|
| 108 | You can define your data as: |
---|
| 109 | |
---|
| 110 | - :ref:`LiteralData <LiteralData>` |
---|
| 111 | - :ref:`BoundingBoxData <BoundingBoxData>` |
---|
| 112 | - :ref:`ComplexData <ComplexData>` |
---|
| 113 | |
---|
[469] | 114 | Except for ``LiteralData``, each *Type Of Data* node must have at least one ``<Default>`` node. Even |
---|
| 115 | if empty, it **has to be present**. So, something |
---|
| 116 | like the following should be present in your ZCFG file: |
---|
[206] | 117 | |
---|
| 118 | .. code-block:: guess |
---|
| 119 | :linenos: |
---|
| 120 | |
---|
[469] | 121 | <Default /> |
---|
[206] | 122 | |
---|
[469] | 123 | Otherwise, ZOO-Kernel won't be able to parse your ZCFG correctly. |
---|
[206] | 124 | |
---|
| 125 | .. _LiteralData: |
---|
| 126 | |
---|
| 127 | LiteralData node |
---|
| 128 | **************** |
---|
| 129 | |
---|
| 130 | A ``<LiteralData>`` node contains: |
---|
| 131 | |
---|
[459] | 132 | - one (optional) ``AllowedValues`` key containing all value allowed for this input |
---|
[469] | 133 | - one (optional) ``range`` properties containing the range (``[``, ``]``) |
---|
[461] | 134 | - one (optional) ``rangeMin`` (``rangeMax``) properties containing the minimum (maximum) value of this range |
---|
[459] | 135 | - one (optional) ``rangeSpacing`` properties containing the regular distance or spacing between value in this range |
---|
[462] | 136 | - one (optional) ``rangeClosure`` properties containing the closure type (``c``, ``o``, ``oc``, ``co``) |
---|
[206] | 137 | - one ``<Default>`` node, |
---|
| 138 | - zero or more ``<Supported>`` nodes depending on the existence or the number of supported Units Of Measure (UOM), and |
---|
| 139 | - a ``dataType`` property. The ``dataType`` property defines the type of literal data, such as a string, an interger and so on |
---|
| 140 | (consult `the complete list <http://www.w3.org/TR/xmlschema-2/#built-in-datatypes>`__ of supported data types). |
---|
| 141 | |
---|
| 142 | ``<Default>`` and ``<Supported>`` nodes can contain the ``uom`` property to define which UOM has to be used for |
---|
| 143 | this input value. |
---|
| 144 | |
---|
| 145 | For input ``<LiteralData>`` nodes, you can add the ``value`` property to the ``<Default>`` node to define a default |
---|
| 146 | value for this input. This means that, when your Service will be run, even if the input wasn't defined, this default |
---|
| 147 | value will be set as the current value for this input. |
---|
| 148 | |
---|
| 149 | A typical ``<LiteralData>`` node, defining a ``float`` data type using meters or degrees for its UOM, looks like the |
---|
| 150 | following: |
---|
| 151 | |
---|
| 152 | .. code-block:: guess |
---|
| 153 | :linenos: |
---|
| 154 | |
---|
| 155 | <LiteralData> |
---|
| 156 | dataType = float |
---|
| 157 | <Default> |
---|
| 158 | uom = meters |
---|
| 159 | </Default> |
---|
| 160 | <Supported> |
---|
| 161 | uom = feet |
---|
| 162 | </Supported> |
---|
| 163 | </LiteralData> |
---|
| 164 | |
---|
[459] | 165 | |
---|
| 166 | A typical ``<LiteralData>`` node, defining a ``float`` data type which |
---|
| 167 | should take values contained in ``[0.0,100.0]``, looks like the following: |
---|
[460] | 168 | |
---|
[459] | 169 | .. code-block:: guess |
---|
| 170 | :linenos: |
---|
| 171 | |
---|
| 172 | <LiteralData> |
---|
| 173 | dataType = float |
---|
| 174 | rangeMin = 0.0 |
---|
| 175 | rangeMax = 100.0 |
---|
| 176 | rangeClosure = c |
---|
| 177 | <Default /> |
---|
| 178 | </LiteralData> |
---|
| 179 | |
---|
[469] | 180 | Or more simply: |
---|
| 181 | |
---|
| 182 | .. code-block:: guess |
---|
| 183 | :linenos: |
---|
| 184 | |
---|
| 185 | <LiteralData> |
---|
| 186 | dataType = float |
---|
| 187 | range = [0.0,100.0] |
---|
| 188 | <Default /> |
---|
| 189 | </LiteralData> |
---|
| 190 | |
---|
[459] | 191 | A typical ``<LiteralData>`` node, defining a ``string`` data type which |
---|
| 192 | support values ``hillshade``, ``slope``, ``aspect``, ``TRI``, ``TPI`` |
---|
| 193 | and ``roughness``, looks like the following: |
---|
[460] | 194 | |
---|
[459] | 195 | .. code-block:: guess |
---|
| 196 | :linenos: |
---|
| 197 | |
---|
| 198 | <LiteralData> |
---|
[463] | 199 | dataType = string |
---|
[459] | 200 | AllowedValues = hillshade,slope,aspect,TRI,TPI,roughness |
---|
| 201 | <Default /> |
---|
| 202 | </LiteralData> |
---|
| 203 | |
---|
[460] | 204 | Properties ``AllowedValues`` and ``range*`` can be conbined with both ``<Default>`` and |
---|
[469] | 205 | ``<Supported>`` nodes in the same was as ``<LiteralData>`` node. For |
---|
| 206 | instance, the following is supported: |
---|
[459] | 207 | |
---|
[469] | 208 | .. code-block:: guess |
---|
| 209 | :linenos: |
---|
| 210 | |
---|
| 211 | <LiteralData> |
---|
| 212 | dataType = int |
---|
| 213 | <Default> |
---|
| 214 | value = 11 |
---|
| 215 | AllowedValues = -10,-8,-7,-5,-1 |
---|
| 216 | rangeMin = 0 |
---|
| 217 | rangeMin = 100 |
---|
| 218 | rangeClosure = co |
---|
| 219 | </Default> |
---|
| 220 | <Supported> |
---|
| 221 | rangeMin = 200 |
---|
| 222 | rangeMin = 600 |
---|
| 223 | rangeClosure = co |
---|
| 224 | </Supported> |
---|
| 225 | <Supported> |
---|
| 226 | rangeMin = 750 |
---|
| 227 | rangeMin = 990 |
---|
| 228 | rangeClosure = co |
---|
| 229 | rangeSpacing = 10 |
---|
| 230 | </Supported> |
---|
| 231 | </LiteralData> |
---|
| 232 | |
---|
[206] | 233 | .. _BoundingBoxData: |
---|
| 234 | |
---|
| 235 | BoundingBoxData node |
---|
| 236 | ******************** |
---|
| 237 | |
---|
| 238 | A ``<BoundingBoxData>`` node contains: |
---|
| 239 | |
---|
| 240 | - one ``<Default>`` node with a CRS property defining the default Coordinate Reference Systems (CRS), and |
---|
| 241 | - one or more ``<Supported>`` nodes depending on the number of CRS your service supports (note that you can |
---|
| 242 | alternatively use a single ``<Supported>`` node with a comma-separated list of supported CRS). |
---|
| 243 | |
---|
| 244 | A typical ``<BoundingBoxData>`` node, for two supported CRS (`EPSG:4326 <http://www.epsg-registry.org/indicio/query?request=GetRepositoryItem&id=urn:ogc:def:crs:EPSG::4326>`__ |
---|
| 245 | and `EPSG:3785 <http://www.epsg-registry.org/indicio/query?request=GetRepositoryItem&id=urn:ogc:def:crs:EPSG::3785>`__), |
---|
| 246 | looks like the following: |
---|
| 247 | |
---|
| 248 | .. code-block:: guess |
---|
| 249 | :linenos: |
---|
| 250 | |
---|
| 251 | <BoundingBoxData> |
---|
| 252 | <Default> |
---|
| 253 | CRS = urn:ogc:def:crs:EPSG:6.6:4326 |
---|
| 254 | </Default> |
---|
| 255 | <Supported> |
---|
| 256 | CRS = urn:ogc:def:crs:EPSG:6.6:4326 |
---|
| 257 | </Supported> |
---|
| 258 | <Supported> |
---|
| 259 | CRS = urn:ogc:def:crs:EPSG:6.6:3785 |
---|
| 260 | </Supported> |
---|
| 261 | </BoundingBoxData> |
---|
| 262 | |
---|
| 263 | .. _ComplexData: |
---|
| 264 | |
---|
| 265 | ComplexData node |
---|
| 266 | **************** |
---|
| 267 | |
---|
| 268 | A ComplexData node contains: |
---|
| 269 | |
---|
| 270 | - a ``<Default>`` node and |
---|
| 271 | - one or more ``<Supported>`` nodes depending on the number of supported formats. A format is made up of this |
---|
| 272 | set of properties : ``mimeType``, ``encoding`` and optionaly ``schema``. |
---|
| 273 | |
---|
| 274 | For output ComplexData nodes, you can add the ``extension`` property to define what extension to use to name |
---|
| 275 | the file when storing the result is required. Obviously, you'll have to add the ``extension`` property to each |
---|
| 276 | supported format (for the ``<Default>`` and ``<Supported>`` nodes). |
---|
| 277 | |
---|
| 278 | You can also add the ``asReference`` property to the ``<Default>`` node to define if the output should be |
---|
| 279 | stored on server side per default. |
---|
| 280 | |
---|
| 281 | .. Note:: the client can always modify this behavior by setting ``asReference`` attribute to ``true`` or ``false`` |
---|
| 282 | for this output in the request ``ResponseDocument`` parameter. |
---|
| 283 | |
---|
| 284 | You can see below a sample ComplexData node for default ``application/json`` and ``text/xml`` (encoded in UTF-8 |
---|
| 285 | or base64) mimeTypes support: |
---|
| 286 | |
---|
| 287 | .. code-block:: guess |
---|
| 288 | :linenos: |
---|
| 289 | |
---|
| 290 | <ComplexData> |
---|
| 291 | <Default> |
---|
| 292 | mimeType = application/json |
---|
| 293 | encoding = UTF-8 |
---|
| 294 | </Default> |
---|
| 295 | <Supported> |
---|
| 296 | mimeType = text/xml |
---|
| 297 | encoding = base64 |
---|
| 298 | schema = http://fooa/gml/3.1.0/polygon.xsd |
---|
| 299 | </Supported> |
---|
| 300 | <Supported> |
---|
| 301 | mimeType = text/xml |
---|
| 302 | encoding = UTF-8 |
---|
| 303 | schema = http://fooa/gml/3.1.0/polygon.xsd |
---|
| 304 | </Supported> |
---|
| 305 | </ComplexData> |
---|