#######
Invoker
#######


****
NAME
****


Kernel::GenericInterface::Invoker - GenericInterface Invoker interface


***********
DESCRIPTION
***********


Invokers are responsible to prepare for making a remote web service
request.

For every Request, two methods are called:


- `PrepareRequest()`_



- `HandleResponse()`_



The first method prepares the response and can prevent it by returning
an error state. The second method must always be called if the request
was initiated to allow the Invoker to handle possible errors.


****************
PUBLIC INTERFACE
****************


new()
=====


create an object.


.. code-block:: perl

     use Kernel::GenericInterface::Debugger;
     use Kernel::GenericInterface::Invoker;
 
     my $DebuggerObject = Kernel::GenericInterface::Debugger->new(
         DebuggerConfig   => {
             DebugThreshold => 'debug',
             TestMode       => 0,           # optional, in testing mode the data will not be written to the DB
             # ...
         },
         WebserviceID      => 12,
         CommunicationType => Requester, # Requester or Provider
         RemoteIP          => 192.168.1.1, # optional
     );
     my $InvokerObject = Kernel::GenericInterface::Invoker->new(
         DebuggerObject     => $DebuggerObject,
         Invoker            => 'TicketLock',            # the name of the invoker in the web service
         InvokerType        => 'Nagios::TicketLock',    # the Invoker backend to use
         WebserviceID       => 1                        # the WebserviceID where the Invoker belongs
                                                        # normally this is passed by the requester
     );



PrepareRequest()
================


prepare the invocation of the configured remote web service.


.. code-block:: perl

     my $Result = $InvokerObject->PrepareRequest(
         Data => {                               # data payload
             ...
         },
     );
 
     $Result = {
         Success         => 1,                   # 0 or 1
         ErrorMessage    => '',                  # in case of error
         Data            => {                    # data payload after Invoker
             ...
         },
     };
 
     $Result = {
         Success           => 1,                 # 0 or 1
         StopCommunication => 1,                 # in case of is not needed to continue with the
                                                 # request (do nothing just exist gracefully)
     };



HandleResponse()
================


handle response data of the configured remote web service.


.. code-block:: perl

     my $Result = $InvokerObject->HandleResponse(
         ResponseSuccess      => 1,              # success status of the remote web service
         ResponseErrorMessage => '',             # in case of web service error
         Data => {                               # data payload
             ...
         },
     );
 
     $Result = {
         Success         => 1,                   # 0 or 1
         ErrorMessage    => '',                  # in case of error
         Data            => {                    # data payload after Invoker
             ...
         },
     };



HandleError()
=============


handle error data of the configured remote web service.


.. code-block:: perl

     my $Result = $InvokerObject->HandleError(
         Data => {                               # data payload
             ...
         },
     );
 
     $Result = {
         Success         => 1,                   # 0 or 1
         ErrorMessage    => '',                  # in case of error
         Data            => {                    # data payload after Invoker
             ...
         },
     };