GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
SPOPS::Manual::Exceptions(3) User Contributed Perl Documentation SPOPS::Manual::Exceptions(3)
 

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

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.

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.)

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: }

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: }

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 (c) 2001-2004 Chris Winters. All rights reserved.
See SPOPS::Manual for license.

Chris Winters <chris@cwinters.com>
2004-06-02 perl v5.28.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.