source: branches/branch-1.7/docs/services/zcfg-reference.rst @ 967

Last change on this file since 967 was 942, checked in by djay, 5 years ago

Tag the 1.7.0 release.

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

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png