.. _agent-exception-handling: 

************************************************************************
Gestione delle eccezioni nei controlli 
************************************************************************

Introduzione
=============

La valutazione delle *expr* di *datasource* e *condition* puo' terminare in modo anomalo in seguito ad errori
di varia natura, come ad esempio:

	* Operazioni semanticamente non corrette (es. divizione per zero o operazioni matematiche tra stringhe di caratteri)

	* Timeout di rete

	* Errori di protocolli di rete (es. certificati invalidi in TLS/SSL)

Attraverso il costrutto *try/catch* e' possibile intercettare queste eccezioni conoscendo il tipo di eccezione
che si intende *riconoscere* e gestire*.

	::
		
		try ......... catch  <TIPO DI ECCEZIONE> ( .... )


Tipi di eccezioni e gerarchia delle eccezioni
===============================================

L'eccezione *generale* che e' possibile intercettare e':

	::
		
		Exception
		

Questa e' l'eccezione di default che viene *intercettata* quando non specificato altrimenti.

Questi due costrutti sono equivalenti:

	::
		
		try ... catch Exception (...)
		
		try ... catch (...)


.. danger:: e' fortemente **sconsigliato** utilizzare construtti *try/catch* intercettando
            sempre eccezioni generiche.

E' sempre *preferibile* intercettare eccezioni specifiche:

	::
		
		try  1/0  catch Exception (-1)                                      NO
		                                                                    
		try  1/0  catch ZeroDivisionError (-1) catch Exception (-2)         SI

Tutti i tipi di eccezione esistenti (comprese le eccezioni dell'agente, vedi :ref:`sanet-exceptions`) 
sono delle *specializzazioni* dell'eccezione base (*derivano* da *Exception*) e sono definite in base 
ad una gerarchia che permette di suddividere ed identificare meglio ogni tipo di eccezione.

Le eccezioni generate internamente da Sanet sono descritte in :ref:`sanet-exceptions`.





.. _external-exceptions:

Eccezioni di librerie esterne o di sistema
=================================================

Non e' possibile fornire un elenco *puntuale* completo di tutte le eccezioni che una *expr* puo' generare.

Sanet si appoggia a diversi moduli esterni/librerie di sistema (*python*), ogniuno dei quali definisce
nuovi tipi di eccezione specifiche.

L'unico modo per conoscere quali eccezioni possono essere intercettare e' leggere la documentazione specifica
dei moduli python/librerie che si stanno utilizzando.

Si veda anche :ref:`exception-hierarchy`.







.. _sanet-exceptions:

Eccezioni di Sanet
=================================================

Quando Sanet valuta le *expr* puo' sollevare un particolare tipo di eccezione chiamato:

	::
		
		PollException

Questa e' l'eccezione *base* della maggior parte delle funzioni di Sanet.

Esempio:

	::
		
		try 1.3.6.1.2.1.1.1.0@ catch PollException ( "NO OID" ) != "NO OID"


Da *PollException* sono derivati altri *sotto-tipi* di eccezioni per identificare meglio casi di errore particolari. 

Queste sono le *sotto-eccezioni* principali:

	* TimeoutException
		
		Viene sollevata quando viene riconosciuto, **ma non gestito**, un timeout di rete.
		
		Esempio:
		
			::
				
				try ... catch TimeoutException (...)
		
		.. warning:: alcune funzioni dell'agente gestiscono internamente molti tipi di errori (es: timeout), che non sono quindi *intercettabili*. 
		             Ad esempio, e' inutile tentare di intercettare un timeout (e molte altre eccezioni di basso livello) 
		             della funzione *urlContentMatches()*:
		             
		                 ::
		                         
		                         try urlContentMatches("https://murolo/prova", "pippo") catch TimeoutException ()    INUTILE
		                     
	
	* UndefinedSnmpValueException
		
		Viene sollevata quando si tenta una GET SNMP senza successo.
		
		Esempio:
		
			::
				
				try ... catch UndefinedSnmpValueException (...)
		
	* UndefinedValueException
	
		Viene sollevata quando si cerca di utilizzare un simbolo {<nome@} non definito.
	
		Esempio:
		
			::
				
				try ... catch UndefinedValueException (...)



.. _exception-hierarchy:

Gerarchia generale delle eccezioni
=================================================

Questa e' la gerarchia (non completa) delle eccezioni 

::
        
        Exception
        |
        +-- StandardError                          <- STANDARD EXCEPTIONS
        |    |
        |    +-- TypeError
        |    |
        |    +-- ValueError
        |    |    +-- UnicodeError
        |    |
        |    +-- ArithmeticError
        |    |
        |    +-- RuntimeError
        |    |    +-- NotImplementedError
        |    |
        |   ...
        |
        |
        +-- <standard libraries>                   <- External libraries
        |    |
        |    |
        |    + <urllib> 
        |    |  |
        |    |  +-- URLErrror
        |    |      |
        |    |      +-- HTTPError
        |    |
        |   ...
        |
        +-- PollException                          <- SANET EXCEPTIONS
             |
            ...