moved qdb here because matt is lazy
[public/www-new.git] / pub / qdb / src / modules / Chirpy / UI / WebApp / Session / DataManager.pm
1 ###############################################################################\r
2 # Chirpy! 0.3, a quote management system                                      #\r
3 # Copyright (C) 2005-2007 Tim De Pauw <ceetee@users.sourceforge.net>          #\r
4 ###############################################################################\r
5 # This program is free software; you can redistribute it and/or modify it     #\r
6 # under the terms of the GNU General Public License as published by the Free  #\r
7 # Software Foundation; either version 2 of the License, or (at your option)   #\r
8 # any later version.                                                          #\r
9 #                                                                             #\r
10 # This program is distributed in the hope that it will be useful, but WITHOUT #\r
11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or       #\r
12 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for   #\r
13 # more details.                                                               #\r
14 #                                                                             #\r
15 # You should have received a copy of the GNU General Public License along     #\r
16 # with this program; if not, write to the Free Software Foundation, Inc., 51  #\r
17 # Franklin St, Fifth Floor, Boston, MA  02110-1301  USA                       #\r
18 ###############################################################################\r
19 \r
20 ###############################################################################\r
21 # $Id:: DataManager.pm 291 2007-02-05 21:24:46Z ceetee                      $ #\r
22 ###############################################################################\r
23 \r
24 =head1 NAME\r
25 \r
26 Chirpy::UI::WebApp::Session::DataManager - Abstract data manager class specific\r
27 to L<Chirpy::UI::WebApp::Session|Chirpy::UI::WebApp::Session>\r
28 \r
29 =head1 USAGE\r
30 \r
31 This class is required by L<Chirpy::UI::WebApp|Chirpy::UI::WebApp>'s session\r
32 manager L<Chirpy::UI::WebApp::Session|Chirpy::UI::WebApp::Session>. It is an\r
33 abstract class representing a data manager for session information.\r
34 \r
35 If you wish to create an implementation of this class, the easiest way is to\r
36 extend an existing L<Chirpy::DataManager|Chirpy::DataManager> implementation\r
37 with this class's methods.\r
38 \r
39 The class also has two non-abstract object method, namely\r
40 C<remove_expired_sessions()> and C<remove_expired_sessions_if_necessary()>. The\r
41 former returns a list containing the IDs of the sessions that have expired and\r
42 have consequently been removed. The latter does the same, but only every 24\r
43 hours; otherwise, it returns C<undef>.\r
44 \r
45 =head1 IMPLEMENTATION\r
46 \r
47 If you want to make your L<Chirpy::DataManager|Chirpy::DataManager> compatible\r
48 with L<Chirpy::UI::WebApp::Session|Chirpy::UI::WebApp::Session>, all you need\r
49 to do is implement a few extra object methods for creating, retrieving,\r
50 updating and deleting sessions. You will probably also have to extend your\r
51 C<set_up()> and C<remove()> methods accordingly. The extra methods to implement\r
52 are as follows:\r
53 \r
54 =over 4\r
55 \r
56 =item add_session($id, $data)\r
57 \r
58 Stores the session with ID C<$id> and session data C<$data>. C<$data> is a hash\r
59 reference, so you will probably have to serialize it. How you do that is up to\r
60 you, but L<Data::Dumper> makes it easy. Returns a true value upon success.\r
61 \r
62 =item get_sessions(@ids)\r
63 \r
64 Returns a list containing the data hash for each session whose ID is contained\r
65 in C<@ids>, or all sessions if C<@ids> is empty. If no sessions are found,\r
66 returns an empty list (and I<not> C<undef>).\r
67 \r
68 =item modify_session($id, $data)\r
69 \r
70 Updates the existing session with ID C<$id> with the data from the hash\r
71 referred to by C<$data>.\r
72 \r
73 =item remove_sessions(@ids)\r
74 \r
75 Removes all sessions with an ID contained in C<@ids> from the system. Returns\r
76 the number of removed sessions.\r
77 \r
78 =back\r
79 \r
80 =head1 AUTHOR\r
81 \r
82 Tim De Pauw E<lt>ceetee@users.sourceforge.netE<gt>\r
83 \r
84 =head1 SEE ALSO\r
85 \r
86 L<Chirpy::UI::WebApp::Session>, L<Chirpy::DataManager::MySQL>,\r
87 L<Chirpy::DataManager>, L<Chirpy>, L<http://chirpy.sourceforge.net/>\r
88 \r
89 =head1 COPYRIGHT\r
90 \r
91 Copyright 2005-2007 Tim De Pauw. All rights reserved.\r
92 \r
93 This program is free software; you can redistribute it and/or modify it under\r
94 the terms of the GNU General Public License as published by the Free Software\r
95 Foundation; either version 2 of the License, or (at your option) any later\r
96 version.\r
97 \r
98 This program is distributed in the hope that it will be useful, but WITHOUT ANY\r
99 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A\r
100 PARTICULAR PURPOSE.  See the GNU General Public License for more details.\r
101 \r
102 =cut\r
103 \r
104 package Chirpy::UI::WebApp::Session::DataManager;\r
105 \r
106 use strict;\r
107 use warnings;\r
108 \r
109 use vars qw($VERSION);\r
110 \r
111 use constant CLEANUP_INTERVAL => 24 * 60 * 60;\r
112 \r
113 $VERSION = '0.3';\r
114 \r
115 use Chirpy 0.3;\r
116 use Chirpy::Util 0.3;\r
117 \r
118 sub remove_expired_sessions {\r
119         my $self = shift;\r
120         my @sessions = $self->get_sessions();\r
121         return () unless (@sessions);\r
122         my @remove = ();\r
123         my $time = time;\r
124         foreach my $data (@sessions) {\r
125                 if (my $exp = $data->{'_SESSION_ETIME'}) {\r
126                         my $at = $data->{'_SESSION_ATIME'};\r
127                         next unless ($exp + $at < $time);\r
128                         push @remove, $data->{'_SESSION_ID'};\r
129                 }\r
130         }\r
131         return () unless (@remove);\r
132         $self->remove_sessions(@remove);\r
133         return @remove;\r
134 }\r
135 \r
136 sub remove_expired_sessions_if_necessary {\r
137         my $self = shift;\r
138         my $now = time();\r
139         my $last_cleanup = $self->get_parameter('last_session_cleanup');\r
140         if (!defined $last_cleanup || $last_cleanup + CLEANUP_INTERVAL < $now) {\r
141                 $self->set_parameter('last_session_cleanup', $now);\r
142                 return $self->remove_expired_sessions();\r
143         }\r
144         return undef;\r
145 }\r
146 \r
147 *add_session = \&Chirpy::Util::abstract_method;\r
148 \r
149 *get_sessions = \&Chirpy::Util::abstract_method;\r
150 \r
151 *modify_session = \&Chirpy::Util::abstract_method;\r
152 \r
153 *remove_sessions = \&Chirpy::Util::abstract_method;\r
154 \r
155 1;\r
156 \r
157 ###############################################################################