Welcome To Our Shell

Mister Spy & Souheyl Bypass Shell

Exceptions Usage Within OptiCm
==============================

First: Try to avoid throwing an exception if possible

Second: If you need to throw an exception, see the 'OptiCm::Object Exceptions' section below

TODO's:
=======

    TODO: Riehm 2011-03-02 describe the exception structure
    TODO: Riehm 2011-03-02 describe exception behaviours
    TODO: Riehm 2011-03-02 describe the circumstances under which exceptions should be thrown
    TODO: Riehm 2011-03-02 describe how exceptions should be thrown
    TODO: Riehm 2011-03-02 describe how exceptions should be caught

General Tips Regarding Exceptions:
==================================

    Exceptions are exceptional:
        Only throw exceptions if the current routine no longer makes sense and
        there is no other fall-back processing available.
        An exception explicitly states that the current routine will be
        immediately aborted and execution will only continue at the next
        exception handler in the stack - if all else fails, this will even
        cause your program to crash.

        So don't use too many exceptions!

        Situations suitable for exceptions:
            cannot connect to database
            could not perform an external action (e.g.: create view)

        Non Exceptions:
            trying to remove a non-existent item from a list

        Note:
            often, it will make sense to have 'undefined' or incomplete
            objects. Since an object often encapsulates the state of a
            particular 'thing', the object should also be able to indicate that
            the 'thing' doesn't exist etc. Cases like this are NOT exceptions
            and should be handled by queries on the object.
            e.g.:
                my $object = Class->new( ... );
                if( $object->exists() and $object->isOk() ) { ... }
                elsif( $object->isBroken() ) { ... }
                else { ... }

        Alternatives to exceptions:
            always return values, undef is also a value and it is not the same as 0 or ""
            split actions into checkers and performers:
                checkers:
                    routines which perform complex checks and return simple
                    yes/no/maybe answers
                performers:
                    routines which actually change state in some way. These
                    routines may assume that all validation checks have been
                    successfully passed.

        CAUTION:
            perl's implementation of exceptions breaks a few assumptions that
            perl develeopers regularly rely on.
            This is especially true of function parameters and return values!

            For example, the following routine is broken in three ways!:

                sub someFunc {
                    my $firstParam = shift;
                    try { doSomethingWithSecondParam( shift ); } catch { return 0; }
                    doSomethingElse();
                    return 1;
                }

            First problem:
                doSomethingWithSecondParam( shift ) will get an undefined value
                because the try block defines an anonymous block, which
                implicitly gets its own @_.

                Fix this by always capturing all parameters first.

                    sub someFunc {
                        my $firstParam  = shift;
                        my $secondParam = shift;
                        try { doSomethingWithSecondParam( $secondParam ); } catch ...
                        ...

            Second problem:
                the catch { return 0; } block also defines an anonymous subroutine.
                This means that the return 0 does NOT terminate the surrounding function, just the catch block!
                As a result, it APPEARS that if an exception was caught, the
                routine is terminated (thus skipping doSomethingElse()),
                however, in reality, doSomethingElse() will ALWAYS be run.

                Fix this by checking the return code of the try statement:

                    return  unless try { doSomethingWithSecondParam( $secondParam ); 1; } catch { 0; };
                    doSomethingElse();

            Third problem:
                A try {} catch {} statement is actually just a try statement
                which expects two (or more) anonymous routines.
                As a result, a trailing ; is required - which looks a bit strange, and is also counter intuitive.

                Correct:

                    try {
                        ...
                    }
                    catch {
                        ...
                    };          # <<==-- semicolon here is REQUIRED!

OptiCm::Object Exceptions
=========================

    OptiCm::Object defines a single exception class, OptiCm::Exception, and
    provides a very simple method for throwing exceptions when needed.

    Let's assume a really simple class derived from OptiCm::Object:

        package MyClass;
        parent qw( OptiCm::Object );

    Now, if I have an instance of such an object, I can throw an exception like this:

        my $object = MyClass->new();
        $object->throwSimpleException( message => 'I give up' );

    That's all there is to it for most situations.

    Of course you can throw more 'complex' exceptions, however, you will just
    be making your own life more miserable... and you might just hurt a kitten!

--
Stephen Riehm
2011-03-02