source: branches/PublicaMundi_David-devel/docs/_build/html/workshop/2014/first_service.html @ 659

Last change on this file since 659 was 659, checked in by nbozon, 9 years ago

Massive update of zoo docs
File size: 39.2 KB
Line 
1
2
3<!DOCTYPE html>
4<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
5<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
6<head>
7  <meta charset="utf-8">
8  <meta name="viewport" content="width=device-width, initial-scale=1.0">
9 
10  <title>Creating your first ZOO Service &mdash; ZOO-Project 1.4a0 documentation</title>
11 
12  <link href="http://fonts.googleapis.com/css?family=Days+One" rel="stylesheet" type="text/css">
13 
14 
15
16 
17
18 
19 
20   
21      <link rel="search" type="application/opensearchdescription+xml" title="Search within ZOO-Project 1.4a0 documentation" href="../../_static/opensearch.xml"/>
22   
23
24 
25
26 
27 
28    <link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
29 
30
31 
32
33 
34    <link rel="top" title="ZOO-Project 1.4a0 documentation" href="../../index.html"/> 
35
36 
37  <script src="_static/js/modernizr.min.js"></script>
38
39</head>
40
41<body class="wy-body-for-nav" role="document">
42
43  <div class="wy-grid-for-nav">
44
45   
46    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
47      <div class="wy-side-nav-search">
48       
49
50       
51          <a class="shrink" href="../../contents.html"><img src="http://zoo-project.org/img/zoo-sun-logo.png" class="img-responsive sun" style="display: inline;"> ZOO</a>
52       
53
54       
55        </a>
56
57       
58<div role="search">
59  <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
60    <input type="text" name="q" placeholder="Search docs" />
61    <input type="hidden" name="check_keywords" value="yes" />
62    <input type="hidden" name="area" value="default" />
63  </form>
64</div>
65
66       
67      </div>
68
69      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
70       
71         
72         
73              <ul>
74<li class="toctree-l1"><a class="reference internal" href="../../intro.html">Introduction</a><ul>
75<li class="toctree-l2"><a class="reference internal" href="../../intro.html#what-is-zoo-project">What is ZOO-Project ?</a></li>
76<li class="toctree-l2"><a class="reference internal" href="../../intro.html#zoo-project-components">ZOO-Project components</a></li>
77<li class="toctree-l2"><a class="reference internal" href="../../intro.html#open-source">Open Source</a></li>
78</ul>
79</li>
80<li class="toctree-l1"><a class="reference internal" href="../../install/index.html">ZOO-Project installation</a><ul>
81<li class="toctree-l2"><a class="reference internal" href="../../install/install-prerequisites.html">Prerequisites</a></li>
82<li class="toctree-l2"><a class="reference internal" href="../../install/install-download.html">Download</a></li>
83<li class="toctree-l2"><a class="reference internal" href="../../install/install-confoptions.html">Configuration options</a></li>
84<li class="toctree-l2"><a class="reference internal" href="../../install/install-installation.html">Installation on Unix/Linux</a></li>
85<li class="toctree-l2"><a class="reference internal" href="../../install/install-installation.html#installation-on-mac-osx">Installation on Mac OSX</a></li>
86<li class="toctree-l2"><a class="reference internal" href="../../install/install-installation.html#installation-on-windows">Installation on Windows</a></li>
87</ul>
88</li>
89<li class="toctree-l1"><a class="reference internal" href="../../kernel/index.html">ZOO-Kernel</a><ul>
90<li class="toctree-l2"><a class="reference internal" href="../../kernel/what.html">What is ZOO-Kernel ?</a></li>
91<li class="toctree-l2"><a class="reference internal" href="../../kernel/configuration.html">ZOO-Kernel configuration</a></li>
92<li class="toctree-l2"><a class="reference internal" href="../../kernel/mapserver.html">Optional MapServer support</a></li>
93<li class="toctree-l2"><a class="reference internal" href="../../kernel/orfeotoolbox.html">Optional Orfeo Toolbox support</a></li>
94</ul>
95</li>
96<li class="toctree-l1"><a class="reference internal" href="../../services/index.html">ZOO-Services</a><ul>
97<li class="toctree-l2"><a class="reference internal" href="../../services/introduction.html">What are ZOO-Services ?</a></li>
98<li class="toctree-l2"><a class="reference internal" href="../../services/zcfg-reference.html">ZOO-Service configuration file</a></li>
99<li class="toctree-l2"><a class="reference internal" href="../../services/process-profiles.html">Process profiles registry</a></li>
100<li class="toctree-l2"><a class="reference internal" href="../../services/howtos.html">Create your own ZOO-Services</a></li>
101<li class="toctree-l2"><a class="reference internal" href="../../services/status.html">ZOO Status Service</a></li>
102<li class="toctree-l2"><a class="reference internal" href="../../services/debug.html">How To Debug ZOO Services</a></li>
103<li class="toctree-l2"><a class="reference internal" href="../../services/zoo-services.html">Available ZOO-Services</a></li>
104</ul>
105</li>
106<li class="toctree-l1"><a class="reference internal" href="../../api/index.html">ZOO-API</a><ul>
107<li class="toctree-l2"><a class="reference internal" href="../../api/what.html">What is ZOO-API ?</a></li>
108<li class="toctree-l2"><a class="reference internal" href="../../api/howto.html">Using ZOO-API</a></li>
109<li class="toctree-l2"><a class="reference internal" href="../../api/classes.html">ZOO-API Classes</a></li>
110<li class="toctree-l2"><a class="reference internal" href="../../api/examples.html">Examples</a></li>
111</ul>
112</li>
113<li class="toctree-l1"><a class="reference internal" href="../../client/index.html">ZOO-Client</a><ul>
114<li class="toctree-l2"><a class="reference internal" href="../../client/what.html">What is ZOO-Client ?</a></li>
115<li class="toctree-l2"><a class="reference internal" href="../../client/howto.html">Using ZOO-Client</a></li>
116<li class="toctree-l2"><a class="reference internal" href="../../client/example.html">Example application</a></li>
117</ul>
118</li>
119</ul>
120
121         
122       
123      </div>
124      &nbsp;
125    </nav>
126
127    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
128
129     
130      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
131        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
132        <a href="../../contents.html">ZOO-Project</a>
133      </nav>
134
135
136     
137      <div class="wy-nav-content">
138        <div class="rst-content">
139          <div role="navigation" aria-label="breadcrumbs navigation">
140  <ul class="wy-breadcrumbs">
141
142    <li><a href="../../contents.html"> Docs</a> &#8725; &#160;</li>
143     
144    <li>Creating your first ZOO Service</li>
145      <li class="wy-breadcrumbs-aside">
146       
147          <a href="../../_sources/workshop/2014/first_service.txt" rel="nofollow"> View page source</a>
148       
149      </li>
150  </ul>
151  <hr/>
152</div>
153          <div role="main" class="document">
154           
155  <div class="section" id="creating-your-first-zoo-service">
156<span id="first-service"></span><h1><a class="toc-backref" href="#table-of-contents">Creating your first ZOO Service</a><a class="headerlink" href="#creating-your-first-zoo-service" title="Permalink to this headline"></a></h1>
157<div class="contents topic" id="table-of-contents">
158<p class="topic-title first">Table of Contents</p>
159<ul class="simple">
160<li><a class="reference internal" href="#creating-your-first-zoo-service" id="id5">Creating your first ZOO Service</a><ul>
161<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li>
162<li><a class="reference internal" href="#service-and-publication-process-overview" id="id7">Service and publication process overview</a></li>
163<li><a class="reference internal" href="#creating-your-first-zcfg-file" id="id8">Creating your first ZCFG file</a></li>
164<li><a class="reference internal" href="#test-requests" id="id9">Test requests</a><ul>
165<li><a class="reference internal" href="#test-the-getcapabilities-request" id="id10">Test the GetCapabilities request</a></li>
166<li><a class="reference internal" href="#test-the-describeprocess-request" id="id11">Test the DescribeProcess request</a></li>
167<li><a class="reference internal" href="#test-the-execute-request" id="id12">Test the Execute request</a></li>
168</ul>
169</li>
170<li><a class="reference internal" href="#implementing-the-python-service" id="id13">Implementing the Python Service</a><ul>
171<li><a class="reference internal" href="#general-principles" id="id14">General Principles</a></li>
172<li><a class="reference internal" href="#the-hello-service" id="id15">The Hello Service</a></li>
173</ul>
174</li>
175<li><a class="reference internal" href="#interracting-with-your-service-using-execute-requests" id="id16">Interracting with your service using Execute requests</a></li>
176<li><a class="reference internal" href="#conclusion" id="id17">Conclusion</a></li>
177</ul>
178</li>
179</ul>
180</div>
181<div class="section" id="introduction">
182<h2><a class="toc-backref" href="#table-of-contents">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
183<p>In this part, you will create and publish a simple ZOO-Service named <code class="docutils literal"><span class="pre">Hello</span></code> which
184will simply return a hello message containing the input value provided. It will be usefull
185to present in deeper details general concept on how ZOO-Kernel works and handles
186Execute requests.</p>
187</div>
188<div class="section" id="service-and-publication-process-overview">
189<h2><a class="toc-backref" href="#table-of-contents">Service and publication process overview</a><a class="headerlink" href="#service-and-publication-process-overview" title="Permalink to this headline"></a></h2>
190<p>Before starting developing a ZOO Service, you should remember that in
191ZOO-Project, a Service is a couple made of:</p>
192<blockquote>
193<div><ul class="simple">
194<li>a metadata file: a ZOO Service Configuration File (ZCFG) containing metadata
195informations about a Service (providing informations about default / supported
196inputs and outputs for a Service)</li>
197<li>a Services Provider: it depends on the programming language used, but for Python it
198is a module and for JavaScript a script file.</li>
199</ul>
200</div></blockquote>
201<p>To publish your Service, which means make your ZOO Kernel aware of its presence,
202you should copy a ZCFG file in the directory where <code class="docutils literal"><span class="pre">zoo_loader.cgi</span></code> is located (in this workshop, <code class="docutils literal"><span class="pre">/usr/lib/cgi-bin</span></code>) or in any subdirectory.</p>
203<div class="admonition warning">
204<p class="first admonition-title">Warning</p>
205<p class="last">only the ZCFG file is required  for the Service to be considerate as
206available. So if you don&#8217;t get the Service Provider, obviously your Execute
207request will fail as we will discuss later.</p>
208</div>
209<p>Before publication, you should store your ongoing work, so you&#8217;ll start by
210creating a directory to store the files of your Services Provider:</p>
211<div class="highlight-none"><div class="highlight"><pre>mkdir -p /home/user/zoo-ws/ws_sp/cgi-env
212</pre></div>
213</div>
214<p>Once the ZCFG and the Python module are both ready, you can publish simply
215by copying the corresponding files in the same directory as the ZOO-Kernel.</p>
216</div>
217<div class="section" id="creating-your-first-zcfg-file">
218<h2><a class="toc-backref" href="#table-of-contents">Creating your first ZCFG file</a><a class="headerlink" href="#creating-your-first-zcfg-file" title="Permalink to this headline"></a></h2>
219<p>You will start by creating the ZCFG file for the <code class="docutils literal"><span class="pre">Hello</span></code> Service. Edit the
220<code class="docutils literal"><span class="pre">/home/user/zoo-ws/ws_sp/cgi-env/Hello.zcfg</span></code> file
221and add the following content:</p>
222<div class="highlight-none"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
223 2
224 3
225 4
226 5
227 6
228 7
229 8
230 9
23110
23211
23312
23413
23514
23615
23716
23817
23918
24019
24120
24221
24322
24423
24524
24625
24726
24827
24928</pre></div></td><td class="code"><div class="highlight"><pre>[Hello]
250 Title = Return a hello message.
251 Abstract = Create a welcome string.
252 processVersion = 2
253 storeSupported = true
254 statusSupported = true
255 serviceProvider = test_service
256 serviceType = Python
257 &lt;DataInputs&gt;
258  [name]
259   Title = Input string
260   Abstract = The string to insert in the hello message.
261   minOccurs = 1
262   maxOccurs = 1
263   &lt;LiteralData&gt;
264       dataType = string
265       &lt;Default /&gt;
266   &lt;/LiteralData&gt;
267 &lt;/DataInputs&gt;
268 &lt;DataOutputs&gt;
269  [Result]
270   Title = The resulting string
271   Abstract = The hello message containing the input string
272   &lt;LiteralData&gt;
273       dataType = string
274       &lt;Default /&gt;
275   &lt;/LiteralData&gt;
276 &lt;/DataOutputs&gt;
277</pre></div>
278</td></tr></table></div>
279<div class="admonition note">
280<p class="first admonition-title">Note</p>
281<p class="last">the name of the ZCFG file and the name between braket (here <code class="docutils literal"><span class="pre">[Hello]</span></code>)
282should be the same and correspond to the function name you will define in your
283Services provider.</p>
284</div>
285<p>As you can see in the ZOO Service Configuration File presented above it is divided into
286three distinct sections:</p>
287<blockquote>
288<div><ol class="arabic simple">
289<li>Main Metadata information (from line 2 to 8)</li>
290<li>List of Inputs metadata information (from 9 line to 19)</li>
291<li>List of Outputs metadata information (from line 20 to 28)</li>
292</ol>
293</div></blockquote>
294<p>You can get more informations about ZCFG from <a class="reference external" href="http://zoo-project.org/docs/services/zcfg-reference.html">the reference documentation</a>.</p>
295<p>If you copy the <code class="docutils literal"><span class="pre">Hello.zcfg</span></code> file in the same directory as your ZOO Kernel
296then you will be able to request for DescribeProcess using the <code class="docutils literal"><span class="pre">Hello</span></code>
297<code class="docutils literal"><span class="pre">Identifier</span></code>. The <code class="docutils literal"><span class="pre">Hello</span></code> service should also be listed from Capabilities
298document.</p>
299</div>
300<div class="section" id="test-requests">
301<h2><a class="toc-backref" href="#table-of-contents">Test requests</a><a class="headerlink" href="#test-requests" title="Permalink to this headline"></a></h2>
302<p>In this section you will tests each WPS requests : GetCapabilities,
303DescribeProcess and Execute. Note that only GetCapabilities and DescribeProcess
304should work at this step.</p>
305<div class="section" id="test-the-getcapabilities-request">
306<h3><a class="toc-backref" href="#table-of-contents">Test the GetCapabilities request</a><a class="headerlink" href="#test-the-getcapabilities-request" title="Permalink to this headline"></a></h3>
307<p>If you run the <code class="docutils literal"><span class="pre">GetCapabilities</span></code> request:</p>
308<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=GetCapabilities&amp;service=WPS
309</pre></div>
310</div>
311<p>Now, you should find your Hello Service in a <code class="docutils literal"><span class="pre">Process</span></code> node in
312<code class="docutils literal"><span class="pre">ProcessOfferings</span></code>:</p>
313<div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;wps:Process</span> <span class="na">wps:processVersion=</span><span class="s">&quot;2&quot;</span><span class="nt">&gt;</span>
314 <span class="nt">&lt;ows:Identifier&gt;</span>Hello<span class="nt">&lt;/ows:Identifier&gt;</span>
315 <span class="nt">&lt;ows:Title&gt;</span>Return a hello message.<span class="nt">&lt;/ows:Title&gt;</span>
316 <span class="nt">&lt;ows:Abstract&gt;</span>Create a welcome string.<span class="nt">&lt;/ows:Abstract&gt;</span>
317<span class="nt">&lt;/wps:Process&gt;</span>
318</pre></div>
319</div>
320</div>
321<div class="section" id="test-the-describeprocess-request">
322<h3><a class="toc-backref" href="#table-of-contents">Test the DescribeProcess request</a><a class="headerlink" href="#test-the-describeprocess-request" title="Permalink to this headline"></a></h3>
323<p>You can access the <code class="docutils literal"><span class="pre">ProcessDescription</span></code> of the <code class="docutils literal"><span class="pre">Hello</span></code> service using the
324following <code class="docutils literal"><span class="pre">DescribeProcess</span></code> request:</p>
325<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=DescribeProcess&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello
326</pre></div>
327</div>
328<p>You should get the following response:</p>
329<div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;wps:ProcessDescriptions</span> <span class="na">xmlns:ows=</span><span class="s">&quot;http://www.opengis.net/ows/1.1&quot;</span> <span class="na">xmlns:wps=</span><span class="s">&quot;http://www.opengis.net/wps/1.0.0&quot;</span> <span class="na">xmlns:xlink=</span><span class="s">&quot;http://www.w3.org/1999/xlink&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.opengis.net/wps/1.0.0 http://schemas.opengis.net/wps/1.0.0/wpsDescribeProcess_response.xsd&quot;</span> <span class="na">service=</span><span class="s">&quot;WPS&quot;</span> <span class="na">version=</span><span class="s">&quot;1.0.0&quot;</span> <span class="na">xml:lang=</span><span class="s">&quot;en-US&quot;</span><span class="nt">&gt;</span>
330  <span class="nt">&lt;ProcessDescription</span> <span class="na">wps:processVersion=</span><span class="s">&quot;2&quot;</span> <span class="na">storeSupported=</span><span class="s">&quot;true&quot;</span> <span class="na">statusSupported=</span><span class="s">&quot;true&quot;</span><span class="nt">&gt;</span>
331    <span class="nt">&lt;ows:Identifier&gt;</span>Hello<span class="nt">&lt;/ows:Identifier&gt;</span>
332    <span class="nt">&lt;ows:Title&gt;</span>Return a hello message.<span class="nt">&lt;/ows:Title&gt;</span>
333    <span class="nt">&lt;ows:Abstract&gt;</span>Create a welcome string.<span class="nt">&lt;/ows:Abstract&gt;</span>
334    <span class="nt">&lt;DataInputs&gt;</span>
335      <span class="nt">&lt;Input</span> <span class="na">minOccurs=</span><span class="s">&quot;1&quot;</span> <span class="na">maxOccurs=</span><span class="s">&quot;1&quot;</span><span class="nt">&gt;</span>
336        <span class="nt">&lt;ows:Identifier&gt;</span>name<span class="nt">&lt;/ows:Identifier&gt;</span>
337        <span class="nt">&lt;ows:Title&gt;</span>Input string<span class="nt">&lt;/ows:Title&gt;</span>
338        <span class="nt">&lt;ows:Abstract&gt;</span>The string to insert in the hello message.<span class="nt">&lt;/ows:Abstract&gt;</span>
339        <span class="nt">&lt;LiteralData&gt;</span>
340          <span class="nt">&lt;ows:DataType</span> <span class="na">ows:reference=</span><span class="s">&quot;http://www.w3.org/TR/xmlschema-2/#string&quot;</span><span class="nt">&gt;</span>string<span class="nt">&lt;/ows:DataType&gt;</span>
341          <span class="nt">&lt;ows:AnyValue/&gt;</span>
342        <span class="nt">&lt;/LiteralData&gt;</span>
343      <span class="nt">&lt;/Input&gt;</span>
344    <span class="nt">&lt;/DataInputs&gt;</span>
345    <span class="nt">&lt;ProcessOutputs&gt;</span>
346      <span class="nt">&lt;Output&gt;</span>
347        <span class="nt">&lt;ows:Identifier&gt;</span>Result<span class="nt">&lt;/ows:Identifier&gt;</span>
348        <span class="nt">&lt;ows:Title&gt;</span>The resulting string<span class="nt">&lt;/ows:Title&gt;</span>
349        <span class="nt">&lt;ows:Abstract&gt;</span>The hello message containing the input string<span class="nt">&lt;/ows:Abstract&gt;</span>
350        <span class="nt">&lt;LiteralOutput&gt;</span>
351          <span class="nt">&lt;ows:DataType</span> <span class="na">ows:reference=</span><span class="s">&quot;http://www.w3.org/TR/xmlschema-2/#string&quot;</span><span class="nt">&gt;</span>string<span class="nt">&lt;/ows:DataType&gt;</span>
352        <span class="nt">&lt;/LiteralOutput&gt;</span>
353      <span class="nt">&lt;/Output&gt;</span>
354    <span class="nt">&lt;/ProcessOutputs&gt;</span>
355  <span class="nt">&lt;/ProcessDescription&gt;</span>
356<span class="nt">&lt;/wps:ProcessDescriptions&gt;</span>
357</pre></div>
358</div>
359</div>
360<div class="section" id="test-the-execute-request">
361<h3><a class="toc-backref" href="#table-of-contents">Test the Execute request</a><a class="headerlink" href="#test-the-execute-request" title="Permalink to this headline"></a></h3>
362<p>Obviously, you cannot run your Service because the Python file was not published
363yet. If you try the following <code class="docutils literal"><span class="pre">Execute</span></code> request:</p>
364<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto
365</pre></div>
366</div>
367<p>You should get an ExceptionReport similar to the one provided in the following,
368which is normal behavior:</p>
369<div class="highlight-xml"><div class="highlight"><pre><span class="nt">&lt;ows:ExceptionReport</span> <span class="na">xmlns:ows=</span><span class="s">&quot;http://www.opengis.net/ows/1.1&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xmlns:xlink=</span><span class="s">&quot;http://www.w3.org/1999/xlink&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.opengis.net/ows/1.1 http://schemas.opengis.net/ows/1.1.0/owsExceptionReport.xsd&quot;</span> <span class="na">xml:lang=</span><span class="s">&quot;en-US&quot;</span> <span class="na">version=</span><span class="s">&quot;1.1.0&quot;</span><span class="nt">&gt;</span>
370  <span class="nt">&lt;ows:Exception</span> <span class="na">exceptionCode=</span><span class="s">&quot;NoApplicableCode&quot;</span><span class="nt">&gt;</span>
371    <span class="nt">&lt;ows:ExceptionText&gt;</span>Python module test_service cannot be loaded.<span class="nt">&lt;/ows:ExceptionText&gt;</span>
372  <span class="nt">&lt;/ows:Exception&gt;</span>
373<span class="nt">&lt;/ows:ExceptionReport&gt;</span>
374</pre></div>
375</div>
376</div>
377</div>
378<div class="section" id="implementing-the-python-service">
379<h2><a class="toc-backref" href="#table-of-contents">Implementing the Python Service</a><a class="headerlink" href="#implementing-the-python-service" title="Permalink to this headline"></a></h2>
380<div class="section" id="general-principles">
381<h3><a class="toc-backref" href="#table-of-contents">General Principles</a><a class="headerlink" href="#general-principles" title="Permalink to this headline"></a></h3>
382<p>The most important thing you must know when implementing a new ZOO-Services
383using the Python language is that the function corresponding to your Service
384returns an integer value representing the status of execution
385(<code class="docutils literal"><span class="pre">SERVICE_FAILED</span></code> <a class="footnote-reference" href="#f1" id="id1">[1]</a> or <code class="docutils literal"><span class="pre">SERVICE_SUCCEEDED</span></code> <a class="footnote-reference" href="#f2" id="id2">[2]</a>) and takes three
386arguments (<a class="reference external" href="http://docs.python.org/tutorial/datastructures.html#dictionaries">Python dictionaries</a>):</p>
387<blockquote>
388<div><ul class="simple">
389<li><code class="docutils literal"><span class="pre">conf</span></code> : the main environment configuration (corresponding to the main.cfg content)</li>
390<li><code class="docutils literal"><span class="pre">inputs</span></code> : the requested / default inputs (used to access input values)</li>
391<li><code class="docutils literal"><span class="pre">outputs</span></code> : the requested / default outputs (used to store computation result)</li>
392</ul>
393</div></blockquote>
394<div class="admonition note">
395<p class="first admonition-title">Note</p>
396<p class="last">when your service return <code class="docutils literal"><span class="pre">SERVICE_FAILED</span></code> you can set
397<code class="docutils literal"><span class="pre">conf[&quot;lenv&quot;][&quot;message&quot;]</span></code> to add a personalized message in the ExceptionReport
398returned by the ZOO Kernel in such case.</p>
399</div>
400<p>You get in the following a sample <code class="docutils literal"><span class="pre">conf</span></code> value based on the <code class="docutils literal"><span class="pre">main.cfg</span></code> file you
401saw <a class="reference external" href="using_zoo_from_osgeolivevm.html#zoo-kernel-configuration">before</a>.</p>
402<div class="highlight-javascript"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
403 2
404 3
405 4
406 5
407 6
408 7
409 8
410 9
41110
41211
41312
41413
41514
41615
41716
41817
41918
42019
42120
42221
42322
42423
42524
42625
42726
42827
42928
43029
43130
43231
43332
43433</pre></div></td><td class="code"><div class="highlight"><pre><span class="p">{</span>
435  <span class="s2">&quot;main&quot;</span><span class="o">:</span> <span class="p">{</span>
436    <span class="nx">language</span><span class="o">:</span> <span class="s2">&quot;en-US&quot;</span><span class="p">,</span>
437    <span class="nx">lang</span><span class="o">:</span> <span class="s2">&quot;fr-FR,ja-JP&quot;</span><span class="p">,</span>
438    <span class="nx">version</span><span class="o">:</span> <span class="s2">&quot;1.0.0&quot;</span><span class="p">,</span>
439    <span class="nx">encoding</span><span class="o">:</span> <span class="s2">&quot;utf-8&quot;</span><span class="p">,</span>
440    <span class="nx">serverAddress</span><span class="o">:</span> <span class="s2">&quot;http://localhost/cgi-bin/zoo_loader.cgi&quot;</span><span class="p">,</span>
441    <span class="nx">dataPath</span><span class="o">:</span> <span class="s2">&quot;/var/data&quot;</span><span class="p">,</span>
442    <span class="nx">tmpPath</span><span class="o">:</span> <span class="s2">&quot;/var/www/temp&quot;</span><span class="p">,</span>
443    <span class="nx">tmpUrl</span><span class="o">:</span> <span class="s2">&quot;../temp&quot;</span><span class="p">,</span>
444    <span class="nx">cacheDir</span><span class="o">:</span> <span class="s2">&quot;/var/www/temp/&quot;</span>
445  <span class="p">},</span>
446  <span class="s2">&quot;identification&quot;</span><span class="o">:</span> <span class="p">{</span>
447    <span class="nx">title</span><span class="o">:</span> <span class="s2">&quot;ZOO-Project Workshop - FOSS4G 2014&quot;</span><span class="p">,</span>
448    <span class="nx">keywords</span><span class="o">:</span> <span class="s2">&quot;WPS,GIS,buffer&quot;</span><span class="p">,</span>
449    <span class="kr">abstract</span><span class="o">:</span> <span class="s2">&quot;Deploying Web Processing Services using ZOO-Project – Examples of Python based WPS using PgRouting&quot;</span><span class="p">,</span>
450    <span class="nx">accessConstraints</span><span class="o">:</span> <span class="s2">&quot;none&quot;</span><span class="p">,</span>
451    <span class="nx">fees</span><span class="o">:</span> <span class="s2">&quot;None&quot;</span>
452  <span class="p">},</span>
453  <span class="s2">&quot;provider&quot;</span><span class="o">:</span> <span class="p">{</span>
454    <span class="nx">positionName</span><span class="o">:</span> <span class="s2">&quot;Developer&quot;</span><span class="p">,</span>
455    <span class="nx">providerName</span><span class="o">:</span> <span class="s2">&quot;ZOO-Project&quot;</span><span class="p">,</span>
456    <span class="nx">addressAdministrativeArea</span><span class="o">:</span> <span class="s2">&quot;Lattes&quot;</span><span class="p">,</span>
457    <span class="nx">addressCountry</span><span class="o">:</span> <span class="s2">&quot;fr&quot;</span><span class="p">,</span>
458    <span class="nx">phoneVoice</span><span class="o">:</span> <span class="s2">&quot;False&quot;</span><span class="p">,</span>
459    <span class="nx">addressPostalCode</span><span class="o">:</span> <span class="s2">&quot;34970&quot;</span><span class="p">,</span>
460    <span class="nx">role</span><span class="o">:</span> <span class="s2">&quot;Dev&quot;</span><span class="p">,</span>
461    <span class="nx">providerSite</span><span class="o">:</span> <span class="s2">&quot;http://www.zoo-project.org&quot;</span><span class="p">,</span>
462    <span class="nx">phoneFacsimile</span><span class="o">:</span> <span class="s2">&quot;False&quot;</span><span class="p">,</span>
463    <span class="nx">addressElectronicMailAddress</span><span class="o">:</span> <span class="s2">&quot;gerald.fenoy@geolabs.fr&quot;</span><span class="p">,</span>
464    <span class="nx">addressCity</span><span class="o">:</span> <span class="s2">&quot;Denver&quot;</span><span class="p">,</span>
465    <span class="nx">individualName</span><span class="o">:</span> <span class="s2">&quot;Gérald FENOY&quot;</span>
466  <span class="p">}</span>
467</pre></div>
468</td></tr></table></div>
469<p>In the following you get a sample outputs value passed to a Python or a JavaScript Service:</p>
470<div class="highlight-javascript"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
4712
4723
4734
4745
4756
4767</pre></div></td><td class="code"><div class="highlight"><pre><span class="p">{</span>
477  <span class="s1">&#39;Result&#39;</span><span class="o">:</span> <span class="p">{</span>
478    <span class="s1">&#39;mimeType&#39;</span><span class="o">:</span> <span class="s1">&#39;application/json&#39;</span><span class="p">,</span>
479    <span class="s1">&#39;inRequest&#39;</span><span class="o">:</span> <span class="s1">&#39;true&#39;</span><span class="p">,</span>
480    <span class="s1">&#39;encoding&#39;</span><span class="o">:</span> <span class="s1">&#39;UTF-8&#39;</span>
481  <span class="p">}</span>
482<span class="p">}</span>
483</pre></div>
484</td></tr></table></div>
485<div class="admonition note">
486<p class="first admonition-title">Note</p>
487<p class="last">the <code class="docutils literal"><span class="pre">inRequest</span></code> value is set internally by the ZOO-Kernel and can be    used to determine from the Service if the key was provided in the request.</p>
488</div>
489<p>ZOO-Project provide a ZOO-API which was originally only available for
490JavaScript services, but thanks to the work of the ZOO-Project
491community, now you have also access to a ZOO-API when using
492the Python language. Thanks to the Python ZOO-API you don&#8217;t have to remember anymore
493the value of SERVICE_SUCCEDED and SERVICE_FAILED, you
494have the capability to translate any string from your Python service
495by calling the <code class="docutils literal"><span class="pre">_</span></code> function (ie: <code class="docutils literal"><span class="pre">zoo._('My</span> <span class="pre">string</span> <span class="pre">to</span>
496<span class="pre">translate')</span></code>) or to update the current status of a running service by
497using the <code class="docutils literal"><span class="pre">update_status</span></code> <a class="footnote-reference" href="#f4" id="id3">[3]</a> function the same way you use it from
498JavaScript or C services.</p>
499</div>
500<div class="section" id="the-hello-service">
501<h3><a class="toc-backref" href="#table-of-contents">The Hello Service</a><a class="headerlink" href="#the-hello-service" title="Permalink to this headline"></a></h3>
502<p>You can copy and paste the following into the
503<code class="docutils literal"><span class="pre">/home/user/zoo-ws/ws_sp/cgi-env/test_service.py</span></code> file.</p>
504<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">zoo</span>
505<span class="k">def</span> <span class="nf">Hello</span><span class="p">(</span><span class="n">conf</span><span class="p">,</span><span class="n">inputs</span><span class="p">,</span><span class="n">outputs</span><span class="p">):</span>
506    <span class="n">outputs</span><span class="p">[</span><span class="s">&quot;Result&quot;</span><span class="p">][</span><span class="s">&quot;value&quot;</span><span class="p">]</span><span class="o">=</span>\
507            <span class="s">&quot;Hello &quot;</span><span class="o">+</span><span class="n">inputs</span><span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">][</span><span class="s">&quot;value&quot;</span><span class="p">]</span><span class="o">+</span><span class="s">&quot; from the ZOO-Project Python world !&quot;</span>
508    <span class="k">return</span> <span class="n">zoo</span><span class="o">.</span><span class="n">SERVICE_SUCCEEDED</span>
509</pre></div>
510</div>
511<p>Once you finish editing the file, you should copy it in the <code class="docutils literal"><span class="pre">/usr/lib/cgi-bin</span></code> directory:</p>
512<div class="highlight-none"><div class="highlight"><pre>sudo cp /home/user/zoo-ws/ws_sp/cgi-env/* /usr/lib/cgi-bin
513</pre></div>
514</div>
515</div>
516</div>
517<div class="section" id="interracting-with-your-service-using-execute-requests">
518<h2><a class="toc-backref" href="#table-of-contents">Interracting with your service using Execute requests</a><a class="headerlink" href="#interracting-with-your-service-using-execute-requests" title="Permalink to this headline"></a></h2>
519<p>Now, you can request for Execute using the following basic url:</p>
520<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto
521</pre></div>
522</div>
523<p>You can request the WPS Server to return a XML WPS Response containing the result of
524your computation, requesting for ResponseDocument or you can access the data directly
525requesting for RawDataOutput.</p>
526<ul class="simple">
527<li>Sample request using the RawDataOutput parameter:</li>
528</ul>
529<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;RawDataOutput=Result
530</pre></div>
531</div>
532<ul class="simple">
533<li>Sample request using the default ResponseDocument parameter:</li>
534</ul>
535<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;ResponseDocument=Result
536</pre></div>
537</div>
538<p>When you are using ResponseDocument there is specific attribut you can use to ask
539the ZOO Kernel to store the result: <code class="docutils literal"><span class="pre">asReference</span></code>. You can use the following example:</p>
540<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;ResponseDocument=Result@asReference=true
541</pre></div>
542</div>
543<p>When computation take long time, the client should request the
544execution of a Service by setting both <code class="docutils literal"><span class="pre">storeExecuteResponse</span></code> and
545<code class="docutils literal"><span class="pre">status</span></code> parameter to true to force asynchronous execution. This
546will make the ZOO-Kernel return, without waiting for the Service execution
547completion but after starting another ZOO-Kernel process responsible
548of the Service execution, a ResponseDocument containing a <code class="docutils literal"><span class="pre">statusLocation</span></code>
549attribute which can be used to access the status of an ongoing service
550or the result when the process ended <a class="footnote-reference" href="#f3" id="id4">[4]</a>.</p>
551<div class="highlight-none"><div class="highlight"><pre>http://localhost/cgi-bin/zoo_loader.cgi?request=Execute&amp;service=WPS&amp;version=1.0.0&amp;Identifier=Hello&amp;DataInputs=name=toto&amp;ResponseDocument=Result&amp;storeExecuteResponse=true&amp;status=true
552</pre></div>
553</div>
554</div>
555<div class="section" id="conclusion">
556<h2><a class="toc-backref" href="#table-of-contents">Conclusion</a><a class="headerlink" href="#conclusion" title="Permalink to this headline"></a></h2>
557<p>Even if this first service was really simple it was useful to illustrate how the
558ZOO-Kernel fill <code class="docutils literal"><span class="pre">conf</span></code>, <code class="docutils literal"><span class="pre">inputs</span></code> and <code class="docutils literal"><span class="pre">outputs</span></code> parameter prior to load
559and run your function service, how to write a ZCFG file, how to publish a Services
560Provider by placing the ZCFG and Python files in the same directory as the
561ZOO-Kernel, then how to interract with your service using both
562<code class="docutils literal"><span class="pre">GetCapabilities</span></code>, <code class="docutils literal"><span class="pre">DescribeProcess</span></code> and <code class="docutils literal"><span class="pre">Execute</span></code> requests. We will see
563in the <a class="reference external" href="building_blocks_presentation.html">next section</a> how to write similar requests
564using the XML syntax.</p>
565<p class="rubric">Footnotes</p>
566<table class="docutils footnote" frame="void" id="f1" rules="none">
567<colgroup><col class="label" /><col /></colgroup>
568<tbody valign="top">
569<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><code class="docutils literal"><span class="pre">SERVICE_FAILED=4</span></code></td></tr>
570</tbody>
571</table>
572<table class="docutils footnote" frame="void" id="f2" rules="none">
573<colgroup><col class="label" /><col /></colgroup>
574<tbody valign="top">
575<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td><code class="docutils literal"><span class="pre">SERVICE_SUCCEEDED=3</span></code></td></tr>
576</tbody>
577</table>
578<table class="docutils footnote" frame="void" id="f4" rules="none">
579<colgroup><col class="label" /><col /></colgroup>
580<tbody valign="top">
581<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>sample use of update_status is available <a class="reference external" href="http://zoo-project.org/trac/browser/trunk/zoo-project/zoo-services/utils/status/cgi-env/service.py#L1">here</a></td></tr>
582</tbody>
583</table>
584<table class="docutils footnote" frame="void" id="f3" rules="none">
585<colgroup><col class="label" /><col /></colgroup>
586<tbody valign="top">
587<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>To get on-going status url in <code class="docutils literal"><span class="pre">statusLocation</span></code>, you&#8217;ll
588need to setup the <a class="reference external" href="http://www.zoo-project.org/trac/browser/trunk/zoo-project/zoo-services/utils/status">utils/status</a>
589Service. If you don&#8217;t get this service available, the ZOO-Kernel will
590simply give the url to a flat XML file stored on the server which will
591contain, at the end of the execution, the result of the Service
592execution. For more informations please take a look into the
593reference  <a class="reference external" href="http://zoo-project.org/docs/services/status.html">documentation</a>.</td></tr>
594</tbody>
595</table>
596</div>
597</div>
598
599
600          </div>
601          <footer>
602 
603
604  <hr/>
605  <div class="pfoot">
606  <div role="contentinfo">
607    <p>
608        &copy; Copyright 2009-2015, ZOO-Project team.
609    </p>
610  </div>
611  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> inspired by <a href="https://readthedocs.org">Read the Docs</a>.
612</div>
613</footer>
614
615        </div>
616      </div>
617
618    </section>
619
620  </div>
621 
622
623
624 
625
626    <script type="text/javascript">
627        var DOCUMENTATION_OPTIONS = {
628            URL_ROOT:'../../',
629            VERSION:'1.4a0',
630            COLLAPSE_INDEX:false,
631            FILE_SUFFIX:'.html',
632            HAS_SOURCE:  true
633        };
634    </script>
635      <script type="text/javascript" src="../../_static/jquery.js"></script>
636      <script type="text/javascript" src="../../_static/underscore.js"></script>
637      <script type="text/javascript" src="../../_static/doctools.js"></script>
638
639 
640
641 
642 
643    <script type="text/javascript" src="../../_static/js/theme.js"></script>
644 
645
646 
647 
648  <script type="text/javascript">
649      jQuery(function () {
650          SphinxRtdTheme.StickyNav.enable();
651      });
652  </script>
653   
654
655</body>
656</html>
Note: See TracBrowser for help on using the repository browser.

Download now !

Search

Context Navigation

Main 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