BioUML exceptions - Revision history

Lan@dote.ru at 05:24, 11 September 2013

2013-09-11T05:24:06Z

Lan@dote.ru: Typo fixed /* Exception descriptors */

2013-08-07T08:44:21Z

Typo fixed - ‎Exception descriptors

Lan@dote.ru: Logging levels updated /* Exception descriptors */

2013-08-07T08:44:05Z

Logging levels updated - ‎Exception descriptors

Lan@dote.ru: BioSoftException -> BiosoftException

2013-07-23T11:07:04Z

BioSoft*Exception -> Biosoft*Exception

Lan@dote.ru: BioUMLException -> BioSoftException

2013-07-23T11:00:07Z

BioUML*Exception -> BioSoft*Exception

Lan@dote.ru: +Descriptors

2013-07-23T04:49:00Z

+Descriptors

Lan@dote.ru: /* Usage guidelines */

2013-07-22T10:58:18Z

‎Usage guidelines

Lan@dote.ru: +getDataElement

2013-07-22T10:22:11Z

+getDataElement

Lan@dote.ru: Created page with "{{Draft}} This article describes new BioUML exception handling concept introduced in version 0.9.6. == Overview == '''BioUML exceptions''' (short: '''BUEX''') are descend..."

2013-07-22T10:14:22Z

Created page with "{{Draft}} This article describes new BioUML exception handling concept introduced in version 0.9.6. == Overview == '''BioUML exceptions''' (short: '''BUEX''') are descend..."

New page

{{Draft}}
This article describes new [[BioUML]] exception handling concept introduced in version 0.9.6.

== Overview ==
'''BioUML exceptions''' (short: '''BUEX''') are descendants of class {{Class|ru.biosoft.access.exception.BioUMLException}}. All other exceptions are called '''raw exceptions'''. Now it's undesired to throw raw exception in BioUML code except some cases when particular part of code can become BioUML-independent.

Class {{Class|ru.biosoft.access.exception.BioUMLException}} extends {{Class|java.lang.RuntimeException}}, thus it's not necessary (but desired!) to declare it in <code>throws</code> clause.

== Exception levels ==
Exceptions are divided to several categories called '''exception levels'''. '''Low-level BioUML exceptions''' include:

;System
:Low level errors: out of memory, NPE, programmatic errors, etc.
;SQL
:Low level SQL database access problem
;IO
:Low level input/output access problem
;Network:
:Low level network problem

'''High-level BioUML exceptions''' include:
;Repository
:Repository problem (unable to get, put, delete element, etc.)
;Security
:Access violation, quota, etc.
;Computational
:Computational problem during some data analysis
;Parameter
:User input problem

List of levels may change in future. Every level has its base exception class. For example, exceptions of level 'System' are related to {{Class|ru.biosoft.access.exception.BioUMLSystemException}} and its subclasses.

== Exception properties ==
Each BioUML exception has the following properties:
;ID
:Autoincrementing number starting from 1 identifying the exception.
;Level
:Exception level (described above)
;Code
:Text string which together with level refers to particular error situation. For example, code 'NPE' of level 'System' refers to null pointer exception. Usually level and code are written together as 'System.NPE'
;Logging level
:How this exception should be displayed in log:
:*None - Do not log this Exception even if requested
:*Summary - Log summary
:*Parameters - Log summary+properties
:*Trace - Log summary+properties+trace

Also BioUML exception has custom properties defined in {{Class|com.beanexplorer.beans.DynamicPropertySet}}. They can be logged and used in generating user-friendly messages.

== Chaining ==
BioUML exceptions can be chained. Usually (but not always) high-level exception has low-level exception cause, which may have raw exception as the cause. Every raw exception can be converted to BioUML exception using {{Method|ru.biosoft.access.exception.ExceptionRegistry.translateException(Throwable)}} method (if BioUML exception was passed to this method it will just return it). However in many cases it's desired to create BioUML exception manually as you may specify additional details. BioUML exception should not be the cause of raw exception. Low-level exception should has raw exception or nothing as the cause (not another BioUML exception).

