view release on metacpan or  search on metacpan

lib/App/CamelPKI/Error.pm  view on Meta::CPAN

  };

=for My::Tests::Below "synopsis basic" end

=for My::Tests::Below "synopsis Class::Facet" begin

  package My::Facet;
  use Class::Facet from => "My::Object",
                   on_error => \&App::CamelPKI::Error::Privilege::on_facet_error;

=for My::Tests::Below "synopsis Class::Facet" end

=head1 DESCRIPTION

This class leverages the L<Error> module, by the excellent Graham Barr
and his buddies, to implement error management in Camel-PKI.

Unlike I<Error>, I<try>, I<with>, I<finally>, I<except> and
I<otherwise> symbols are exported by default: no need to say C<< use
Error qw(:try); >> to import these.

=cut

use Error qw(:try);
use base "Error";
use base "Exporter";
our %EXPORT_TAGS=%Error::subs::EXPORT_TAGS;
our @EXPORT_OK=map { @$_ } (values %EXPORT_TAGS);
our @EXPORT=@{$EXPORT_TAGS{try}};
{
    no warnings "once";
    *import = \&Exporter::import; # Stupid Error.pm redefines its own
                                  # ->import()
}

=head2 App::CamelPKI::Error::Internal

Thrown when a programing issue occurs (for example when not respecting the
documented API, using a bad number of arguments, ...).

=cut

package App::CamelPKI::Error::Internal;
use vars qw(@ISA); @ISA=qw(App::CamelPKI::Error);

=head2 App::CamelPKI::Error::IO

Thrown when a file issue occurs. The incriminated file name must be passed
as the parameter C<-IOfile>, for example.

=for My::Tests::Below "App::CamelPKI::Error::IO" begin

    throw App::CamelPKI::Error::IO("cannot open file",
                              -IOfile => $file);

=for My::Tests::Below "App::CamelPKI::Error::IO" end

The ->{-errorcode} field will be automatically set with the numerical
value of $!  (see L</perlvar>) when the error is thrown.  The
->{-error} field will be automatically set whith the textual value of
this same variable; note that this value depends on the active locale
and therefore should not be tested by error catching code.

=cut

package App::CamelPKI::Error::IO;
use vars qw(@ISA); @ISA=qw(App::CamelPKI::Error);

sub new {
    my $class = shift;
    local $Error::Depth = $Error::Depth + 1;
    return $class->SUPER::new(@_,
                              -errorcode => $! + 0, -error => "$!");
}

=head2 App::CamelPKI::Error::Privilege

Thrown each time the owner of a facet, another object or a class with
restricted privileges, try to exceeds those which were granted to it.
To this effect, the I<App::CamelPKI::Error::Privilege> also defines a
B<on_facet_error> function that can be installed as a L<Class::Facet>
error handler, as shown in L</SYNOPSIS>.

=cut

package App::CamelPKI::Error::Privilege;
use vars qw(@ISA); @ISA=qw(App::CamelPKI::Error);

sub on_facet_error {
    shift; # Off with the class name
    throw App::CamelPKI::Error::Privilege(-text => "Facet error", @_);
}

=head2 App::CamelPKI::Error::Database

Thrown when an Camel-PKI database (typically L<App::CamelPKI::CADB>) detects
an error at the SQL level, as an invariant violation tentative or
an insert of two values for an unique index.

=cut

package App::CamelPKI::Error::Database;
use vars qw(@ISA); @ISA=qw(App::CamelPKI::Error);

=head2 App::CamelPKI::Error::State

Thrown when a Camel-PKI object or class is in a state which cannot be handled
correctly (for example, private key and certificate already present on disk
for a non corresponding service), or an asked operation which is no yet or
anymore possible to perform (for example when L<App::CamelPKI::CA> ask for a
certificate generation when the AC key and certificate are not regulated).

=cut

package App::CamelPKI::Error::State;
use vars qw(@ISA); @ISA=qw(App::CamelPKI::Error);

=head2 App::CamelPKI::Error::OtherProcess

Thrown in case of an error in the communication with an external
process (for example failling to start an instance of