NAME

SPOPS::Manual::Exceptions - Error handling in SPOPS

SYNOPSIS

This document describes SPOPS exceptions, their composition, how they're used and how you can create your own. See SPOPS::Exception for more concrete implementation details.

DESCRIPTION

Error handling in SPOPS is fairly straightforward. Most (if not all) methods that can encounter some sort of error let the caller know about the error by throwing a "die". The error thrown is actually a SPOPS::Exception object or one of its subclasses.

The object can be placed directly into a string and it will do the Right Thing, displaying the message it was assigned. You can also query the object for additional information about the lcoation the object was thrown. Subclasses can have additional information in the object as well.

The base object properties used are:

message

This is the message the exception is created with -- there should be one with every exception. (It is bad form to throw an exception with no message.)

package

The package the exception was thrown from.

filename

The file the exception was thrown from.

line

The line number in "filename" the exception was thrown from.

method

The subroutine the exception was thrown from.

trace

Returns a Devel::StackTrace object. If you set a package variable 'ShowTrace' in your exception then the output of "to_string()" (along with the stringification output) will include the stack trace output as well as the message.

This output may produce redundant messages in the default "to_string()" method -- just override the method in your exception class if you want to create your own output. (See SPOPS::Exception::Security for an example of this.)

SUBCLASSING

Creating your own exceptions is very easy -- all you need to do is subclass SPOPS::Exception. If you want additional properties in the exception, two or three lines will create them for you. And performing custom initialization is similarly easy.

Here's an example of a subclass:

  1: package MyApplication::Exception
  2: 
  3: use strict;
  4: use base qw( SPOPS::Exception );
  5: 
  6: my @FIELDS = qw( epoch_time business_action );
  7: MyApplication::Exception->mk_accessors( @FIELDS );
  8: sub get_fields { return ( $_[0]->SUPER::get_fields, @FIELDS ) }
  9: 
 10: sub initialize { $_[0]->epoch_time( time ) }
 11: 
 12: 1;

The purpose of this should be plain -- we're creating a new exception for our application with two additional properties, 'epoch_time' and 'business_action', and initializing 'epoch_time' to the current time when the exception is created.

Here's how you might use it in your object:

  1: package My::Object;
  2: 
  3: use strict;
  4: use MyApplication::Exception;
  5: 
  6: my @BADWORDS = qw( pr0n );
  7: 
  8: sub find_relevant_links {
  9:     my ( $self ) = @_;
 10:     my @words_found = grep { $self->{content} =~ /$_/ } @BADWORDS;
 11:     if ( scalar @words_found ) {
 12:         my $msg = "Cannot find relevant links -- bad words found: " .
 13:                   "[" . join( ", ", @words_found ) . "]";
 14:         MyApplication::Exception->throw(
 15:                $msg, { business_action => 'determine links from object' } );
 16:     }
 17:     ...
 18: }

And then an example of handling it from code that uses the object:

  1: my ( $object, $links );
  2: eval { 
  3:     $object = My::Object->fetch( $id );
  4:     $links = $object->find_relevant_links;
  5: };
  6: if ( $@ and $@->isa( 'MyApplication::Exception' ) ) {
  7:     print "Error trying to ", $@->business_action(), ": $@";
  8: }
  9: elsif ( $@ ) {
 10:     print "Database error: $@";
 11: }
 12: else {
 13:     print join( ", ",  @{ $links } );
 14: }

EXAMPLES

Here is a simple example trying to fetch an object and filtering the error returned to see if it's a security error:

  1: my $news_id = $q->param( 'news_id' );
  2: my $news = eval { My::News->fetch( $news_id ) };
  3: if ( $@ ) {
  4:     log_error( $@ );
  5:     if ( $@->isa( 'SPOPS::Exception::Security' ) ) {
  6:         print "Cannot retrieve News article -- insufficient security access.";
  7:     }
  8:     else {
  9:         print "Cannot retrieve News article! (Error: $@) Please ",
 10:               "contact administrator.";
 11:     }
 12: }
 13: else {
 14:     print "$news->{title}\n$news->{posted_on}\n$news->{content}\n";
 15: }

Shortcuts

Every SPOPS exception module exports a shortcut. Instead of using the format:

 use SPOPS::Exception;
 ...
 SPOPS::Exception->throw( $msg, \%params );

You can use:

 use SPOPS::Exception qw( spops_error );
 ...
 spops_error $msg, \%params;

The shortcuts exported are:

SPOPS::Exception: "spops_error"

SPOPS::Exception::DBI: "spops_dbi_error"

SPOPS::Exception::LDAP: "spops_ldap_error"

SPOPS::Exception::Security: "spops_security_error"

COPYRIGHT

See SPOPS::Manual for license.

AUTHORS

Chris Winters <chris@cwinters.com>