View source for Error and Exception Handling Policy

==DRAFT DOCUMENT==
'''TODO:''' This document is a DRAFT and needs to be revised and extended, especially in the areas of Client and Server error handling.

Input should be given on [[Inconsistent Error and Exception Handling|this]] page.

==Overall==
'''Exceptions should be thrown...'''
* '''whenever genuine Exceptions occur;'''
* '''when other error states (determined by program logic) are detected in code''' and the handling for those is outside the current program scope (e.g. Method, Property Getter/Setter, etc.). 


Raising of Exceptions is not considered costly nowadays. We are happy to throw Exceptions across .NET Remoting boundaries as well, as long this occurs infrequently (see [[Error and Exception Handling Policy#Exception Handling across .NET Remoting Boundaries .28Server_-.3E_Client.29|below]]). 

==Practices That Need to be Adhered to==
===General===
* '''Exceptions must never be 'swallowed'''', that is, get caught and not get re-raised again!
** What ''is allowed'' is catching of a certain Exception and throwing of another Exception instead (in that Exception handler). However, the new Exception must never be a generalisation. Rather it needs to be a ''specialisation'' of the Exception that gets handled. Alternatively it can be ''a different Exception altogether'', if this is meaningful. The second option needs to be carefully assessed and the pros and cons need to be considered - it must not cause confusion in ''any situation'' where it might be handled by a caller.
*** Example - ALLOWED: catching a <code>System.Exception</code> and raising e.g. a <code>System.IO.IOException</code> or a custom openPETRA Exception (both result in a specialisation, which is fine).
*** Example - NOT ALLOWED: catching a <code>System.NullReferenceException</code> and raising a <code>System.Exception</code> instead (that would be a generalisation, in which valuable information is lost!).
** When another Exception is raised than the original Exception, the ''original Exception '''must''' be added as the 'InnerException' of the newly raised Exception''. In doing so the original Exception information isn't lost (incl. the code line where the original Exception occured [if the Assembly is built in the Debug rather than the Release configuration]!). 
*** This is done by adding the instance of the original Exception as the second Argument when creating the instance of the new Exception. 
**** Example: <code>throw new MyAppException("Error caused by trying ThrowInner.", Exp);</code>, where <code>Exp</code> is the instance of the original Exception.
**** Full Example: see [http://msdn.microsoft.com/en-us/library/system.exception.innerexception(v=VS.80).aspx Exception.InnerException Property]
* '''TODO'''

===File Operations===
'''TODO'''

===Server-specific Considerations===
'''TODO'''

====DB Access====
At the moment our auto-generated '...SubmitChanges' Methods in the openPETRA Datastore return a TVerificationResultCollection, but that should be changed to Exceptions being thrown instead - see [[DB Discussions: Transaction Model, Savepoints, Locking; Exception Handling; Caching#SubmitChanges_Methods | DB Discussions]]!

===Client-specific Considerations===
'''TODO'''


==Exception Handling across .NET Remoting Boundaries (Server -> Client)==
All the information that is encapsulated in an Exception is transported without loss of fidelity across .NET Remoting boundaries (this works fine from Linux/mono to Windows/MS .NET as well!). 

We are happy to throw Exceptions across .NET Remoting boundaries. However, this this should be done infrequently as throwing Exceptions across .NET Remoting boundaries is more costly then throwing Exceptions in the same Operating System process. 
Be sure to ''never'' throw Exceptions across .NET Remoting boundaries ''in a loop'' of some sort because this could result in a lot of Exceptions which would all need to be remoted, and this would be quite costly!

===Custom Exceptions crossing .NET Remoting Boundaries===
If a custom Exception needs to be able to cross .NET Remoting boundaries and keep its specific data in doing so, care needs to be taken that any custom Exception data is not lost! 

Of special importance is the implementation of the Method '<code>GetObjectData</code>': check out some of our custom Exceptions in the Namespace <code>Ict.Petra.Shared.RemotedExceptions</code> to see examples on how this is done properly!

====Obligatory Namespace for Remoted Exceptions====
All custom Exceptions which can cross .NET Remoting boundaries must be specified in the Namespace <code>Ict.Petra.Shared.RemotedExceptions</code>.


==Central Place for Maintenance of Unique Error Codes==
The goal is to have a numbering scheme for unique error codes that 
* allows new error codes to be introduced easily;
* ensures that error codes are used and re-used appropriately by the software developers;
* distinguishes between data verification errors and exceptions.

===Past Implementation and Anticipated Changes===
* In Petra 2.x, a DB Table ('s_error_message') held error codes and the associated error messages centrally. A central function existed which displayed these errors when the software developer supplied the error code.
* In openPETRA we will probably do this differently - a global static Class which holds error codes is envisaged, and a message library which will display errors.