source: branches/branch-1.4/docs/services/zcfg-reference.txt @ 873

Last change on this file since 873 was 529, checked in by djay, 10 years ago

Fix link isue reported by Andrea

  • Property svn:keywords set to HeadURL Date Author Id Rev
  • Property svn:mime-type set to text/plain
File size: 10.2 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: 2014-11-05 12:29:01 +0000 (Wed, 05 Nov 2014) $
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
51List of Inputs
52--------------
53
54The list of inputs contains metadata information of each supported input, and they are grouped using a ``<DataInputs>`` node.
55
56Each 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``, ``maxOccurs`` and, in case of ComplexData, the optional ``maximumMegabytes``)
60- a Type Of Data node (:ref:`description <typeDataNodes>`)
61
62A typical list of inputs (``<DataInputs>``) look like the following:
63
64.. code-block:: none
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
84List of Outputs
85---------------
86
87The list of outputs is very similar to a list of inputs except it is specified as a ``<DataOutputs>`` node.
88
89A typical ``<DataOutputs>`` node looks like the following:
90
91.. code-block:: none
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
103Type Of Data Nodes
104------------------
105
106In the beginning of this ZCFG introduction, we spoke about "Type Of Data Nodes" to describe the data type of inputs and outputs.
107
108You can define your data as:
109
110- :ref:`LiteralData <LiteralData>`
111- :ref:`BoundingBoxData <BoundingBoxData>`
112- :ref:`ComplexData <ComplexData>`
113
114Except for ``LiteralData``, each *Type Of Data* node must have at least one ``<Default>`` node. Even
115if empty, it **has to be present**. So, something
116like the following should be present in your ZCFG file:
117
118.. code-block:: guess
119   :linenos:
120
121   <Default />
122
123Otherwise, ZOO-Kernel won't be able to parse your ZCFG correctly.
124
125.. _LiteralData:
126
127LiteralData node
128****************
129
130A ``<LiteralData>`` node contains:
131
132- one (optional) ``AllowedValues`` key containing all value allowed for this input
133- one (optional) ``range`` properties containing the range (``[``, ``]``)
134- one (optional) ``rangeMin`` (``rangeMax``) properties containing the minimum (maximum) value of this range
135- one (optional) ``rangeSpacing`` properties containing the regular distance or spacing between value in this range
136- one (optional) ``rangeClosure`` properties containing the closure type (``c``, ``o``, ``oc``, ``co``)
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
143this input value.
144
145For input ``<LiteralData>`` nodes, you can add the ``value`` property to the ``<Default>`` node to define a default
146value for this input. This means that, when your Service will be run, even if the input wasn't defined, this default
147value will be set as the current value for this input.
148
149A typical ``<LiteralData>`` node, defining a ``float`` data type using meters or degrees for its UOM, looks like the
150following:
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
165
166A typical ``<LiteralData>`` node, defining a ``float`` data type which
167should take values contained in ``[0.0,100.0]``, looks like the following:
168
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
180Or 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
191A typical ``<LiteralData>`` node, defining a ``string`` data type which
192support values ``hillshade``, ``slope``, ``aspect``, ``TRI``, ``TPI``
193and ``roughness``, looks like the following:
194
195.. code-block:: guess
196   :linenos:
197   
198   <LiteralData>
199     dataType = string
200     AllowedValues = hillshade,slope,aspect,TRI,TPI,roughness
201     <Default />
202   </LiteralData>
203
204Properties ``AllowedValues`` and ``range*`` can be conbined with both ``<Default>`` and
205``<Supported>`` nodes in the same was as ``<LiteralData>`` node. For
206instance, the following is supported:
207
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
233.. _BoundingBoxData:
234
235BoundingBoxData node
236********************
237
238A ``<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
244A 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>`__
245and `EPSG:3785 <http://www.epsg-registry.org/indicio/query?request=GetRepositoryItem&id=urn:ogc:def:crs:EPSG::3785>`__),
246looks 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
265ComplexData node
266****************
267
268A 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
274For output ComplexData nodes, you can add the ``extension`` property to define what extension to use to name
275the file when storing the result is required. Obviously, you'll have to add the ``extension`` property to each
276supported format (for the ``<Default>`` and ``<Supported>`` nodes).
277
278You can also add the ``asReference`` property to the ``<Default>`` node to define if the output should be
279stored 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
284You can see below a sample ComplexData node for default ``application/json`` and ``text/xml`` (encoded in UTF-8
285or 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>
Note: See TracBrowser for help on using the repository browser.

Search

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