== Reporting ==
[[File:Application_log_error_log_workbench.png|thumb|Error log in [[BioUML workbench]].]]
There are two ways to report the BioUML exception: to display it to user and to log it. All BioUML exceptions are logged into special logger <code>error.log</code>. In [[BioUML workbench]] it's displayed as a separate sub tab of [[Application log (viewpart)|Application log viewpart]]. On [[BioUML server]] this might be appended to separate file depending on your server.lcf configuration. Ideally all low-level technical information including all the stacktraces must go there. Messages displayed to the user (including ones displayed in normal Application log) should be more user-friendly.

For example, this is how the exception is reported in Application log:
ERROR : Cannot create collection data/Collaboration/Lan_test/Data/MACS/profile
Error reason: Internal error occured (Java class ru.biosoft.bsa.analysis.chipseqprofile.PeakProfileTransformer not found). Please check error log for BUEX#136.

And this is how the same exception is reported in Error log:
ERROR : BUEX#137/Repository.CannotCreate: Cannot create collection data/Collaboration/Lan_test/Data/MACS/profile
Caused by: BUEX#136/System.NoClass: Internal error occured (Java class ru.biosoft.bsa.analysis.chipseqprofile.PeakProfileTransformer not found).
Caused by: java.lang.ClassNotFoundException: Can't load class ru.biosoft.bsa.analysis.chipseqprofile.PeakProfileTransformer
at ru.biosoft.access.CollectionFactory.loadClass(CollectionFactory.java:269)
at ru.biosoft.access.TransformedDataCollection.<init>(TransformedDataCollection.java:45)
at sun.reflect.GeneratedConstructorAccessor12.newInstance(Unknown Source)
at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:27)
at java.lang.reflect.Constructor.newInstance(Constructor.java:513)
at ru.biosoft.access.CollectionFactory.createCollection(CollectionFactory.java:195)
at ru.biosoft.access.CollectionFactory.createCollection(CollectionFactory.java:148)
at ru.biosoft.access.LocalRepository.createCollection(LocalRepository.java:224)
at ru.biosoft.access.LocalRepository.init(LocalRepository.java:131)
(many more stacktrace lines)

To log the exception, use {{Method|ru.biosoft.access.exception.BioUMLException.log()}} method. Each exception can be logged only once in order not to pollute the error log with dublicates.

To get the user-friendly message use {{Method|ru.biosoft.access.exception.BioUMLException.getMessage()}} method. This method provides one-line description of the problem followed by the description of the cause. If cause is absent or it's raw exception, it's not returned. By default for low-level exceptions additional message added like <code>Please check error log for BUEX#...</code> for [[BioUML workbench]] or <code>Please contact application vendor supplying ID BUEX#...</code> for [[BioUML server]].

Message templates are registered currently in the static section of {{Class|ru.biosoft.access.exception.ExceptionRegistry}} class. In future this might be changed to some kind of extension point. Templates can use all custom properties defined by exception referring to them like <code>$path$</code>. Bean properties of these properties can also be used like <code>$cause/class/simpleName$</code> (the same syntax is used by {{Method|ru.biosoft.util.OptionEx.makeAutoProperty}}).

== Usage guidelines ==
Try not to 'swallow' the exception if you cannot handle it properly. Printing the exception to log and returning null is bad practice as calling code won't know what's going on. Also printing to the log might be useless for [[BioUML web edition]] as messages from your log object may not be passed to the client at all. Consider wrapping the exception to higher-level BioUML exception and throw it outside. If you think that user might be interested in exception, but you can continue ignoring it, use {{Method|ru.biosoft.access.exception.ExceptionRegistry.log(Throwable)}}, which will translate an exception to BioUML exception, log it and return the user-friendly message.

[[Category:Development]]

← Older revision		Revision as of 05:24, 11 September 2013
Line 1:		Line 1:
−	~~{{Draft}}~~
	This article describes new [[BioUML]] exception handling concept introduced in version 0.9.6.		This article describes new [[BioUML]] exception handling concept introduced in version 0.9.6.

