All error handling in eBox is implemented with java-style exceptions. These are provided by the perl module Error, you can check the perl documentation for that module for a detailed description on how to use exceptions in perl. eBox exceptions are defined in the EBox::Exceptions namespace.

eBox provides a hierarchy of exceptions from which you can choose the most appropriate for each situation. All eBox exceptions inherit from one of these two exceptions:

The difference between these two kinds is what the user will see when an uncaught exceptions occurs. The user interface framework will show the message contained in the exception unaltered if the exception is an external one. You should use external exceptions for user induced errors, like a syntax error in an IP address given by the user interface to the module backend.

If the exception is internal it will log the error and assume something is wrong internally in eBox (a bug) or in the system in general. When an internal exception is caught by the GUI framework the user will see a generic error message, recommending him to check the system logs or seek technical support. Any exception, internal or external, may be used internally for other purposes, as long as it is caught before it goes all the way up to the GUI framework.

The internal exceptions developed are:

The external exceptions developed are:

If you can't find an exception for certain error condition, you have two options: create a new exception class, inheriting from either EBox::Exceptions::External or EBox::Exceptions::Internal, or just use one those two classes as generic exceptions:

if ($foo_condition) {
	throw EBox::Exceptions::Internal('Something happened!');
}

As you can see, throwing exceptions follows a syntax very similar to Java's. Catching them is very similar too:

use Error qw(:try);

sub foo
{
	my $bar = shift;

	try {
		$bar->doSomething();
	} catch EBox::Exceptions::Base with {
		# do nothing, just ignore the error
	};
}

You can do whatever you like inside the “catch” clause. You may also write several “catch” clauses if you need to do different things for different exception types. “otherwise” and “finally” clauses are also allowed, for a detailed explanation about them just run perldoc Error. A very important detail is not to forget the semicolon after the last clause (the “catch” in the example), failing to do so may produce very weird results, this is due to the black magic that is used in the implementation of the try-catch idiom.