source: branches/PublicaMundi_David_integration_01-devel/docs/services/zcfg-reference.txt @ 935

Last change on this file since 935 was 607, checked in by djay, 10 years ago

Introduce the Process Profiles Registry with its documentation.

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