[BACK]Return to LONCAPA.pm CVS log [TXT] [DIR] Up to [LON-CAPA] / loncom

Diff for /loncom/LONCAPA.pm between versions 1.26 and 1.36

version 1.26, 2008/11/17 13:24:02 version 1.36, 2019/08/25 02:43:33
Line 27 Line 27
 #  #
 ###  ###
   
 =head1 NAME  
   
 Apache::LONCAPA  
   
 LONCAPA - Basic routines  
   
 =head1 SYNOPSIS  
   
 Generally useful routines  
   
 =head1 EXPORTED SUBROUTINES  
   
 =over 4  
   
 =item *  
   
 escape() : unpack non-word characters into CGI-compatible hex codes  
   
 =item *  
   
 unescape() : pack CGI-compatible hex codes into actual non-word ASCII character  
   
 =item *  
   
 add_get_param() :  
  Inputs:  url (with or without exit GET from parameters), hash ref of  
               form name => value pairs  
   
  Return: url with properly added the form name elements and values to the   
          the url doing proper escaping of the values and joining with ? or &  
          as needed  
   
 =back  
   
 =cut  
   
 package LONCAPA;  package LONCAPA;
   
Line 71  use LONCAPA::Configuration; Line 37  use LONCAPA::Configuration;
 use Fcntl qw(:flock);  use Fcntl qw(:flock);
 use GDBM_File;  use GDBM_File;
 use POSIX;  use POSIX;
   #use Apache::lonnet;
   
 my $loncapa_max_wait_time = 13;  my $loncapa_max_wait_time = 13;
   
   
   #--------------------------------------------------------------------------
   #
   #   The  constant definnitions below probably should really be in 
   #   a configuration file somewhere (loncapa.conf?) and loaded so that they can be 
   #   modified without requring source code changes:
   #
   #   COURSE_CACHE_TIME - Number of minutes after which an unaccessed
   #                       course.db or course_param.db file is considered
   #                       to be a stale cache of this info.
   #
   #   LONCAPA_TEMPDIR   - Place loncapa puts temporary files
   #
   
   my  $COURSE_CACHE_TIME =  60; # minutes course cache file is considered valid. 
   my  $LONCAPA_TEMPDIR   =  '/tmp/'; # relative to configuration{'lonTabDir'}.
   
 use vars qw($match_domain   $match_not_domain  use vars qw($match_domain   $match_not_domain
     $match_username $match_not_username      $match_username $match_not_username
     $match_courseid $match_not_courseid      $match_courseid $match_not_courseid
               $match_community
     $match_name      $match_name
             $match_lonid              $match_lonid
     $match_handle   $match_not_handle);      $match_handle   $match_not_handle);
