Object::Relation::Exceptions - Object::Relation exception object definitions
use Object::Relation::Exceptions ':all'; throw_fatal 'Whoops!'; # The error is fully localizable. throw_fatal ['Unknown value "[_1]"', 'foo'];
This class defines Object::Relation exception objects. It subclasses Exception::Class, which provides a robust exception implementation. It extends Exception::Class by requiring localizable error messages. All error messages must be represented in the appropriate Object::Relation::Language lexicons.
There currently four major classes of exceptions:
This class and its subclasses represent fatal, non-recoverable errors. Exceptions of this sort are unexpected, and should be reported to an administrator or to the Object::Relation developers.
This class and its subclasses represent non-fatal errors triggered by invalid data. These can be used to let users know that the data they've entered is invalid.
This class will never has its error message localized. This is so that it can be thrown by libraries not under direct Object::Relation control and therefore are not localizable. This class is also used for the global $SIG{__DIE__} handler, so that exceptions always include a nicely formatted stack trace.
$SIG{__DIE__}
This class is used solely for handling exceptions thrown by DBI. You should never need to access it directly.
The exception classes generated by this module are as follows:
Object::Relation exception base class. It generally should not be thrown, only its subclasses.
Base class for fatal exceptions. Alias: throw_fatal.
throw_fatal
Invalid data exception. Thrown when an invalid value is assigned to a Object::Relation class attribute. Alias: throw_invalid.
throw_invalid
ReadOnly exception. Thrown when an someone attempts to assign a value to a read-only attribute. Alias: throw_read_only.
throw_read_only
Localization exception. Thrown if an error is encountered while attempting to localize a string. Alias: throw_lang.
throw_lang
File status exception. Thrown if an error is encountered while attempting to stat a file. Alias: throw_stat.
throw_stat
IO exception. Thrown if an error is encountered while attempting to read or write to a file. Alias: throw_io.
throw_io
Unimplemented exception. Thrown if a feature has not yet been implemented or must be overridden in a subclass. Alias: throw_unimplemented.
throw_unimplemented
Missing arguments exception. Thrown if required arguments to a method are not present. Alias: throw_required.
throw_required
Object Not Found exception. Thrown if something searched for is not found. Usually this is for objects in data stores, but also might be used for anything that is being looked for (such as a file). Alias: throw_not_found.
throw_not_found
Alias: throw_not_found.
Unsupported feature exception. Thrown if code attempts to use an unsupported feature. Alias: throw_unsupported.
throw_unsupported
XML parse exception. Thrown if a problem is found parsing XML. Alias: throw_xml.
throw_xml
Invalid class exception. Thrown if an incorrect class is encountered. Alias: throw_invalid_class.
throw_invalid_class
Invalid attribute exception. Thrown if an incorrect attribute is encountered. Alias: throw_invalid_attr.
throw_invalid_attr
Unknown class exception. Thrown if an unknown class is encountered. Alias: throw_unknown_class.
throw_unknown_class
Object::Relation attribute exception. Thrown if a Object::Relation attribute is used incorrectly, such as "unknown attributes" or trying to use a non-unique attribute where a unique attribute would be used. Alias: throw_attribute.
throw_attribute
Store search exception. Thrown if data store cannot figure out how to respond to a search request. Alias: throw_search.
throw_search
Setup exception. Thrown if there is an error when setting up a data store. Alias: throw_setup.
throw_setup
Panic exception. This internal exception should (theoretically) never be thrown. It only occurs if the internal state of something has reached a point that cannot occur. For example, an "ANY" search in a store class can only occur if the values searched on are contained in an array reference. If an ANY search occurs and the values are not an array reference, a panic is thrown. Alias: panic.
panic
Base class for error exceptions. These are non-fatal errors, generally triggered by problems with data entered by users. Alias: throw_error.
throw_error
Authentication failure. Thrown when authentication fails. Alias: throw_auth.
throw_auth
Class for exceptions thrown external to Object::Relation code. Exceptions of this class behave just like any other Object::Relation exception objects, except that error messages are not localized. Alias: throw_exlib.
throw_exlib
In addition to the functions that can be imported to throw the above exceptions, there are a few other functions that may be imported into a client class.
if (isa_obj_rel_exception($@)) print 'A Object::Relation exception was thrown'; print "...and it was fatal!' if isa_obj_rel_exception($@, 'Fatal'); }
This function returns true if the argument passed to it is a Object::Relation exception. The optional second argument can be used to test for a specific Object::Relation exception. If no such exception exists, an exception will be thrown.
if (isa_exception($@)) { print "What we have here...is an exception object"; }
This function returns true if the argument passed to it is an Exception::Class object.
sig_handlers(0);
This function accepts a boolean value. If true, it turns on stack traces via the DIE signal handler. If false, it disables them. If called without arguments, it merely returns a boolean value indicating whether or not the signal handlers are enabled.
my $err = Object::Relation::Exception->new("Whoops!"); my $err = Object::Relation::Exception->new(error => 'Whoops!'); my $err = Object::Relation::Exception->new(['Unknown value "[_1]"', 'foo']); my $err = Object::Relation::Exception->new( error => ['Unknown value "[_1]"', 'foo'] );
Creates and returns a new exception object. Use this method with die to throw exceptions yourself, or if you don't want to import any throw_ functions into your namespace. Otherwise, a throw_ function is generally the preferred way to throw an exception. Besides, it requires less typing!
die
throw_
The base class supports only a single parameter, error, for the exception error message. If only a single argument is passed to new(), it is assumed to be the error parameter. Other exception classes may support other parameters; consult their <descriptions|"Exception Classes"> for details. All throw_ functions for the exception subclasses support the parameters that correspond to their respective classes.
error
new()
my $string $err->as_string;
Returns a stringified representation of the exception, which includes the full error message and the stack trace. The method overrides stringification (double-quoted string context), so its return value is output whenever an exception object is printed.
We override the base class version of this method in order to provide a nicer, more legible stack trace, rather than the default Carp-style trace.
my $trace = $err->trace_as_text;
Returns a stringified representation of the stack trace for the exception object. Used by as_string() to pretty-print the stack trace.
as_string()
Copyright (c) 2004-2006 Kineticode, Inc. <info@obj_relode.com>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Object::Relation, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Object::Relation
CPAN shell
perl -MCPAN -e shell install Object::Relation
For more information on module installation, please visit the detailed CPAN module installation guide.