Annotation of loncom/LondTransaction.pm, revision 1.3

1.1       foxr        1: #   This module defines and implements a class that represents
                      2: #   a connection to a lond daemon.
                      3: #
1.3     ! foxr        4: # $Id: LondTransaction.pm,v 1.2 2003/05/05 23:58:05 foxr Exp $
1.1       foxr        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: =pod
1.3     ! foxr       30: 
        !            31: =head1 Synopsis
        !            32: 
1.2       foxr       33:   LondTransaction objectifies the state of a transaction between lonc and
1.1       foxr       34:   lond (loncnew really).  
                     35: 
                     36: =cut
                     37: 
1.3     ! foxr       38: package LondTransaction;
1.2       foxr       39: 
                     40: =pod
                     41: =head1 Description
                     42: 
                     43: LondTransaction objects hold the state required to manage a 
                     44: transaction between lonc and lond, from the loncnew point of view.
                     45: The state consists of the following member data:
                     46: 
                     47: =item request
                     48: 
                     49: The text of the request to send to lond.
                     50: 
                     51: =item active
                     52: 
                     53: If zero, the request is not active and the londSocket item is not
                     54: defined.
                     55: 
                     56: =item londSocket
                     57: 
1.3     ! foxr       58: If the request is active,
1.2       foxr       59: this member contains the LondConnection object reference that
                     60: this request is being processed on.
                     61: 
                     62: =item deferred
                     63: 
                     64: True if the request is a deferred (delayed) request.
                     65: The member data below are either present or not depending on 
                     66: whether or not deferred is true.
                     67: 
                     68: =item clientSocket
                     69:    
                     70: If deferred is false, this member data is defined and is the 
                     71: handle to the socket that is connected to the apache child that
                     72: has requested this transaction.
                     73: 
                     74: =item DeferredFile
                     75: 
                     76: If deferred is false, this member data is defined and is the name
                     77: of the file that contains the deferred request.  When the transaction
                     78: is retired, this file will be deleted.
                     79: 
                     80: =head1 Member Functions
                     81: 
                     82: =head2  Operational functions
                     83: 
1.3     ! foxr       84: =cut
        !            85: 
        !            86: =pod
        !            87: 
1.2       foxr       88: =item new
                     89: 
                     90: Creates a new transaction object.
                     91: 
1.3     ! foxr       92: =cut
        !            93: 
        !            94: sub new {
        !            95:     my $class       = shift;
        !            96:     my $Transaction = shift;
        !            97: 
        !            98:     
        !            99:     my $self   = {request     => $Transaction,
        !           100: 		  active      => 0,
        !           101: 		  deferred    => 0};
        !           102:     bless($self, $class);
        !           103: }
        !           104: =pod
        !           105: 
1.2       foxr      106: =item Activate
                    107: 
                    108: Activates the transaction by assigning it to a LondConnection object
                    109: 
1.3     ! foxr      110: Parameters:
        !           111: 
        !           112: =over 3
        !           113: 
        !           114: =item  Connection
        !           115: 
        !           116: 
        !           117: Reference to the LondConnection object along which the transaction
        !           118: will be carried.
        !           119: 
        !           120: =back 
        !           121: 
        !           122: =cut
        !           123: sub Activate {
        !           124:     my $self       = shift;
        !           125:     my $Connection = shift;	# Reference to a lond connection.
        !           126: 
        !           127:     $self->{londSocket} = $Connection; # Store the connection object and
        !           128:     $self->{active}     = 1;	       # Indicate it's active.
        !           129: 
        !           130: }
        !           131: 
        !           132: =pod
        !           133: 
1.2       foxr      134: =item Retire
                    135: 
1.3     ! foxr      136: 
        !           137: Retires a transaction after successful completion.  If the
        !           138: transaction is deferred, the deferred file is destroyed.
        !           139: Otherwise this is a noop.
        !           140: 
        !           141: =cut
        !           142: sub Retire {
        !           143:     my $self     = shift;
        !           144: 
        !           145:     if($self->{deferred}) {
        !           146: 	unlink $self->{DeferredFile};
        !           147:     }
        !           148: 
        !           149:     #  Destroy my member data to release reference counts.
        !           150: 
        !           151:     delete $self->{londSocket};
        !           152:     delete $self->{clientSocket};
        !           153:     delete $self->{DeferredFile};
        !           154: 
        !           155: }
        !           156: 
        !           157: =pod
1.2       foxr      158: 
                    159: =item SetDeferred
                    160: 
                    161: Sets the state of a transaction to deferred, the deferred member
                    162: is set true, clientSocket is undefined, and DeferredFile is set.
                    163: 