Line 86  require Exporter; Line 70  require Exporter;
 our @ISA = qw (Exporter);  our @ISA = qw (Exporter);
 our @EXPORT = qw(&add_get_param    &escape            &unescape         our @EXPORT = qw(&add_get_param    &escape            &unescape       
  &tie_domain_hash  &untie_domain_hash &tie_user_hash   &tie_domain_hash  &untie_domain_hash &tie_user_hash
  &untie_user_hash  &propath);   &untie_user_hash  &propath &tie_course);
 our @EXPORT_OK = qw($match_domain   $match_not_domain  our @EXPORT_OK = qw($match_domain   $match_not_domain
     $match_username $match_not_username      $match_username $match_not_username
     $match_courseid $match_not_courseid      $match_courseid $match_not_courseid
                       $match_community
     $match_name      $match_name
     $match_lonid      $match_lonid
     $match_handle   $match_not_handle);      $match_handle   $match_not_handle &tie_course);
 our %EXPORT_TAGS = ( 'match' =>[qw($match_domain   $match_not_domain  our %EXPORT_TAGS = ( 'match' =>[qw($match_domain   $match_not_domain
    $match_username $match_not_username     $match_username $match_not_username
    $match_courseid $match_not_courseid     $match_courseid $match_not_courseid
                                      $match_community
    $match_name     $match_name
    $match_lonid     $match_lonid
    $match_handle   $match_not_handle)],);     $match_handle   $match_not_handle)],);
 my %perlvar;  my %perlvar;
   
   
 =pod  #
   # If necessary fetch and tie a user's image of the course hash 
   # to the specified hash
   # Parameters:
   #   domain   - User's domain
   #   user     - Name of user.
   #   course   - Course number.
   #   cdom     - Domain that is home to the course
   #   hash     - reference to the has to tie.
   #
   # Side effects:
   #   a gdbm file and it's associated lock file will be created in the 
   #   tmp directory tree.
   #
   # Returns:
   #   0 - failure.
   #   1 - success.
   #
   #  Note:
   #     It's possible the required user's db file is already present in the tempdir.
   #     in that case a decision must be made about whether or not to just tie to it
   #     or to fetch it again. Remember this sub could be called in the context of a user
   #     other than the one whose data are being fetched.  We don't know if that user already
   #     has a live session on this server.  What we'll do is only re-fetch if the hash atime.
   #     is older than COURSE_CACHE_TIME...that is if it's been accessed relatively recently
   #     where COURSE_CACHE_TIME defines the caching time.
   #
   #     The database files this function creates are of the form:
   #     $user@$domain_$course@$cdom.{db,lock}
   #     This differs from the prior filenames.  Therefore if a module does its own
   #     caching (That's a coding no-no) and does not use this centralized sub,
   #     multiple cache files for the same course/user will be created. 
   #  
   sub tie_course {
       my ($domain, $user, $course, $cdom, $hash) = @_;
   
       #
       #  See if we need to re-fetch the course data
       #
   
 =head2 NOTE:      
   }
   
 add_get_param()  # Return a string that is the path in which loncapa puts temp files:
   
 Inputs are a url, and a hash ref of  sub tempdir {
 form name => value pairs      my $result =  $perlvar{'lonDaemons'}.$LONCAPA_TEMPDIR; # to allow debugging.
 takes care of properly adding the form name elements and values to the       return $result;
 the url doing proper escaping of the values and joining with ? or & as   }
 needed  
   
 =cut  # Return the default engine to use to render content of <m></m> tags unless
   # a domain, course, or user specific value exists. 
   
   sub texengine {
       return 'MathJax';
   }
   
   # Return the Linux distro where this LON-CAPA instance is running
   
   sub distro {
       my $distro;
       if (open(PIPE,"/home/httpd/perl/distprobe |")) {
           $distro = <PIPE>;
           close(PIPE);
       }
       return $distro;
   }
   
   # Return the default password length. Can be overridden in a domain
   # by specifying a larger value (integer) in the domain configuration.
   
   sub passwd_min {
       return 7;
   }
   
   #----------------------------------------------------------------------
   #
   #  some of these subs need a bit of documentation
   
 sub add_get_param {  sub add_get_param {
     my ($url,$form_data) = @_;      my ($url,$form_data) = @_;
Line 148  sub unescape { Line 199  sub unescape {
     return $str;      return $str;
 }  }
   
 $match_domain     = $LONCAPA::domain_re     = qr{[\w\-.]+};  $LONCAPA::assess_re = qr{\.(problem|exam|quiz|assess|survey|form|library|task)$};
 $match_not_domain = $LONCAPA::not_domain_re = qr{[^\w\-.]+};  $LONCAPA::assess_page_re = qr{\.(problem|exam|quiz|assess|survey|form|library|task|page)$};
   $LONCAPA::assess_page_seq_re = qr{\.(problem|exam|quiz|assess|survey|form|library|task|sequence|page)$};
   $LONCAPA::parse_re = qr{\.(problem|exam|quiz|assess|survey|form|library|page|xml|html|htm|xhtml|xhtm)$};
   $LONCAPA::parse_page_re = qr{\.(problem|exam|quiz|assess|survey|form|library|page|xml|html|htm|xhtml|xhtm|page)$};
   $LONCAPA::parse_page_sty_re = qr{\.(problem|exam|quiz|assess|survey|form|library|page|xml|html|htm|xhtml|xhtm|page|sty)$};
   
   
   $match_domain     = $LONCAPA::domain_re     = qr{[[:alnum:]\-.]+};
   $match_not_domain = $LONCAPA::not_domain_re = qr{[^[:alnum:]\-.]+};
 sub clean_domain {  sub clean_domain {
     my ($domain) = @_;      my ($domain) = @_;
     $domain =~ s/$match_not_domain//g;      $domain =~ s/$match_not_domain//g;
Line 167  sub clean_username { Line 226  sub clean_username {
   
   
 $match_courseid     = $LONCAPA::courseid_re     = qr{\d[\w\-.]+};  $match_courseid     = $LONCAPA::courseid_re     = qr{\d[\w\-.]+};
   $match_community    =$LONCAPA::community_re     = qr{0[\w\-.]+};
 $match_not_courseid = $LONCAPA::not_courseid_re = qr{[^\w\-.]+};  $match_not_courseid = $LONCAPA::not_courseid_re = qr{[^\w\-.]+};
 sub clean_courseid {  sub clean_courseid {
     my ($courseid) = @_;      my ($courseid) = @_;
Line 199  sub clean_handle { Line 259  sub clean_handle {
     return $handle;      return $handle;
 }  }
   
   #
   # -- Ensure another process for same filesystem action is not running.
   #    lond uses for: apachereload; loncron uses for: lciptables
   #
   
   sub try_to_lock {
       my ($lockfile)=@_;
       my $currentpid;
       my $lastpid;
       # Do not manipulate lock file as root
       if ($>==0) {
           return 0;
       }
       # Try to generate lock file.
       # Wait 3 seconds.  If same process id is in
       # lock file, then assume lock file is stale, and
       # go ahead.  If process id's fluctuate, try
       # for a maximum of 10 times.
       for (0..10) {
           if (-e $lockfile) { 
               open(LOCK,"<$lockfile");
               $currentpid=<LOCK>;
               close LOCK;
               if ($currentpid==$lastpid) {
                   last;
               }
               sleep 3;
               $lastpid=$currentpid;
           } else {
               last;
           }
           if ($_==10) {
               return 0;
           }
       }
       open(LOCK,">$lockfile");
       print LOCK $$;
       close LOCK;
       return 1;
   }
   
 # -------------------------------------------- Return path to profile directory  # -------------------------------------------- Return path to profile directory
   
 sub propath {  sub propath {
Line 209  sub propath { Line 310  sub propath {
     $subdir =~ s/(.)(.)(.).*/$1\/$2\/$3/;      $subdir =~ s/(.)(.)(.).*/$1\/$2\/$3/;
     my $proname="$perlvar{'lonUsersDir'}/$udom/$subdir/$uname";      my $proname="$perlvar{'lonUsersDir'}/$udom/$subdir/$uname";
     return $proname;      return $proname;
 }   }
   
   
 #---------------------------------------------------------------  
   
 =pod  
   
 =out  
   
 =item tie_domain_hash()  
   
 Manipulation of hash based databases (factoring out common code  
 for later use as we refactor.  
   
  Ties a domain level resource file to a hash.  
  If requested a history entry is created in the associated hist file.  
   
  Parameters:  
     domain    - Name of the domain in which the resource file lives.  
     namespace - Name of the hash within that domain.  
     how       - How to tie the hash (e.g. GDBM_WRCREAT()).  
     loghead   - Optional parameter, if present a log entry is created  
                 in the associated history file and this is the first part  
                  of that entry.  
     logtail   - Goes along with loghead,  The actual logentry is of the  
                 form $loghead:<timestamp>:logtail.  
 Returns:  
    Reference to a hash bound to the db file or alternatively undef  
    if the tie failed.  
   
 =back  
   
 =cut  
   
 sub tie_domain_hash {  sub tie_domain_hash {
     my ($domain,$namespace,$how,$loghead,$logtail) = @_;      my ($domain,$namespace,$how,$loghead,$logtail) = @_;
Line 262  sub untie_domain_hash { Line 331  sub untie_domain_hash {
     return &_locking_hash_untie(@_);      return &_locking_hash_untie(@_);
 }  }
   
 =pod  
   
 =out  
   
 =item tie_user_hash()  
   
   Ties a user's resource file to a hash.    
   If necessary, an appropriate history  
   log file entry is made as well.  
   This sub factors out common code from the subs that manipulate  
   the various gdbm files that keep keyword value pairs.  
 Parameters:  
   domain       - Name of the domain the user is in.  
   user         - Name of the 'current user'.  
   namespace    - Namespace representing the file to tie.  
   how          - What the tie is done to (e.g. GDBM_WRCREAT().  
   loghead      - Optional first part of log entry if there may be a  
                  history file.  
   what         - Optional tail of log entry if there may be a history  
                  file.  
 Returns:  
   hash to which the database is tied.  It's up to the caller to untie.  
   undef if the has could not be tied.  
   
 back  
   
 =cut  
   
 sub tie_user_hash {  sub tie_user_hash {
     my ($domain,$user,$namespace,$how,$loghead,$what) = @_;      my ($domain,$user,$namespace,$how,$loghead,$what) = @_;
Line 304  sub untie_user_hash { Line 346  sub untie_user_hash {
     return &_locking_hash_untie(@_);      return &_locking_hash_untie(@_);
 }  }
   
 =pod  
   
 =out  
   
 =item locking_hash_tie()  
   
 routines if you just have a filename  
 return tied hashref or undef  
   
 =back  
   
 =cut  
   
 sub locking_hash_tie {  sub locking_hash_tie {
     my ($filename,$how)=@_;      my ($filename,$how)=@_;
Line 481  sub _do_hash_untie { Line 511  sub _do_hash_untie {
     }      }
 }  }
   
   
 BEGIN {  BEGIN {
     %perlvar=%{&LONCAPA::Configuration::read_conf('loncapa.conf')};      %perlvar=%{&LONCAPA::Configuration::read_conf('loncapa.conf')};
 }  }
Line 489  BEGIN { Line 520  BEGIN {
   
 __END__  __END__
   
   =pod
   
   =head1 NAME
   
   Apache::LONCAPA
   
   LONCAPA - Basic routines
   
   =head1 SYNOPSIS
   
   Generally useful routines
   
   =head1 EXPORTED SUBROUTINES
   
   =over
   
   =item escape()
   
   unpack non-word characters into CGI-compatible hex codes
   
   =item unescape()
   
    pack CGI-compatible hex codes into actual non-word ASCII character
   
   =item  add_get_param()
   
   Append escaped form elements (name=value etc.) to a url.
    
    Inputs:  url (with or without exit GET from parameters), hash ref of
                 form name => value pairs
   
    Return: url with form name elements and values appended to the 
            the url, doing proper escaping of the values and joining with ? or &
            as needed
   
   =item clean_handle()
   
   =item propath()
   
   =item untie_domain_hash()
   
   =item tie_domain_hash()
   
   Manipulation of hash based databases (factoring out common code
   for later use as we refactor.
   
    Ties a domain level resource file to a hash.
    If requested a history entry is created in the associated hist file.
   
    Parameters:
       domain    - Name of the domain in which the resource file lives.
       namespace - Name of the hash within that domain.
       how       - How to tie the hash (e.g. GDBM_WRCREAT()).
       loghead   - Optional parameter, if present a log entry is created
                   in the associated history file and this is the first part
                    of that entry.
       logtail   - Goes along with loghead,  The actual logentry is of the
                   form $loghead:<timestamp>:logtail.
   Returns:
      Reference to a hash bound to the db file or alternatively undef
      if the tie failed.
   
   =item tie_user_hash()
   
     Ties a user's resource file to a hash.  
     If necessary, an appropriate history
     log file entry is made as well.
     This sub factors out common code from the subs that manipulate
     the various gdbm files that keep keyword value pairs.
   Parameters:
     domain       - Name of the domain the user is in.
     user         - Name of the 'current user'.
     namespace    - Namespace representing the file to tie.
     how          - What the tie is done to (e.g. GDBM_WRCREAT().
     loghead      - Optional first part of log entry if there may be a
                    history file.
     what         - Optional tail of log entry if there may be a history
                    file.
   Returns:
     hash to which the database is tied.  It's up to the caller to untie.
     undef if the has could not be tied.
   
   =item tie_course
   
   Caches the course database into the temp directory in the context of a specific
   user and ties it to a hash.
   Parameters:
      domain    - Domain the user is in.
      user      - Username of the user.
      course    - Course specification
      cdom      - The course domain.
      hash      - Reference to the hash to tie.
   
   Returns:
       1        - Success
       0        - Failure.
   
   =item tie_course_params
   
   Caches the course parameter database into the temp directory in the context
   of a specific user and ties it to a hash.
   Parameters:
      domain   - Domain the user is in.
      user     - Username of the user.
      course   - course specification.
      cdom     - The course domain.
      hash     - reference to the hash to tie.
   
   Returns:
      1        - Success.
      0        - Failure./
   
   
   =item locking_hash_tie()
   
   routines if you just have a filename return tied hashref or undef
   
   =item locking_hash_untie()
   
   =item db_filename_parts()
   
   =back
   
   =item tempdir()
   
   Returns the file system path to the place loncapa temporary files should be placed/found.
   
   
   =head1 INTERNAL SUBROUTINES
   
   =over 
   
   =item _do_hash_tie()
   
   =item _do_hash_untie()
   
   =back
   
   =cut
   
Removed from v.1.26  
changed lines
  Added in v.1.36

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>