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::System::Storable;
10
11use strict;
12use warnings;
13
14use Storable qw();
15
16our @ObjectDependencies = (
17    'Kernel::System::Log',
18);
19
20=head1 NAME
21
22Kernel::System::Storable - Storable wrapper functions
23
24=head1 DESCRIPTION
25
26Functions for Storable serialization / deserialization.
27
28
29=head2 new()
30
31create a Storable object. Do not use it directly, instead use:
32
33    my $StorableObject = $Kernel::OM->Get('Kernel::System::Storable');
34
35=cut
36
37sub new {
38    my ( $Type, %Param ) = @_;
39
40    # allocate new hash for object
41    my $Self = {};
42    bless( $Self, $Type );
43
44    return $Self;
45}
46
47=head2 Serialize()
48
49Dump a Perl data structure to an storable string.
50
51    my $StoableString = $StorableObject->Serialize(
52        Data => $Data,          # must be a reference,
53        Sort => 1,              # optional 1 or 0, default 0
54    );
55
56=cut
57
58sub Serialize {
59    my ( $Self, %Param ) = @_;
60
61    # check for needed data
62    if ( !defined $Param{Data} ) {
63        $Kernel::OM->Get('Kernel::System::Log')->Log(
64            Priority => 'error',
65            Message  => 'Need Data!',
66        );
67        return;
68    }
69
70    if ( !ref $Param{Data} ) {
71        $Kernel::OM->Get('Kernel::System::Log')->Log(
72            Priority => 'error',
73            Message  => 'Data needs to be given as a reference!',
74        );
75        return;
76    }
77
78    local $Storable::canonical = $Param{Sort} ? 1 : 0;
79
80    my $Result;
81    eval {
82        $Result = Storable::nfreeze( $Param{Data} );
83    };
84
85    # error handling
86    if ($@) {
87        $Kernel::OM->Get('Kernel::System::Log')->Log(
88            Priority => 'error',
89            Message  => "Error serializing data: $@",
90        );
91        return;
92    }
93
94    return $Result;
95}
96
97=head2 Deserialize()
98
99Load a serialized storable string to a Perl data structure.
100
101    my $PerlStructureScalar = $StorableObject->Deserialize(
102        Data => $StorableString,
103    );
104
105=cut
106
107sub Deserialize {
108    my ( $Self, %Param ) = @_;
109
110    # check for needed data
111    return if !defined $Param{Data};
112
113    # read data structure back from file dump, use block eval for safety reasons
114    my $Result;
115    eval {
116        $Result = Storable::thaw( $Param{Data} );
117    };
118
119    # error handling
120    if ($@) {
121        $Kernel::OM->Get('Kernel::System::Log')->Log(
122            Priority => 'error',
123            Message  => "Error deserializing data: $@",
124        );
125        return;
126    }
127
128    return $Result;
129}
130
131=head2 Clone()
132
133Creates a deep copy a Perl data structure.
134
135    my $StorableData = $StorableObject->Clone(
136        Data => $Data,          # must be a reference
137    );
138
139=cut
140
141sub Clone {
142    my ( $Self, %Param ) = @_;
143
144    # check for needed data
145    if ( !defined $Param{Data} ) {
146        $Kernel::OM->Get('Kernel::System::Log')->Log(
147            Priority => 'error',
148            Message  => 'Need Data!',
149        );
150        return;
151    }
152
153    if ( !ref $Param{Data} ) {
154        $Kernel::OM->Get('Kernel::System::Log')->Log(
155            Priority => 'error',
156            Message  => 'Data needs to be a reference!',
157        );
158        return;
159    }
160
161    my $Result;
162    eval {
163        $Result = Storable::dclone( $Param{Data} );
164    };
165
166    # error handling
167    if ($@) {
168        $Kernel::OM->Get('Kernel::System::Log')->Log(
169            Priority => 'error',
170            Message  => "Error cloning data: $@",
171        );
172        return;
173    }
174
175    return $Result;
176}
177
1781;
179
180=head1 TERMS AND CONDITIONS
181
182This software is part of the OTRS project (L<https://otrs.org/>).
183
184This software comes with ABSOLUTELY NO WARRANTY. For details, see
185the enclosed file COPYING for license information (GPL). If you
186did not receive this file, see L<https://www.gnu.org/licenses/gpl-3.0.txt>.
187
188=cut
189