@@ Line 18: / Line 18: @@
 :*None - Do not log this Exception even if requested
 :*Summary - Log summary+properties which are not directly specified in summary message
-:*TraceIfNoCause - Log summary+properties+trace if exception as no cause
+:*TraceIfNoCause - Log summary+properties+trace if exception has no cause
 :*Trace - Log summary+properties+trace
 ;Template

@@ Line 3: / Line 3: @@
 == Overview ==
-'''BioUML exceptions''' (short: '''BUEX''') are descendants of class {{Class|ru.biosoft.access.exception.BioSoftException}}. All other exceptions are called '''raw exceptions'''. Now it's undesired to throw raw exception in BioUML code except some cases when particular part of code can become BioUML-independent.
+'''BioUML exceptions''' (short: '''BUEX''') are descendants of class {{Class|ru.biosoft.access.exception.BiosoftException}}. All other exceptions are called '''raw exceptions'''. Now it's undesired to throw raw exception in BioUML code except some cases when particular part of code can become BioUML-independent.
-Class {{Class|ru.biosoft.access.exception.BioSoftException}} extends {{Class|java.lang.RuntimeException}}, thus it's not necessary (but desired!) to declare it in <code>throws</code> clause.
+Class {{Class|ru.biosoft.access.exception.BiosoftException}} extends {{Class|java.lang.RuntimeException}}, thus it's not necessary (but desired!) to declare it in <code>throws</code> clause.
 == Exception descriptors ==
@@ Line 23: / Line 23: @@
 :User-friendly message template. Templates can use all custom properties defined by exception referring to them like <code>$path$</code>. Bean properties of these properties can also be used like <code>$cause/class/simpleName$</code> (the same syntax is used by {{Method|ru.biosoft.util.OptionEx.makeAutoProperty}}).
-User code should not use exception descriptors. Instead separate classes for individual exceptions should be created which initialize {{Class|ru.biosoft.access.exception.BioSoftException}} with specific descriptor defined as constant in the same class. For example, {{Class|ru.biosoft.access.exception.QuotaException}} defines {{Constant|ru.biosoft.access.exception.QuotaException.ED_QUOTA}} descriptor.
+User code should not use exception descriptors. Instead separate classes for individual exceptions should be created which initialize {{Class|ru.biosoft.access.exception.BiosoftException}} with specific descriptor defined as constant in the same class. For example, {{Class|ru.biosoft.access.exception.QuotaException}} defines {{Constant|ru.biosoft.access.exception.QuotaException.ED_QUOTA}} descriptor.
 === Exception levels ===
@@ Line 84: / Line 84: @@
   (many more stacktrace lines)
-To log the exception, use {{Method|ru.biosoft.access.exception.BioSoftException.log()}} method. Each exception can be logged only once in order not to pollute the error log with dublicates.
+To log the exception, use {{Method|ru.biosoft.access.exception.BiosoftException.log()}} method. Each exception can be logged only once in order not to pollute the error log with dublicates.
-To get the user-friendly message use {{Method|ru.biosoft.access.exception.BioSoftException.getMessage()}} method. This method provides one-line description of the problem followed by the description of the cause. If cause is absent or it's raw exception, it's not returned. By default for low-level exceptions additional message added like <code>Please check error log for BUEX#...</code> for [[BioUML workbench]] or <code>Please contact application vendor supplying ID BUEX#...</code> for [[BioUML server]].
+To get the user-friendly message use {{Method|ru.biosoft.access.exception.BiosoftException.getMessage()}} method. This method provides one-line description of the problem followed by the description of the cause. If cause is absent or it's raw exception, it's not returned. By default for low-level exceptions additional message added like <code>Please check error log for BUEX#...</code> for [[BioUML workbench]] or <code>Please contact application vendor supplying ID BUEX#...</code> for [[BioUML server]].
 == Usage guidelines ==

@@ Line 3: / Line 3: @@
 == Overview ==
