FlowPDF-Groovy-lib Exceptions

All out-of-the box exceptions are inherited from the com.cloudbees.flowpdf.exceptions.FlowPDFException

All out of the box exceptions should be created using new() method. Groovy exception classes have 3 different parameters set for new() method. Two of them are the same across all exceptions:

No parameters: new(). Template message will be used as an exception message.
Single string error message: new("This is error message"). Given string will be used as an exception message.
Using hash reference with keys as parameters. This option is described for each exception individually. Note, that not all parameters are required. Keys could be omitted. Special template will be rendered for given values.
Using positional String arguments. Each exception has it’s own arguments.

FlowPDF provides the following exceptions out of the box:

UnexpectedEmptyValue

An exception that could be used when something returned an unexpected undef or empty string.

Keys

where: A description where it happened.
expected: An expected value.

throw new UnexpectedEmptyValue([
   where : 'function sum()',
   expected : 'non-empty value'
])▼

UnexpectedMissingValue

An exception that could be used when the wrapper that should contain a value does not exist.

Keys

where: A description where it happened.
expected: An expected value.

throw new UnexpectedMissingValue([
   where : 'function sum(int a, int b)',
   expected : 'parameter b should not be null'
])▼

MissingFunctionDefinition

An exception, that could be used when class does not have required function defined.

Keys

class: A class where function is missing.
function: A name of the function, that is not implemented (missing).

throw new MissingFunctionDefinition([
   'class'    : 'MyClass',
   'function' : 'mySub'
])▼

MissingFunctionArgument

An exception, that could be used when function expects required parameter, but this parameter is missing.

Keys

argument: An argument, that is missing.
functions: A name of the function, that didn’t receive a mandatory argument.

throw new MissingFunctionArgument([
   argument : 'user name',
   function : 'greetUser'
])▼

WrongFunctionArgumentType

An exception, that could be used when function received an argument, but it has different type.

Keys

item argument: An argument, that has a wrong type.
function: A name of the function, that received an argument of a wrong type.
got: A type of argument that were gotten.
expected: An expected type of an argument.

throw new MissingFunctionArgument([
   argument : 'user name',
   function : 'greetUser',
   got      : 'Integer',
   expected : 'String'
])▼

WrongFunctionArgumentValue

An exception, that could be used when function received an argument, but its value is wrong.

Keys

argument: An argument, that has a wrong value.
function: A name of the function, that received an argument with a wrong value.
got: A value of argument that were gotten.
expected: An expected value of an argument.

throw new WrongFunctionArgumentValue([
   argument : 'user name',
   function : 'greetUser',
   got      : 'Integer',
   expected : 'String'
])▼

EntityDoesNotExist

An exception, that could be used when something does not exist, but it should. Like a key in a Map.

Keys:

entity: An entity, that does not exist.
in: A place, where entity does not exist.
function: A name of the function in context of which entity does not exist.

throw new EntityDoesNotExist([
   entity   : 'key email',
   in       : 'users array',
   function : 'newUser'
])▼

EntityAlreadyExists

An exception, that could be used when something exists, but it should not, like user with the same email.

Keys:

entity: An entity, that already exists.
in: A place, where entity already exists.
function: A name of the function in context of which entity already exists.

throw new EntityAlreadyExists([
   entity   : 'key email',
   in       : 'users array',
   function : 'newUser'
])▼

Creating your own exceptions

To create your own exceptions for a plugin, you need to do the following things:

Inherit FlowPDFException
Define errorCode String field that will be used as code for your exception

class MyException extends FlowPDFException {

  String errorCode = 'CBF0002MFA'

  // Rest of the exception code
}▼

Define render() method. Render method accepts all parameters, that were provided to new() method, but you have to return ready-to-use message. This method is more advanced way of exceptions creation and provides full control. Simple exception using render could be implemented like that:

class SimpleException extends FlowPDFException {

    // Usually it's a 'CBF', 0 padded number of an exception + abbreviation of the exception name
    String errorCode = 'CBF0009SE'

    /** Message that will be shown if no parameters are supplied */
    static String emptyParamsMessage = 'Something has happened.'

    /** What has happened */
    String whatHappened

    /** Where it has happened */
    String whereHappened

    /**
     * Simple message constructor. You can use instead of template (Map or List) ones if you can supply more clarifying
     * message or you don't have any details for exceptional situation.
     * @param message (optional) - Description of the exception, {@link #emptyParamsMessage} will be used if empty.
     */
    SimpleException(String message = emptyParamsMessage) {
        super(message)
    }

    /**
     * Map constructor allows you to set different values for the message template.
     * @param params - Map<String, String> with keys:
     *  - 'what'({@link #whatHappened})
     *  - 'where'({@link #whereHappened})
     */
    SimpleException(Map<String, String> params) {
        this.whatHappened = params['what']
        this.whereHappened = params['where']
    }

    /**
     * Positional arguments constructor allows you to clarify the details.
     * @param what - See {@link #whatHappened}
     * @param where - See {@link #whereHappened}
     */
    SimpleException(String what, String where) {
        this.whatHappened = what
        this.whereHappened = where
    }

    /**
     * Builds an exception message from the initial parameters.
     * @return exception message
     */
    String render() {
        if (whatHappened && whereHappened) {
            return sprintf("%s has happened at %s.", whatHappened, whereHappened)
        } else if (whereHappened) {
            return sprintf("Something has happened at %s.", whereHappened)
        } else if (whatHappened) {
            return sprintf("%s has happened.", whatHappened)
        }

        return emptyParamsMessage
    }
}▼