Annotation of loncom/LONCAPA.pm, revision 1.16
1.1 albertel 1: # The LearningOnline Network
2: # Base routines
3: #
1.16 ! albertel 4: # $Id: LONCAPA.pm,v 1.15 2006/11/27 16:34:38 albertel Exp $
1.1 albertel 5: #
6: # Copyright Michigan State University Board of Trustees
7: #
8: # This file is part of the LearningOnline Network with CAPA (LON-CAPA).
9: #
10: # LON-CAPA is free software; you can redistribute it and/or modify
11: # it under the terms of the GNU General Public License as published by
12: # the Free Software Foundation; either version 2 of the License, or
13: # (at your option) any later version.
14: #
15: # LON-CAPA is distributed in the hope that it will be useful,
16: # but WITHOUT ANY WARRANTY; without even the implied warranty of
17: # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18: # GNU General Public License for more details.
19: #
20: # You should have received a copy of the GNU General Public License
21: # along with LON-CAPA; if not, write to the Free Software
22: # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23: #
24: # /home/httpd/html/adm/gpl.txt
25: #
26: # http://www.lon-capa.org/
27: #
28: ###
29:
30: package LONCAPA;
31:
32: use strict;
1.2 www 33: use lib '/home/httpd/lib/perl/';
34: use LONCAPA::Configuration;
35: use Fcntl qw(:flock);
36: use GDBM_File;
37: use POSIX;
38:
39: my $loncapa_max_wait_time = 13;
40:
1.14 albertel 41:
42: use vars qw($match_domain $match_not_domain
43: $match_username $match_not_username
1.16 ! albertel 44: $match_courseid $match_not_courseid
! 45: $match_name
1.14 albertel 46: $match_handle $match_not_handle);
47:
1.1 albertel 48: require Exporter;
49: our @ISA = qw (Exporter);
1.14 albertel 50: our @EXPORT = qw(&add_get_param &escape &unescape
51: &tie_domain_hash &untie_domain_hash &tie_user_hash
52: &untie_user_hash &propath);
53: our @EXPORT_OK = qw($match_domain $match_not_domain
54: $match_username $match_not_username
1.16 ! albertel 55: $match_courseid $match_not_courseid
! 56: $match_name
1.14 albertel 57: $match_handle $match_not_handle);
58: our %EXPORT_TAGS = ( 'match' =>[qw($match_domain $match_not_domain
59: $match_username $match_not_username
1.16 ! albertel 60: $match_courseid $match_not_courseid
! 61: $match_name
1.14 albertel 62: $match_handle $match_not_handle)],);
1.2 www 63: my %perlvar;
1.1 albertel 64:
1.8 foxr 65:
66:
1.2 www 67: # Inputs are a url, and a hash ref of
1.1 albertel 68: # form name => value pairs
69: # takes care of properly adding the form name elements and values to the
70: # the url doing proper escaping of the values and joining with ? or & as
71: # needed
72:
73: sub add_get_param {
74: my ($url,$form_data) = @_;
75: my $needs_question_mark = ($url !~ /\?/);
76:
77: while (my ($name,$value) = each(%$form_data)) {
78: if ($needs_question_mark) {
79: $url.='?';
80: $needs_question_mark = 0;
81: } else {
82: $url.='&';
83: }
84: $url.=$name.'='.&escape($form_data->{$name});
85: }
86: return $url;
87: }
88:
89: # -------------------------------------------------------- Escape Special Chars
90:
91: sub escape {
92: my $str=shift;
93: $str =~ s/(\W)/"%".unpack('H2',$1)/eg;
94: return $str;
95: }
96:
97: # ----------------------------------------------------- Un-Escape Special Chars
98:
99: sub unescape {
100: my $str=shift;
101: $str =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C",hex($1))/eg;
102: return $str;
103: }
104:
1.14 albertel 105: $match_domain = $LONCAPA::domain_re = qr{[\w\-.]+};
106: $match_not_domain = $LONCAPA::not_domain_re = qr{[^\w\-.]+};
107: sub clean_domain {
108: my ($domain) = @_;
109: $domain =~ s/$match_not_domain//g;
110: return $domain;
111: }
112:
1.16 ! albertel 113: $match_username = $LONCAPA::username_re = qr{[^a-zA-Z\_][\w\-.]+};
1.14 albertel 114: $match_not_username = $LONCAPA::not_username_re = qr{[^\w\-.]+};
115: sub clean_username {
116: my ($username) = @_;
1.16 ! albertel 117: $username =~ s/^\d+//;
1.14 albertel 118: $username =~ s/$match_not_username//g;
119: return $username;
120: }
121:
1.16 ! albertel 122:
! 123: $match_courseid = $LONCAPA::courseid_re = qr{\d[\w\-.]+};
! 124: $match_not_courseid = $LONCAPA::not_courseid_re = qr{[^\w\-.]+};
! 125: sub is_courseid {
! 126: my ($courseid) = @_;
! 127: return ($courseid =~ m/^$match_courseid$/);
! 128: }
! 129:
! 130: $match_name = qr{$match_username|$match_courseid};
! 131: sub clean_name {
! 132: my ($name) = @_;
! 133: $name =~ s/$match_not_username//g;
! 134: return $name;
! 135: }
! 136:
! 137: sub split_courseid {
! 138: my ($courseid) = @_;
! 139: my ($domain,$coursenum) =
! 140: ($courseid=~m{^/($match_domain)/($match_courseid)});
! 141: return ($domain,$coursenum);
! 142: }
! 143:
1.14 albertel 144: $match_handle = $LONCAPA::handle_re = qr{[\w\-.]+};
145: $match_not_handle = $LONCAPA::not_handle_re = qr{[^\w\-.]+};
146: sub clean_handle {
147: my ($handle) = @_;
148: $handle =~ s/$match_not_handle//g;
149: return $handle;
150: }
151:
1.2 www 152: # -------------------------------------------- Return path to profile directory
153:
154: sub propath {
155: my ($udom,$uname)=@_;
1.14 albertel 156: $udom = &clean_domain($udom);
1.16 ! albertel 157: $uname= &clean_name($uname);
1.2 www 158: my $subdir=$uname.'__';
159: $subdir =~ s/(.)(.)(.).*/$1\/$2\/$3/;
160: my $proname="$perlvar{'lonUsersDir'}/$udom/$subdir/$uname";
161: return $proname;
162: }
163:
164:
165: #---------------------------------------------------------------
166: #
167: # Manipulation of hash based databases (factoring out common code
168: # for later use as we refactor.
169: #
170: # Ties a domain level resource file to a hash.
171: # If requested a history entry is created in the associated hist file.
172: #
173: # Parameters:
174: # domain - Name of the domain in which the resource file lives.
175: # namespace - Name of the hash within that domain.
176: # how - How to tie the hash (e.g. GDBM_WRCREAT()).
177: # loghead - Optional parameter, if present a log entry is created
178: # in the associated history file and this is the first part
179: # of that entry.
180: # logtail - Goes along with loghead, The actual logentry is of the
181: # form $loghead:<timestamp>:logtail.
182: # Returns:
183: # Reference to a hash bound to the db file or alternatively undef
184: # if the tie failed.
185: #
186: sub tie_domain_hash {
187: my ($domain,$namespace,$how,$loghead,$logtail) = @_;
188:
189: # Filter out any whitespace in the domain name:
190:
1.14 albertel 191: $domain = &clean_domain($domain);
1.2 www 192:
193: # We have enough to go on to tie the hash:
194:
195: my $user_top_dir = $perlvar{'lonUsersDir'};
196: my $domain_dir = $user_top_dir."/$domain";
197: my $resource_file = $domain_dir."/$namespace";
198: return &_locking_hash_tie($resource_file,$namespace,$how,$loghead,$logtail);
199: }
200:
201: sub untie_domain_hash {
202: return &_locking_hash_untie(@_);
203: }
204: #
205: # Ties a user's resource file to a hash.
206: # If necessary, an appropriate history
207: # log file entry is made as well.
208: # This sub factors out common code from the subs that manipulate
209: # the various gdbm files that keep keyword value pairs.
210: # Parameters:
211: # domain - Name of the domain the user is in.
212: # user - Name of the 'current user'.
213: # namespace - Namespace representing the file to tie.
214: # how - What the tie is done to (e.g. GDBM_WRCREAT().
215: # loghead - Optional first part of log entry if there may be a
216: # history file.
217: # what - Optional tail of log entry if there may be a history
218: # file.
219: # Returns:
220: # hash to which the database is tied. It's up to the caller to untie.
221: # undef if the has could not be tied.
222: #
223: sub tie_user_hash {
224: my ($domain,$user,$namespace,$how,$loghead,$what) = @_;
225:
1.15 albertel 226: $namespace=~s{/}{_}g; # / -> _
227: $namespace = &clean_username($namespace);
228: my $proname = &propath($domain, $user);
1.2 www 229: my $file_prefix="$proname/$namespace";
230: return &_locking_hash_tie($file_prefix,$namespace,$how,$loghead,$what);
231: }
232:
233: sub untie_user_hash {
234: return &_locking_hash_untie(@_);
235: }
236:
1.6 www 237: # routines if you just have a filename
238: # return tied hashref or undef
239:
240: sub locking_hash_tie {
241: my ($filename,$how)=@_;
242: my ($file_prefix,$namespace)=&db_filename_parts($filename);
1.7 albertel 243: if ($namespace eq '') { return undef; }
1.6 www 244: return &_locking_hash_tie($file_prefix,$namespace,$how);
245: }
246:
247: sub locking_hash_untie {
248: return &_locking_hash_untie(@_);
249: }
250:
251: sub db_filename_parts {
252: my ($filename)=@_;
253: my ($file_path,$namespace)=($filename=~/^(.*)\/([^\/]+)\.db$/);
1.7 albertel 254: if ($namespace eq '') { return undef; }
1.6 www 255: return ($file_path.'/'.$namespace,$namespace);
256: }
257:
1.2 www 258: # internal routines that handle the actual tieing and untieing process
259:
260: sub _do_hash_tie {
261: my ($file_prefix,$namespace,$how,$loghead,$what) = @_;
262: my %hash;
263: if(tie(%hash, 'GDBM_File', "$file_prefix.db", $how, 0640)) {
264: # If this is a namespace for which a history is kept,
265: # make the history log entry:
266: if (($namespace !~/^nohist\_/) && (defined($loghead))) {
267: my $hfh = IO::File->new(">>$file_prefix.hist");
268: if($hfh) {
1.5 albertel 269: my $now = time();
270: print $hfh ("$loghead:$now:$what\n");
1.2 www 271: }
272: $hfh->close;
273: }
274: return \%hash;
275: } else {
276: return undef;
277: }
278: }
279:
280: sub _do_hash_untie {
281: my ($hashref) = @_;
282: my $result = untie(%$hashref);
283: return $result;
284: }
285:
286: {
287: my $sym;
1.10 albertel 288: my @pushed_syms;
1.11 albertel 289:
290: sub clean_sym {
291: undef($sym);
292: }
1.10 albertel 293: sub push_locking_hash_tie {
294: if (!defined($sym)) {
295: die("Invalid used of push_locking_hash_tie, should only be called after a lock has occurred and before and unlock.");
296: }
297: push(@pushed_syms,$sym);
298: undef($sym);
299: }
300:
301: sub pop_locking_hash_tie {
302: if (defined($sym)) {
303: die("Invalid nested used of pop_locking_hash_tie, should only be called after a unlock has occurred.");
304: }
305: $sym = pop(@pushed_syms);
306: }
1.2 www 307:
308: sub _locking_hash_tie {
309: my ($file_prefix,$namespace,$how,$loghead,$what) = @_;
1.9 albertel 310: if (defined($sym)) {
1.11 albertel 311: die('Nested locking attempted without proper use of push_locking_hash_tie, this is unsupported');
1.9 albertel 312: }
313:
1.2 www 314: my $lock_type=LOCK_SH;
315: # Are we reading or writing?
316: if ($how eq &GDBM_READER()) {
317: # We are reading
318: if (!open($sym,"$file_prefix.db.lock")) {
319: # We don't have a lock file. This could mean
320: # - that there is no such db-file
321: # - that it does not have a lock file yet
322: if ((! -e "$file_prefix.db") && (! -e "$file_prefix.db.gz")) {
323: # No such file. Forget it.
324: $! = 2;
1.11 albertel 325: &clean_sym();
1.2 www 326: return undef;
327: }
328: # Apparently just no lock file yet. Make one
329: open($sym,">>$file_prefix.db.lock");
330: }
331: # Do a shared lock
1.9 albertel 332: if (!&flock_sym(LOCK_SH)) {
1.11 albertel 333: &clean_sym();
1.9 albertel 334: return undef;
335: }
1.2 www 336: # If this is compressed, we will actually need an exclusive lock
337: if (-e "$file_prefix.db.gz") {
1.9 albertel 338: if (!&flock_sym(LOCK_EX)) {
1.11 albertel 339: &clean_sym();
1.9 albertel 340: return undef;
341: }
1.2 www 342: }
343: } elsif ($how eq &GDBM_WRCREAT()) {
344: # We are writing
345: open($sym,">>$file_prefix.db.lock");
346: # Writing needs exclusive lock
1.9 albertel 347: if (!&flock_sym(LOCK_EX)) {
1.11 albertel 348: &clean_sym();
1.9 albertel 349: return undef;
350: }
1.2 www 351: } else {
1.5 albertel 352: die("Unknown method $how for $file_prefix");
1.2 www 353: }
354: # The file is ours!
355: # If it is archived, un-archive it now
356: if (-e "$file_prefix.db.gz") {
357: system("gunzip $file_prefix.db.gz");
358: if (-e "$file_prefix.hist.gz") {
359: system("gunzip $file_prefix.hist.gz");
360: }
361: }
362: # Change access mode to non-blocking
363: $how=$how|&GDBM_NOLOCK();
364: # Go ahead and tie the hash
1.13 albertel 365: my $result =
366: &_do_hash_tie($file_prefix,$namespace,$how,$loghead,$what);
367: if (!$result) {
368: &clean_sym();
369: }
370: return $result;
1.2 www 371: }
372:
373: sub flock_sym {
374: my ($lock_type)=@_;
375: my $failed=0;
376: eval {
377: local $SIG{__DIE__}='DEFAULT';
378: local $SIG{ALRM}=sub {
379: $failed=1;
380: die("failed lock");
381: };
382: alarm($loncapa_max_wait_time);
383: flock($sym,$lock_type);
384: alarm(0);
385: };
386: if ($failed) {
387: $! = 100; # throwing error # 100
388: return undef;
389: } else {
390: return 1;
391: }
392: }
393:
394: sub _locking_hash_untie {
395: my ($hashref) = @_;
396: my $result = untie(%$hashref);
397: flock($sym,LOCK_UN);
398: close($sym);
1.11 albertel 399: &clean_sym();
1.2 www 400: return $result;
401: }
402: }
403:
404: BEGIN {
1.4 albertel 405: %perlvar=%{&LONCAPA::Configuration::read_conf('loncapa.conf')};
1.2 www 406: }
407:
1.1 albertel 408: 1;
409:
410: __END__
411:
412: =pod
413:
414: =head1 NAME
415:
416: LONCAPA - Basic routines
417:
418: =head1 SYNOPSIS
419:
420: Generally useful routines
421:
422: =head1 EXPORTED SUBROUTINES
423:
424: =over 4
425:
426: =item *
427:
428: escape() : unpack non-word characters into CGI-compatible hex codes
429:
430: =item *
431:
432: unescape() : pack CGI-compatible hex codes into actual non-word ASCII character
433:
434: =item *
435:
436: add_get_param() :
437: Inputs: url (with or without exit GET from parameters), hash ref of
438: form name => value pairs
439:
440: Return: url with properly added the form name elements and values to the
441: the url doing proper escaping of the values and joining with ? or &
442: as needed
443:
444: =back
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to LONCAPA.pm CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / loncom