/ 
Class-DBI-Factory-0.994
River stage zero No dependents
/ Class::DBI::Factory::Exception

NAME

Class::DBI::Factory::Exception - useful exception classes for applications using the CDF framework

SYNOPSIS

try {
  $self->do_something_to($object);
}
catch Exception::SERVER_ERROR with {
  $self->error(shift);
  $self->view('error');
  return $self->redirect_to_view( 'error' );
}

# and elsewhere

throw Exception::SERVER_ERROR(
  -text => 'Failed to update object',
  -errors => \@errors,
  -object => $object,
);

or

throw Exception::OK(
  -text => 'Indexing complete',
  -view => 'index_report',
);

INTRODUCTION

This is a set of exception classes based around apache return codes. It defines the following hierarchy of errors:

* Exception::OK
  '- Exception::DONE
  '- Exception::RETRY

* Exception::SERVER_ERROR
  '- Exception::NOT_FOUND
  '- Exception::GLITCH

* Exception::REDIRECT
  '- Exception::CONFIRM

* Exception::AUTH_REQUIRED
  '- Exception::DECLINED

Any of which can be thrown from anywhere in a CDF-based application and should be sensibly dealt with by Class::DBI::Factory::Handler or one of its subclasses.

The hierarchy may seem a little odd, and probably needs some tidying up, but it is practical. The main categories:

REDIRECT results in a new request to the redirected address (an external redirect with a new, cleared input set).
CONFIRM is a REDIRECT and therefore always triggers a new request, usually to display the object that has just been acted upon.
AUTH_REQUIRED is redirected internally so that only the view changes and other parameters are preserved: this way the attempted action can be resumed on successful login.
DECLINED is a subclass of AUTH_REQUIRED, but points to the 'denied' template rather than the 'login' template.
SERVER_ERROR normally just displays an error page with the supplied error messages on it
GLITCH on the other hand is recorded but allows processing to continue . Only the task that was being carried out when the exception was thrown is affected. This should only be used for very minor errors that nevertheless abort the task at hand.
RETRY tends to bounce people back to an input form to try again.
DONE just stops processing and assumes that everything has been done.

Each exception object has access to a few useful methods, in addition to those provided by Error.pm:

CLASS METHODS

factory()

As usual, returns the locally active factory object.

factory_class()

Defines the class that should be used to retrieve the factory. This works differently here. Most CDF modules are designed to be subclassed, but the CDF::Exception is a tricky one. To change the factory class set $Class::DBI::Factory::Exception::factory_class to the full class name you want to use. It will be a subclass of CDF, presumably:

$Class::DBI::Factory::Exception::factory_class = 'Delivery';

will mean that the factory is retrieved by calling Delivery->instance, not Class::DBI::Factory->instance.

do_log()

If a particular exception class returns non-zero here, that kind of error will be logged.

do_notify()

If a particular exception class returns non-zero here, that kind of error will be emailed to the admin user, if possible.

persevere()

If this returns a true value then the handler will continue through its task sequence, and only the present task will be aborted by the exception. This is unlikely to be a good idea.

return_code()

Returns the Apache return code (as one of the constants defined by Apache::Constants) that this error should produce. This may or may not be respected downstream.

INSTANCE METHODS

Useful bits of error message and context.

log_error()

By default just logs to STDERR.

notify_admin()

Uses the factory's email helper to send the error to the configured admin address. This can be sent plain (just the stringified error) or by way of a template, if the configuration parameter 'error_email_template' is set (in which case it will have access to all the usual Error.pm parameters: file, line, stack trace and so on).

message()

Returns the main error message (which corresponds to the -text exception parameter).

errors()

This returns the set of detailed error messages supplied (as the -errors parameter) when the exception was thrown. It will be returned as a list of strings, by reference if called in scalar context.

view()

Returns the name of the view to which we should redirect the user who has encountered this error. Usually login-related. Corresponds to the -view parameter.

handler_url()

Returns the address of the handler passed in as part of the exception. This is normally used as the stem of a redirect instruction.

thing()

Returns the data object that was passed in as part of the exception (using the -object parameter).

type()

Returns the moniker that was passed in as part of the exception (using the -type parameter). This is normally only used for confirmation.

id()

Returns the id value that was passed in as part of the exception (using the -id parameter). This is normally only used for confirmation.

SEE ALSO

Error Class::DBI Class::DBI::Factory Class::DBI::Factory::Handler Class::DBI::Factory::Config Class::DBI::Factory::List

AUTHOR

William Ross, wross@cpan.org

COPYRIGHT

Copyright 2004 William Ross, spanner ltd.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.