Index: trunk/docs/services/index.txt =================================================================== --- trunk/docs/services/index.txt (revision 146) +++ trunk/docs/services/index.txt (revision 206) @@ -10,4 +10,5 @@ introduction + zcfg-reference howtos examples Index: trunk/docs/services/introduction.txt =================================================================== --- trunk/docs/services/introduction.txt (revision 146) +++ trunk/docs/services/introduction.txt (revision 206) @@ -4,13 +4,14 @@ ============ -ZOO Services are example Web services which work with the ZOO Kernel. They are based on various -existing Open Source libraries and tend to provide simple Web processing functions such as -GIS format conversion, GIS file reprojection, basic spatial operations, basic raster operations... +ZOO Services are example Web services which work with the ZOO :ref:`Kernel `. +They are based on various existing Open Source libraries and tend to provide simple Web processing +functions such as GIS format conversion, GIS file reprojection, basic spatial operations, +basic raster operations... The available ZOO Services are under development and come without any warranty. They are based -on existing code and prove that the ZOO Kernel works with many different codes and languages -(please have a look to the ZOO demos !). The ZOO Project team wants to encourage people to use -the ZOO Services as a functional basis for Web processing, but above all to provide a source -of inspiration to the community for creating new ZOO Services. +on existing code and prove that the :ref:`ZOO Kernel ` works with many different +codes and languages (please have a look to the ZOO demos!). The ZOO Project team wants to encourage +people to use the ZOO Services as a functional basis for Web processing, but above all to provide a +source of inspiration to the community for creating new ZOO Services. What is a ZOO Service? @@ -22,8 +23,8 @@ - A configuration file (.zcfg) which describes this Web service -Learn more on ZOO services configuration reading the .zcfg Reference +Learn more on configuring ZOO services by reading the :ref:`.zcfg Reference `. Example ZOO Services -------------------- -See ZOO Services examples page +See the ZOO Services :ref:`examples page `. Index: trunk/docs/services/zcfg-reference.txt =================================================================== --- trunk/docs/services/zcfg-reference.txt (revision 206) +++ trunk/docs/services/zcfg-reference.txt (revision 206) @@ -0,0 +1,230 @@ +.. _services-zcfg: + +ZCFG : the ZOO Service Configuration File +========================================= + +.. contents:: Table of Contents + :depth: 3 + :backlinks: top + +The ZOO Service configuration file (.zcfg) describes the service and will be parsed by +the ZOO Kernel. We will describe here what such a file contains. +You can also take a look at the existing examples of ZCFG files in the ``cgi-env`` directory +of each services available in the `ZOO-Project SVN source tree `__. + +A ZOO Configuration file is divided into three distinct sections : + +1. Main Metadata information +2. List of Inputs metadata information +3. List of Outputs metadata information + +.. Note:: The ZOO Service Configuration File is case sensitive. + +Main Metadata Information +------------------------- + +The fist part in a ZOO Configuration file contains the metadata information relative to the service. +Note that the "name of your service" between brackets on the first line has to be the exact same name +as the function you defined in your services provider code. In most cases, this name is also the name +of the ZCFG file without the "``.zcfg``" extension. + +You can see below a description of the main metadata information: + +.. code-block:: guess + :linenos: + + [Name of your service] + Title = Title of your service + Abstract = Description of your service + processVersion = Version number of your service + storeSupported = true/false + statusSupported = true/false + serviceType = the programming language used to implement the service (C/Fortran/Python/Java/PHP/Javascript) + serviceProvider = name of your services provider (shared library/Python Module/Java Class/PHP Script/JavaScript script) + + title = Metadata title of your service + + +List of Inputs +-------------- + +The list of inputs contains metadata information of each supported input, and they are grouped using a ```` node. + +Each input is defined as : + +- a name (between brackets as for the name of the service before) +- various medata properties (``Title``, ``Abstract``, ``minOccurs`` and ``maxOccurs``) +- a Type Of Data node (:ref:`description `) + +A typical list of inputs (````) look like the following: + +.. code-block:: guess + :linenos: + + + [Name of the first input] + Title = Title of the first input + Abstract = Abstract describing the first input + minOccurs = Minimum occurence of the first input + maxOccurs = Maximum occurence of the first input + + [Name of the second input] + Title = Title of the second input + Abstract = Abstract describing the second input + minOccurs = Minimum occurence of the second input + maxOccurs = Maximum occurence of the second input + + + +.. Note:: you can add ```` node as in the main metadata information. + +List of Outputs +--------------- + +The list of outputs is very similar to a list of inputs except it is specified as a ```` node. + +A typical ```` node looks like the following: + +.. code-block:: guess + :linenos: + + + [Name of the output] + Title = Title of the output + Abstract = Description of the output + + + +.. _typeDataNodes: + +Type Of Data Nodes +------------------ + +In the beginning of this ZCFG introduction, we spoke about "Type Of Data Nodes" to describe the data type of inputs and outputs. + +You can define your data as: + +- :ref:`LiteralData ` +- :ref:`BoundingBoxData ` +- :ref:`ComplexData ` + +Except for ``LiteralData``, each *Type Of Data* node must have at least one ```` and one ```` node. Even +if one of those are empty, it **has to be present** with an opening and closing tag on two different lines. So, something +like the following: + +.. code-block:: guess + :linenos: + + + + +Otherwise, ZOO-Kernel won't be able to parse your ZCFG and will fail to process requests. + +.. _LiteralData: + +LiteralData node +**************** + +A ```` node contains: + +- one ```` node, +- zero or more ```` nodes depending on the existence or the number of supported Units Of Measure (UOM), and +- a ``dataType`` property. The ``dataType`` property defines the type of literal data, such as a string, an interger and so on + (consult `the complete list `__ of supported data types). + +```` and ```` nodes can contain the ``uom`` property to define which UOM has to be used for +this input value. + +For input ```` nodes, you can add the ``value`` property to the ```` node to define a default +value for this input. This means that, when your Service will be run, even if the input wasn't defined, this default +value will be set as the current value for this input. + +A typical ```` node, defining a ``float`` data type using meters or degrees for its UOM, looks like the +following: + +.. code-block:: guess + :linenos: + + + dataType = float + + uom = meters + + + uom = feet + + + +.. _BoundingBoxData: + +BoundingBoxData node +******************** + +A ```` node contains: + +- one ```` node with a CRS property defining the default Coordinate Reference Systems (CRS), and +- one or more ```` nodes depending on the number of CRS your service supports (note that you can + alternatively use a single ```` node with a comma-separated list of supported CRS). + +A typical ```` node, for two supported CRS (`EPSG:4326 `__ +and `EPSG:3785 `__), +looks like the following: + +.. code-block:: guess + :linenos: + + + + CRS = urn:ogc:def:crs:EPSG:6.6:4326 + + + CRS = urn:ogc:def:crs:EPSG:6.6:4326 + + + CRS = urn:ogc:def:crs:EPSG:6.6:3785 + + + +.. _ComplexData: + +ComplexData node +**************** + +A ComplexData node contains: + +- a ```` node and +- one or more ```` nodes depending on the number of supported formats. A format is made up of this + set of properties : ``mimeType``, ``encoding`` and optionaly ``schema``. + +For output ComplexData nodes, you can add the ``extension`` property to define what extension to use to name +the file when storing the result is required. Obviously, you'll have to add the ``extension`` property to each +supported format (for the ```` and ```` nodes). + +You can also add the ``asReference`` property to the ```` node to define if the output should be +stored on server side per default. + +.. Note:: the client can always modify this behavior by setting ``asReference`` attribute to ``true`` or ``false`` + for this output in the request ``ResponseDocument`` parameter. + +You can see below a sample ComplexData node for default ``application/json`` and ``text/xml`` (encoded in UTF-8 +or base64) mimeTypes support: + +.. code-block:: guess + :linenos: + + + + mimeType = application/json + encoding = UTF-8 + + + mimeType = text/xml + encoding = base64 + schema = http://fooa/gml/3.1.0/polygon.xsd + + + mimeType = text/xml + encoding = UTF-8 + schema = http://fooa/gml/3.1.0/polygon.xsd + +