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

Last change on this file since 206 was 206, checked in by jmckenna, 13 years ago

add ZCFG Reference doc

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