<?xml version="1.0" encoding="UTF-8"?>
<!--
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - JASMINe
  - Copyright (C) 2011-2012 Bull S.A.S.
  - Contact: jasmine@ow2.org
  -
  - This library is free software; you can redistribute it and/or
  - modify it under the terms of the GNU Lesser General Public
  - License as published by the Free Software Foundation; either
  - version 2.1 of the License, or any later version.
  -
  - This library is distributed in the hope that it will be useful,
  - but WITHOUT ANY WARRANTY; without even the implied warranty of
  - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  - Lesser General Public License for more details.
  -
  - You should have received a copy of the GNU Lesser General Public
  - License along with this library; if not, write to the Free Software
  - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
  - USA
  -
  -
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  - $Id$
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
<sect1 version="5.0" xml:lang="en" xml:id="jasmineprobe.tools_rest" xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:svg="http://www.w3.org/2000/svg"
  xmlns:mml="http://www.w3.org/1998/Math/MathML"
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:db="http://docbook.org/ns/docbook">

  <title>RESTful Web Service for JASMINe Probe artifacts management</title>

    <para>
      The service has the following address base:
      <screen>http://host:9000/jbrobe/</screen>
    </para>
    <para>The 9000 port number corresponds to the web service configuration. See <xref linkend="jasmineprobe.config_server"/> for further details.</para>

  <sect2>
    <title>Target management</title>
    <itemizedlist>
     <listitem>
       <para>
         list targets:
       </para>
       <para>
         GET /target
       </para>
     </listitem>

     <listitem>
       <para>
         retrieve a target's definition
       </para>
       <para>
         GET /target/{targetName}
       </para>
       <para>
         For example, the result of:
       </para>
       <para>
       <screen>
         GET http://localhost:9000/jprobe/target/jonas
       </screen>
       </para>
       <para>is</para>
       <para>
       <screen>
         &lt;target href="http://localhost:9000/jprobe/target/jonas" name="jonas"&gt;
           &lt;property key="url" value="service:jmx:rmi:///jndi/rmi://localhost:1099/jrmpconnector_jonas"&gt;
         &lt;/target&gt;
       </screen>
       </para>
     </listitem>

     <listitem>
       <para>
         create a target
       </para>
       <para>
         POST /target
       </para>
       <para>
        The request must have a body (an associated entity) containing the new target definition in an XML format. Use the format corresponding to the GET /target/{targetName} result.
       </para>
     </listitem>

     <listitem>
       <para>
         remove a target
       </para>
       <para>
         DELETE /target/{targetName}
       </para>

     </listitem>

   </itemizedlist>
  </sect2>
  <sect2>
    <title>Indicator management</title>

    <itemizedlist>
     <listitem>
       <para>
         list indicators:
       </para>
       <para>
         GET /indicator
       </para>
     </listitem>

     <listitem>
       <para>
         retrieve an indicator's definition
       </para>
       <para>
         GET /indicator/{indicatorName}
       </para>
       <para>
         For example, the result of:
       </para>
       <para>
       <screen>
         GET http://localhost:9000/jprobe/indicator/maxSize
       </screen>
       </para>
       <para>is</para>
       <para>
       <screen>
         &lt;indicator href="http://localhost:9000/jprobe/indicator/maxSize" name="maxSize" type="jmx" scale="1"&gt;
           &lt;property key="mbean" value="*:j2eeType=JCAConnectionFactory,*"&gt;
           &lt;property key="target" value="jonas"&gt;
           &lt;property key="attr" value="maxSize"&gt;
         &lt;/indicator&gt;
       </screen>
       </para>
     </listitem>

     <listitem>
       <para>
         create an indicator
       </para>
       <para>
         POST /indicator
       </para>
       <para>
        The request must have a body (an associated entity) containing the new indicator definition in an XML format. Use the format corresponding to the GET /indicator/{indicatorName} result.
       </para>
     </listitem>

     <listitem>
       <para>
         change an indicator's definition
       </para>
       <para>
         PUT /indicator/{indicatorName}
       </para>
       <para>
        The request must have a body (an associated entity) containing the updated definition in an XML format. You can provide only the modified attributes or properties.
       </para>
     </listitem>

     <listitem>
       <para>
         remove an indicator
       </para>
       <para>
         DELETE /indicator/{indicatorName}
       </para>
     </listitem>

     <listitem>
       <para>
         list indicator types:
       </para>
       <para>
         GET /indicatorType
       </para>
     </listitem>

     <listitem>
       <para>
         retrieve the properties (name, description, required or not) to be defined when creating an indicator of a given type.
       </para>
       <para>
         GET /indicatorType/{type}/props
       </para>
     </listitem>
     <listitem>
       <para>
         retrieve detailed description of a given indicator type (role, properties, usage).
       </para>
       <para>
         GET /indicatorType/{type}/info
       </para>
     </listitem>
   </itemizedlist>
  </sect2>

  <sect2>
    <title>Output management</title>

    Simmilar to indicators management. Just replace 'indicator' by 'output' in the URIs.
  </sect2>

  <sect2>
    <title>Probe management</title>

    <itemizedlist>
     <listitem>
       <para>
         list probes:
       </para>
       <para>
         GET /probe
       </para>
     </listitem>

     <listitem>
       <para>
         retrieve an probe's definition
       </para>
       <para>
         GET /probe/{probeId}
       </para>
       <para>
         For example, the result of:
       </para>
       <para>
       <screen>
         GET http://localhost:9000/jprobe/probe/mems
       </screen>
       </para>
       <para>is</para>
       <para>
       <screen>
         &lt;probe status="stopped" href="http://localhost:9000/jprobe/probe/mems" id="mems" period="5"&gt;
           &lt;indicator&gt;used-memory&lt;/indicator&gt;
           &lt;indicator&gt;used-nh-memory&lt;/indicator&gt;
           &lt;indicator&gt;used-total-memory&lt;/indicator&gt;
           &lt;output&gt;stdio&lt;/output&gt;
           &lt;link rel="down" href="http://localhost:9000/jprobe/indicator/used-memory"/&gt;
           &lt;link rel="down" href="http://localhost:9000/jprobe/indicator/used-nh-memory"/&gt;
           &lt;link rel="down" href="http://localhost:9000/jprobe/indicator/used-total-memory"/&gt;
           &lt;link rel="down" href="http://localhost:9000/jprobe/output/stdio"/&gt;
         &lt;/probe&gt;
       </screen>
       </para>
     </listitem>

     <listitem>
       <para>
         create an probe
       </para>
       <para>
         POST /probe
       </para>
       <para>
        The request must have a body (an associated entity) containing the new probe definition in an XML format.
        Use the format corresponding to the GET /probe/{probeId} result. If the id attribute is not defined, a new id is generated.
       </para>
       <para>
         For example, the result of:
       </para>
       <para>
       <screen>
         POST http://localhost:9000/jprobe/probe
       </screen>
       </para>
       <para>with body containing the following XML entity:</para>
       <para>
       <screen>
         &lt;?xml version="1.0" encoding="UTF-8" standalone="yes"?&gt;
           &lt;probe xmlns="org.ow2.jasmine.probe:probe-config" period="20" status="stopped"&gt;
           &lt;indicator&gt;ci&lt;/indicator&gt;
           &lt;output&gt;stdio&lt;/output&gt;
           &lt;target&gt;jonas&lt;/target&gt;
         &lt;/probe&gt;
       </screen>
       </para>
       <para>
         creates a new probe, and the generated id is placed in the <emphasis>Location</emphasis> header of the response.
         In the current example, the probe manager generates an id equal to the name of the <emphasis>ci</emphasis> indicator (this rule corresponds to the case when only one indicator is defined for a probe).
       </para>
       <para>
       <screen>
         Location: http://localhost:9000/jprobe/probe/ci
       </screen>
       </para>
     </listitem>

     <listitem>
       <para>
         change an probe's definition
       </para>
       <para>
         PUT /probe/{probeName}
       </para>
       <para>
        The request must have a body (an associated entity) containing the updated definition in an XML format. You can provide only the modified attributes.
       </para>
     </listitem>

     <listitem>
       <para>
         remove an probe
       </para>
       <para>
         DELETE /probe/{probeName}
       </para>
     </listitem>

     <listitem>
       <para>
         start an probe
       </para>
       <para>
         POST /probe/{probeName}/action/start
       </para>
     </listitem>

     <listitem>
       <para>
         stop an probe
       </para>
       <para>
         POST /probe/{probeName}/action/stop
       </para>
     </listitem>
    </itemizedlist>
  </sect2>

</sect1>