-'''BioUML exceptions''' (short: '''BUEX''') are descendants of class {{Class|ru.biosoft.access.exception.BioUMLException}}. All other exceptions are called '''raw exceptions'''. Now it's undesired to throw raw exception in BioUML code except some cases when particular part of code can become BioUML-independent.
+'''BioUML exceptions''' (short: '''BUEX''') are descendants of class {{Class|ru.biosoft.access.exception.BioSoftException}}. All other exceptions are called '''raw exceptions'''. Now it's undesired to throw raw exception in BioUML code except some cases when particular part of code can become BioUML-independent.
-Class {{Class|ru.biosoft.access.exception.BioUMLException}} extends {{Class|java.lang.RuntimeException}}, thus it's not necessary (but desired!) to declare it in <code>throws</code> clause.
+Class {{Class|ru.biosoft.access.exception.BioSoftException}} extends {{Class|java.lang.RuntimeException}}, thus it's not necessary (but desired!) to declare it in <code>throws</code> clause.
 == Exception descriptors ==
@@ Line 23: / Line 23: @@
 :User-friendly message template. Templates can use all custom properties defined by exception referring to them like <code>$path$</code>. Bean properties of these properties can also be used like <code>$cause/class/simpleName$</code> (the same syntax is used by {{Method|ru.biosoft.util.OptionEx.makeAutoProperty}}).
-User code should not use exception descriptors. Instead separate classes for individual exceptions should be created which initialize {{Class|ru.biosoft.access.exception.BioUMLException}} with specific descriptor defined as constant in the same class. For example, {{Class|ru.biosoft.access.exception.QuotaException}} defines {{Constant|ru.biosoft.access.exception.QuotaException.ED_QUOTA}} descriptor.
+User code should not use exception descriptors. Instead separate classes for individual exceptions should be created which initialize {{Class|ru.biosoft.access.exception.BioSoftException}} with specific descriptor defined as constant in the same class. For example, {{Class|ru.biosoft.access.exception.QuotaException}} defines {{Constant|ru.biosoft.access.exception.QuotaException.ED_QUOTA}} descriptor.
 === Exception levels ===
@@ Line 84: / Line 84: @@
   (many more stacktrace lines)
-To log the exception, use {{Method|ru.biosoft.access.exception.BioUMLException.log()}} method. Each exception can be logged only once in order not to pollute the error log with dublicates.
+To log the exception, use {{Method|ru.biosoft.access.exception.BioSoftException.log()}} method. Each exception can be logged only once in order not to pollute the error log with dublicates.
-To get the user-friendly message use {{Method|ru.biosoft.access.exception.BioUMLException.getMessage()}} method. This method provides one-line description of the problem followed by the description of the cause. If cause is absent or it's raw exception, it's not returned. By default for low-level exceptions additional message added like <code>Please check error log for BUEX#...</code> for [[BioUML workbench]] or <code>Please contact application vendor supplying ID BUEX#...</code> for [[BioUML server]].
+To get the user-friendly message use {{Method|ru.biosoft.access.exception.BioSoftException.getMessage()}} method. This method provides one-line description of the problem followed by the description of the cause. If cause is absent or it's raw exception, it's not returned. By default for low-level exceptions additional message added like <code>Please check error log for BUEX#...</code> for [[BioUML workbench]] or <code>Please contact application vendor supplying ID BUEX#...</code> for [[BioUML server]].
 == Usage guidelines ==

@@ Line 83: / Line 83: @@
 Try not to 'swallow' the exception if you cannot handle it properly. Printing the exception to log and returning null is bad practice as calling code won't know what's going on. Also printing to the log might be useless for [[BioUML web edition]] as messages from your log object may not be passed to the client at all. Consider wrapping the exception to higher-level BioUML exception and throw it outside. If you think that user might be interested in exception, but you can continue ignoring it, use {{Method|ru.biosoft.access.exception.ExceptionRegistry.log(Throwable)}}, which will translate an exception to BioUML exception, log it and return the user-friendly message.
