<?xml version="1.0" encoding="UTF-8"?>
<!--
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 - JASMINe Probe
 - 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$
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-->
<chapter version="5.0" xml:lang="en" 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>Running probes</title>

 <para>
     JASMINe Probe provides operations to <emphasis>start</emphasis> and <emphasis>stop</emphasis> a probe's execution any number of times.
 </para>
 <para>
     Once started, the probe's status change from STOPPED to RUNNING if no error occurs, or to FAILED otherwise.
 </para>
 <para>
     Reasons that may lead to an error state may be a bad JASMINe probe artifact definition, or some problem related to polling the specified resources.
     For example, when using a jmx indicator, the jmx target may be unreachable. In this case, definitions must be checked, and verify urls and/or resource names.
 </para>
 <para>
     Note that <emphasis>list probes</emphasis> operation allows to see the probes' status.
 </para>
 <para>
     A RUNNING probe periodically collects the values corresponding to all the indicators specified in its definition.
     All the obtained values are passed to the outputs specified in the probe's definition.
     Each output publishes the values in a specific format on a given support (console, file, bus, etc.). See <xref linkend="jasmineprobe.outforms"/>.
 </para>
 <para>
     At each polling iteration, several values are collected because one or more of the following reasons:
      <itemizedlist>
       <listitem>
         <para>Several indicators are specified by the probe's definition.</para>
       </listitem>
       <listitem>
         <para>Several resources are polled for an indicator. For example, if a jmx indicator is used, several MBeans or several attributes
         or attribute fragments may be specified in the indicator's definition.</para>
       </listitem>
       <listitem>
         <para>A polled resource may have a complex value. In this case, the indicator value is decomposed in fragments having simple values (Number, String, Boolean), also called simple results.</para>
       </listitem>
     </itemizedlist>
 </para>
 <para>
     The JASMINe Probe API defines data types (<emphasis>JasmineIndicatorValue</emphasis> and <emphasis>JasmineSimpleResult</emphasis> classes) allowing to construct
     a data structure for each indicator value obtained at each iteration.
 </para>
 <para>
     Each indicator value is identified by the <emphasis>indicator name</emphasis>. Moreover, each simple result that is composing an indicator value is identified by a <emphasis>result name</emphasis>
     that is generated by JASMINe Probe based on the fragments naming convention (see <xref linkend="jasmineprobe.fragments"/>).
     In most of the cases, the indicator name + the result names are sufficient to uniquely
     distinguish the obtained results. In some particular case, other metadata associated to the results make possible the distinction.
 </para>


 <xi:include href="indicator_values_api.xml" />

 <xi:include href="indicator_values.xml" />

 <xi:include href="output_formats.xml" />
</chapter>
