NAME

OpenInteract::Error - Provide central holding location for Interact errors

SYNOPSIS

 OpenInteract::Error->set( ... );
 $R->throw( ... );

 my $ei = OpenInteract::Error->get;
 print "Last error message: $ei->{system_msg}\n"; 

DESCRIPTION

This class provides a central location for error messages from all Interact modules. The error information collected in these variables is guaranteed to result from the most recent error generated by Interact.

VARIABLES

All of these variables are package variables, so you refer to them like this:

  $OpenInteract::Error::<variable_name>
  $OpenInteract::Error::system_msg

See the NOTES section below for hints on making the error variables shorter.

user_msg ($)

A generic message that is suitable for showing a user. When telling a user something went wrong, you do not want to tell them:

 execute called with 2 bind variables when 1 are needed

instead, you want to tell them:

 Database query failed to execute

This variable is identical to the value thrown by the die() command, so you do not normally need to refer to it.

system_msg ($)

Even though you do not want to show your users details of the error, you still need to know them! The variable system_msg gives you details regarding the error.

type ($)

Interact knows about a few types of errors. Some depend on your Interact implementation (e.g., DBI, dbm, LDAP, etc.). Others can be:

• security: There is a security violation and the action could not be completed.
• config: There was a problem reading/writing configuration information.

package ($)

Set to the package from where the error was thrown.

method ($)

Set to the method from where the error was thrown.

filename ($)

Set to the filename from where the error was thrown.

line ($)

Set to the line number from where the error was thrown.

extra (\%)

Different Interact classes have different information related to the current request. For instance, DBI errors will typically fill the 'sql' and 'values' keys. Other Interact implementations may use different keys; see their documentation for details.

METHODS

clear ()

Clears the current error saved in the class. Classes outside the OpenInteract:: hierarchy should never need to call this.

No return value.

get()

Returns a hashref with all the currently set error values.

set( \%params )

First clears the variables then sets them all in one fell swoop. The variables that are set are passed in the first argument, a hashref. (See VARIABLES for the names and purposes.) Also sets both the package and method variables for you, although you can override by setting manually.

No return value;

throw( \%params )

Throws an error from anywhere in the system. Kept for backward compatibility -- most of the time you will use:

 $R->throw( ... );

We simply pass the parameters (with any caller info) to the method by the same name in the error object class.

NOTES

Some people might find it easier to alias a local package variable to an OpenInteract error variable. For instance, you can do:

 *err_user_msg   = \$OpenInteract::Error::user_msg;
 *err_system_msg = \$OpenInteract::Error::system_msg;
 *err_type       = \$OpenInteract::Error::type;
 *err_extra      = \%OpenInteract::Error::extra;

And then refer to the alias in your local package:

 my $obj_list = eval { $obj->fetch_group( { where => 'this = that' } ) };
 if ( $@ ) {
   warn "Error found! Error: $@\n",
        "Error type: $err_type\n",
        "More specific: $err_system_msg\n", 
        "Extra stuff:\n",
        "--$err_extra{sql}\n",
        "--$err_extra{values}\n";
 }

TO DO

Nothing known.

BUGS

None known.

COPYRIGHT

Copyright (c) 2001-2002 intes.net, inc.. All rights reserved.

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

AUTHORS

Chris Winters <chris@cwinters.com>