-Currently the prefered way to get the data element is {{Method|ru.biosoft.access.DataElementPath.getDataElement(Class<T>)}}. The parameter is the wanted element class. This method never returns null. Instead it throws BioUMLRepositoryException if element cannot be fetched or has invalid class.
+Currently the prefered way to get the data element is {{Method|ru.biosoft.access.DataElementPath.getDataElement(Class&lt;T&gt;)}}. The parameter is the wanted element class. This method never returns null. Instead it throws BioUMLRepositoryException if element cannot be fetched or has invalid class.
 [[Category:Development]]

@@ Line 7: / Line 7: @@
 Class {{Class|ru.biosoft.access.exception.BioUMLException}} extends {{Class|java.lang.RuntimeException}}, thus it's not necessary (but desired!) to declare it in <code>throws</code> clause.
-== Exception levels ==
+== Exception descriptors ==
 Exceptions are divided to several categories called '''exception levels'''. '''Low-level BioUML exceptions''' include:
@@ Line 29: / Line 47: @@
 :User input problem
-List of levels may change in future. Every level has its base exception class. For example, exceptions of level 'System' are related to {{Class|ru.biosoft.access.exception.BioUMLSystemException}} and its subclasses.
+List of levels may change in future.
 == Exception properties ==
@@ Line 35: / Line 53: @@
 ;ID
 :Autoincrementing number starting from 1 identifying the exception.
-;Level
+;Descriptor
-:Exception level (described above)
+:Exception descriptor associated with this exception
-;Code
-:Text string which together with level refers to particular error situation. For example, code 'NPE' of level 'System' refers to null pointer exception. Usually level and code are written together as 'System.NPE'
-;Logging level
-:How this exception should be displayed in log:
-:*None - Do not log this Exception even if requested
-:*Summary - Log summary
-:*Parameters - Log summary+properties
-:*Trace - Log summary+properties+trace
 Also BioUML exception has custom properties defined in {{Class|com.beanexplorer.beans.DynamicPropertySet}}. They can be logged and used in generating user-friendly messages.
@@ Line 57: / Line 67: @@
 For example, this is how the exception is reported in Application log:
   ERROR :  Cannot create collection data/Collaboration/Lan_test/Data/MACS/profile
-  Error reason: Internal error occured (Java class ru.biosoft.bsa.analysis.chipseqprofile.PeakProfileTransformer not found). Please check error log for BUEX#136.
+  Reason: Internal error occured (Java class ru.biosoft.bsa.analysis.chipseqprofile.PeakProfileTransformer not found). Please check error log for BUEX#136.
 And this is how the same exception is reported in Error log:
@@ Line 77: / Line 87: @@
 To get the user-friendly message use {{Method|ru.biosoft.access.exception.BioUMLException.getMessage()}} method. This method provides one-line description of the problem followed by the description of the cause. If cause is absent or it's raw exception, it's not returned. By default for low-level exceptions additional message added like <code>Please check error log for BUEX#...</code> for [[BioUML workbench]] or <code>Please contact application vendor supplying ID BUEX#...</code> for [[BioUML server]].
 == Usage guidelines ==
 Try not to 'swallow' the exception if you cannot handle it properly. Printing the exception to log and returning null is bad practice as calling code won't know what's going on. Also printing to the log might be useless for [[BioUML web edition]] as messages from your log object may not be passed to the client at all. Consider wrapping the exception to higher-level BioUML exception and throw it outside. If you think that user might be interested in exception, but you can continue ignoring it, use {{Method|ru.biosoft.access.exception.ExceptionRegistry.log(Throwable)}}, which will translate an exception to BioUML exception, log it and return the user-friendly message.
 Currently the prefered way to get the data element is {{Method|ru.biosoft.access.DataElementPath.getDataElement(Class&lt;T&gt;)}}. The parameter is the wanted element class. This method never returns null. Instead it throws BioUMLRepositoryException if element cannot be fetched or has invalid class.
 [[Category:Development]]