source: trunk/docs/services/zcfg-reference.txt @ 313

Last change on this file since 313 was 272, checked in by nbozon, 13 years ago

add keywords with svn propset

  • Property svn:keywords set to HeadURL Date Author Id Rev
File size: 8.1 KB
Line 
1.. _services-zcfg:
2   
3ZCFG : the ZOO Service Configuration File
4========================================= 
5
6:Last Updated: $Date: 2011-07-16 13:26:31 +0000 (Sat, 16 Jul 2011) $
7:Id:    $Id: zcfg-reference.txt 272 2011-07-16 13:26:31Z jmckenna $
8:Author: $Author: jmckenna $
9:HeadURL: $HeadURL: trunk/docs/services/zcfg-reference.txt $ 
10
11.. contents:: Table of Contents
12    :depth: 3
13    :backlinks: top
14
15The ZOO Service configuration file (.zcfg) describes the service and will be parsed by
16the ZOO Kernel. We will describe here what such a file contains.
17You can also take a look at the existing examples of ZCFG files in the ``cgi-env`` directory
18of each services available in the `ZOO-Project SVN source tree <http://zoo-project.org/trac/browser/trunk/zoo-services>`__.
19
20A ZOO Configuration file is divided into three distinct sections :
21
221. Main Metadata information
232. List of Inputs metadata information
243. List of Outputs metadata information
25
26.. Note:: The ZOO Service Configuration File is case sensitive.
27
28Main Metadata Information
29-------------------------
30
31The fist part in a ZOO Configuration file contains the metadata information relative to the service.
32Note that the "name of your service" between brackets on the first line has to be the exact same name
33as the function you defined in your services provider code. In most cases, this name is also the name
34of the ZCFG file without the "``.zcfg``" extension.
35
36You can see below a description of the main metadata information:
37
38.. code-block:: none
39   :linenos:
40
41   [Name of your service]
42   Title = Title of your service
43   Abstract = Description of your service
44   processVersion = Version number of your service
45   storeSupported = true/false
46   statusSupported = true/false
47   serviceType = the programming language used to implement the service (C/Fortran/Python/Java/PHP/Javascript)
48   serviceProvider = name of your services provider (shared library/Python Module/Java Class/PHP Script/JavaScript script)
49   <MetaData>
50     title = Metadata title of your service
51   </MetaData>
52
53List of Inputs
54--------------
55
56The list of inputs contains metadata information of each supported input, and they are grouped using a ``<DataInputs>`` node.
57
58Each input is defined as :
59
60-  a name (between brackets as for the name of the service before)
61- various medata properties (``Title``, ``Abstract``, ``minOccurs`` and ``maxOccurs``)
62- a Type Of Data node (:ref:`description <typeDataNodes>`)
63
64A typical list of inputs (``<DataInputs>``) look like the following:
65
66.. code-block:: none
67   :linenos:
68   
69   <DataInputs>
70     [Name of the first input]
71       Title = Title of the first input
72       Abstract = Abstract describing the first input
73       minOccurs = Minimum occurence of the first input
74       maxOccurs = Maximum occurence of the first input
75       <Type Of Data Node />
76     [Name of the second input]
77       Title = Title of the second input
78       Abstract = Abstract describing the second input
79       minOccurs = Minimum occurence of the second input
80       maxOccurs = Maximum occurence of the second input
81       <Type Of Data Node />
82   </DataInputs>
83   
84.. Note:: you can add ``<MetaData>`` node as in the main metadata information.
85
86List of Outputs
87---------------
88
89The list of outputs is very similar to a list of inputs except it is specified as a ``<DataOutputs>`` node.
90
91A typical ``<DataOutputs>`` node looks like the following:
92
93.. code-block:: none
94   :linenos:
95   
96   <DataOutputs>
97     [Name of the output]
98       Title = Title of the output
99       Abstract = Description of the output
100       <Type Of Data Node />
101   </DataOutputs>
102
103.. _typeDataNodes:
104
105Type Of Data Nodes
106------------------
107
108In the beginning of this ZCFG introduction, we spoke about "Type Of Data Nodes" to describe the data type of inputs and outputs.
109
110You can define your data as:
111
112- :ref:`LiteralData <LiteralData>`
113- :ref:`BoundingBoxData <BoundingBoxData>`
114- :ref:`ComplexData <ComplexData>`
115
116Except for ``LiteralData``, each *Type Of Data* node must have at least one ``<Default>`` and one ``<Supported>`` node. Even
117if one of those are empty, it **has to be present** with an opening and closing tag on two different lines. So, something
118like the following:
119
120.. code-block:: guess
121   :linenos:
122
123   <Default>
124   </Default>
125
126Otherwise, ZOO-Kernel won't be able to parse your ZCFG and will fail to process requests.
127
128.. _LiteralData:
129
130LiteralData node
131****************
132
133A ``<LiteralData>`` node contains:
134
135- one ``<Default>`` node,
136- zero or more ``<Supported>`` nodes depending on the existence or the number of supported Units Of Measure (UOM), and
137- a ``dataType`` property. The ``dataType`` property defines the type of literal data, such as a string, an interger and so on
138  (consult `the complete list <http://www.w3.org/TR/xmlschema-2/#built-in-datatypes>`__ of supported data types).
139
140``<Default>`` and ``<Supported>`` nodes can contain the ``uom`` property to define which UOM has to be used for
141this input value.
142
143For input ``<LiteralData>`` nodes, you can add the ``value`` property to the ``<Default>`` node to define a default
144value for this input. This means that, when your Service will be run, even if the input wasn't defined, this default
145value will be set as the current value for this input.
146
147A typical ``<LiteralData>`` node, defining a ``float`` data type using meters or degrees for its UOM, looks like the
148following:
149
150.. code-block:: guess
151   :linenos:
152   
153   <LiteralData>
154     dataType = float
155     <Default>
156       uom = meters
157     </Default>
158     <Supported>
159       uom = feet
160     </Supported>
161   </LiteralData>
162
163.. _BoundingBoxData:
164
165BoundingBoxData node
166********************
167
168A ``<BoundingBoxData>`` node contains:
169
170- one ``<Default>`` node with a CRS property defining the default Coordinate Reference Systems (CRS), and
171- one or more ``<Supported>`` nodes depending on the number of CRS your service supports (note that you can
172  alternatively use a single ``<Supported>`` node with a comma-separated list of supported CRS).
173
174A 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>`__
175and `EPSG:3785 <http://www.epsg-registry.org/indicio/query?request=GetRepositoryItem&id=urn:ogc:def:crs:EPSG::3785>`__),
176looks like the following:
177
178.. code-block:: guess
179   :linenos:
180   
181   <BoundingBoxData>
182     <Default>
183       CRS = urn:ogc:def:crs:EPSG:6.6:4326
184     </Default>
185     <Supported>
186       CRS = urn:ogc:def:crs:EPSG:6.6:4326
187     </Supported>
188     <Supported>
189       CRS = urn:ogc:def:crs:EPSG:6.6:3785
190     </Supported>
191   </BoundingBoxData>
192
193.. _ComplexData:
194
195ComplexData node
196****************
197
198A ComplexData node contains:
199
200- a ``<Default>`` node and
201- one or more ``<Supported>`` nodes depending on the number of supported formats. A format is made up of this
202  set of properties : ``mimeType``, ``encoding`` and optionaly ``schema``.
203
204For output ComplexData nodes, you can add the ``extension`` property to define what extension to use to name
205the file when storing the result is required. Obviously, you'll have to add the ``extension`` property to each
206supported format (for the ``<Default>`` and ``<Supported>`` nodes).
207
208You can also add the ``asReference`` property to the ``<Default>`` node to define if the output should be
209stored on server side per default.
210
211.. Note:: the client can always modify this behavior by setting ``asReference`` attribute to ``true`` or ``false``
212          for this output in the request ``ResponseDocument`` parameter.
213
214You can see below a sample ComplexData node for default ``application/json`` and ``text/xml`` (encoded in UTF-8
215or base64) mimeTypes support:
216
217.. code-block:: guess
218   :linenos:
219   
220   <ComplexData>
221     <Default>
222       mimeType = application/json
223       encoding = UTF-8
224     </Default>
225     <Supported>
226       mimeType = text/xml
227       encoding = base64
228       schema = http://fooa/gml/3.1.0/polygon.xsd
229     </Supported>
230     <Supported>
231       mimeType = text/xml
232       encoding = UTF-8
233       schema = http://fooa/gml/3.1.0/polygon.xsd
234     </Supported>
235   </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