1# --
2# Copyright (C) 2001-2020 OTRS AG, https://otrs.com/
3# --
4# This software comes with ABSOLUTELY NO WARRANTY. For details, see
5# the enclosed file COPYING for license information (GPL). If you
6# did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.
7# --
8
9package Kernel::GenericInterface::Transport;
10
11use strict;
12use warnings;
13
14# prevent 'Used once' warning for Kernel::OM
15use Kernel::System::ObjectManager;
16
17our $ObjectManagerDisabled = 1;
18
19=head1 NAME
20
21Kernel::GenericInterface::Transport - GenericInterface network transport interface
22
23=head1 PUBLIC INTERFACE
24
25=head2 new()
26
27create an object.
28
29    use Kernel::GenericInterface::Debugger;
30    use Kernel::GenericInterface::Transport;
31
32    my $DebuggerObject = Kernel::GenericInterface::Debugger->new(
33        DebuggerConfig   => {
34            DebugThreshold  => 'debug',
35            TestMode        => 0,           # optional, in testing mode the data will not be written to the DB
36            # ...
37        },
38        WebserviceID      => 12,
39        CommunicationType => Requester, # Requester or Provider
40        RemoteIP          => 192.168.1.1, # optional
41    );
42    my $TransportObject = Kernel::GenericInterface::Transport->new(
43        DebuggerObject => $DebuggerObject,
44        TransportConfig => {
45            Type => 'HTTP::SOAP',
46            Config => {
47                ...
48            },
49        },
50    );
51
52=cut
53
54sub new {
55    my ( $Type, %Param ) = @_;
56
57    my $Self = {};
58    bless( $Self, $Type );
59
60    for my $Needed (qw( DebuggerObject TransportConfig)) {
61        $Self->{$Needed} = $Param{$Needed} || return {
62            Success => 0,
63            Summary => "Got no $Needed!",
64        };
65    }
66
67    # select and instantiate the backend
68    my $Backend = 'Kernel::GenericInterface::Transport::' . $Self->{TransportConfig}->{Type};
69
70    if ( !$Kernel::OM->Get('Kernel::System::Main')->Require($Backend) ) {
71        return $Self->{DebuggerObject}->Error( Summary => "Backend $Backend not found." );
72    }
73    $Self->{BackendObject} = $Backend->new( %{$Self} );
74
75    # if the backend constructor failed, it returns an error hash, pass it on in this case
76    return $Self->{BackendObject} if ref $Self->{BackendObject} ne $Backend;
77
78    return $Self;
79}
80
81=head2 ProviderProcessRequest()
82
83process an incoming web service request. This function has to read the request data
84from the web server process.
85
86    my $Result = $TransportObject->ProviderProcessRequest();
87
88    $Result = {
89        Success         => 1,                   # 0 or 1
90        ErrorMessage    => '',                  # in case of error
91        Operation       => 'DesiredOperation',  # name of the operation to perform
92        Data            => {                    # data payload of request
93            ...
94        },
95    };
96
97=cut
98
99sub ProviderProcessRequest {
100    my ( $Self, %Param ) = @_;
101
102    my $Result = $Self->{BackendObject}->ProviderProcessRequest(%Param);
103
104    # make sure an operation is provided in success case
105    if ( $Result->{Success} && !$Result->{Operation} ) {
106
107        return $Self->{DebuggerObject}->Error(
108            Summary => 'TransportObject backend did not return an operation',
109        );
110    }
111
112    return $Result;
113}
114
115=head2 ProviderGenerateResponse()
116
117generate response for an incoming web service request.
118
119    my $Result = $TransportObject->ProviderGenerateResponse(
120        Success         => 1,       # 1 or 0
121        ErrorMessage    => '',      # in case of an error, optional
122        Data            => {        # data payload for response, optional
123            ...
124        },
125
126    );
127
128    $Result = {
129        Success         => 1,                   # 0 or 1
130        ErrorMessage    => '',                  # in case of error
131    };
132
133=cut
134
135sub ProviderGenerateResponse {
136    my ( $Self, %Param ) = @_;
137
138    if ( !defined $Param{Success} ) {
139
140        return $Self->{DebuggerObject}->Error(
141            Summary => 'Missing parameter Success.',
142        );
143    }
144
145    if ( $Param{Data} && ref $Param{Data} ne 'HASH' ) {
146
147        return $Self->{DebuggerObject}->Error(
148            Summary => 'Data is not a hash reference.',
149        );
150    }
151
152    return $Self->{BackendObject}->ProviderGenerateResponse(%Param);
153}
154
155=head2 RequesterPerformRequest()
156
157generate an outgoing web service request, receive the response and return its data..
158
159    my $Result = $TransportObject->RequesterPerformRequest(
160        Operation       => 'remote_op', # name of remote operation to perform
161        Data            => {            # data payload for request
162            ...
163        },
164    );
165
166    $Result = {
167        Success         => 1,                   # 0 or 1
168        ErrorMessage    => '',                  # in case of error
169        Data            => {
170            ...
171        },
172    };
173
174=cut
175
176sub RequesterPerformRequest {
177    my ( $Self, %Param ) = @_;
178
179    if ( !$Param{Operation} ) {
180
181        return $Self->{DebuggerObject}->Error(
182            Summary => 'Missing parameter Operation.',
183        );
184    }
185
186    if ( $Param{Data} && ref $Param{Data} ne 'HASH' ) {
187
188        return $Self->{DebuggerObject}->Error(
189            Summary => 'Data is not a hash reference.',
190        );
191    }
192
193    return $Self->{BackendObject}->RequesterPerformRequest(%Param);
194}
195
1961;
197
198=head1 TERMS AND CONDITIONS
199
200This software is part of the OTRS project (L<https://otrs.org/>).
201
202This software comes with ABSOLUTELY NO WARRANTY. For details, see
203the enclosed file COPYING for license information (GPL). If you
204did not receive this file, see L<https://www.gnu.org/licenses/gpl-3.0.txt>.
205
206=cut
207