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 ###############################################################################