1.3     ! foxr      164: Parameters:
        !           165:  
        !           166: =over 3
        !           167: 
        !           168: =item File
        !           169: 
        !           170: Name of the file that holds the deferred transaction.
        !           171: 
        !           172: =back 
        !           173: 
        !           174: =cut
        !           175: sub SetDeferred {
        !           176:     my $self   = shift;
        !           177:     my $File   = shift;
        !           178: 
        !           179:     $self->{deferred}      = 1;
        !           180:     $self->{DeferrredFile} = $File;
        !           181: }
        !           182: 
        !           183: =pod
        !           184: 
        !           185: =item  SetClient
1.2       foxr      186: 
                    187: Sets the state of a transaction to not deferred.  The deferred member
                    188: is set false, clientSocket is set and DeferredFile is undefined.
                    189: 
1.3     ! foxr      190: Parameters:
        !           191: 
        !           192: =over 3
        !           193: 
        !           194: =item Socket
        !           195: 
        !           196:   The socket open on the client.
        !           197: 
        !           198: =back
        !           199: 
        !           200: =cut
        !           201: sub SetClient {
        !           202:     my $self   = shift;
        !           203:     my $Client = shift;
        !           204:     
        !           205:     $self->{deferred}     = 0;
        !           206:     $self->{clientSocket} = $Client; 
        !           207: }
        !           208: 
        !           209: =pod
        !           210: 
        !           211: =item WroteSome
        !           212: 
        !           213:  Called to indicate that some bytes were writtne to lond.
        !           214:  The request is trimmed by the number of bytes written.
        !           215:  If no bytes are left, nonzero is returned, else 0.
        !           216: 
        !           217: Parameters:
        !           218: 
        !           219: =over 3
        !           220: 
        !           221: =item Count
        !           222: 
        !           223: Number of bytes written
        !           224: 
        !           225: =back
        !           226: 
        !           227: =cut
        !           228: sub WroteSome {
        !           229:     my $self   = shift;
        !           230:     my $Count  = shift;
        !           231: 
        !           232:     substr($self->{request}, length($self->{request}), $Count);
        !           233: 
        !           234:     return (length($self->{request]) == 0);
        !           235: 
        !           236: =pod
        !           237: 
1.2       foxr      238: =head2  Selectors
                    239: 
                    240: 
                    241: =item isDeferred
                    242: 
                    243: Returns the state of the deferred member.
                    244: 
1.3     ! foxr      245: =cut
        !           246: sub isDeferred {
        !           247:     my $self   = shift;
        !           248:     return $self->{deferred};
        !           249: }
        !           250: 
        !           251: =pod
        !           252: 
1.2       foxr      253: =item isActive
                    254: 
1.3     ! foxr      255: Returns the value of the active member.
        !           256: 
        !           257: =cut
        !           258: sub isActive {
        !           259:     my $self = shift;
        !           260:     return $self->{active};
        !           261: }
        !           262: 
        !           263: =pod
1.2       foxr      264: 
                    265: =item getClient
                    266: 
1.3     ! foxr      267: If not deferred returns the client socket, else returns undef.
        !           268: 
        !           269: =cut
        !           270: sub getClient {
        !           271:     my $self = shift;
        !           272:     if($self->{deferred}) {
        !           273: 	return undef;
        !           274:     } else {
        !           275: 	return $self->{clientSocket};
        !           276:     }
        !           277: }
        !           278: 
        !           279: 
        !           280: =pod
1.2       foxr      281: 
                    282: =item getFile
                    283: 
                    284: If deferred, returns the name of the deferred queue file else
                    285: returns undef.
                    286: 
                    287: =cut
1.3     ! foxr      288: sub getFile {
        !           289:     my $self = shift;
        !           290:     if($self->{deferred}) {
        !           291: 	return $self->{DeferredFile};
        !           292:     } else {
        !           293: 	return undef;
        !           294:     }
        !           295: }
        !           296: 
        !           297: 
        !           298: =pod
        !           299: 
        !           300: =item getServer
        !           301: 
        !           302:   If active returns the lond server socket else undef.
        !           303: 
        !           304: =cut
        !           305: sub getServer {
        !           306:     my $self  = shift;
        !           307: 
        !           308:     if($self->{active}) {
        !           309: 	return $self->{londSocket};
        !           310:     } else {
        !           311: 	return undef;
        !           312:     }
        !           313: }
        !           314: 
        !           315: =pod
        !           316: 
        !           317: =item getRequest
        !           318: 
        !           319:   Returns the remaining request text.
        !           320: 
        !           321: =cut
        !           322: sub getRequest {
        !           323:     my $self = shift;
        !           324:     return $self->{request};
        !           325: }
        !           326: 
        !           327: 

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