__createFilterElement (
        self,
        userDoc,
        filter,
        )

__createFilterElement is a private helper function that takes a MadrigalFilter python object and converts to an xml node.

Inputs: userDoc - the xml document to be added to, filter - a MadrigalFilter object to be persisted as an xml node in an xml file.

Returns: the xml node created

Affects: None

Exceptions: None

Notes: Each attribute added to the node takes four lines of code, basically 1) create new element, 2) create text element, 3 append text element to new element, and 4) append new element to its parent. Since a MadrigalFilter has at the moment 23 attributes, this function is long but simply repeats those 4 steps above. One dom implementaion hint: always finish creating a node first before appending to a parent. Once a node is appended to a parent, it cannot have other nodes appended to it. So always append from the bottom up.

__dropLock ( self,  filename )

__dropLock is a private helper function that drops exclusive access to filename via a locking file.

Inputs: filename = the file that exclusive access is required to.

Returns: None

Affects: Removes file filename + .LCK as a lock mechanism

Exceptions: None.

__elementExists (
        self,
        elem,
        elemTag,
        doc,
        )

__elementExists is a private helper function that returns 1 if the xml doc has a element elemTag with text elem, 0 otherwise.

Inputs: elem - a string to match text nodes against, elemTag - a string giving the element name to search in, and doc is the xml document.

Returns: returns 1 if the xml doc has a element elemTag with text elem, 0 otherwise.

Affects: None

Exceptions: None

Usage: If an xml file contains <person age=43> John Doe </person>, and you call self.__elementExists(John Doe, person, doc), 1 will be returned

__getLock ( self,  filename )

__getLock is a private helper function that provides exclusive access to filename via a locking file.

Inputs: filename = the file that exclusive access is required to.

Returns: None

Affects: Writes file filename + .LCK as a lock mechanism

Exceptions: MadrigalError thrown if unable to write lock file

Notes: Will sleep for 1 second at a time, for a maximum of _MaxSleep seconds (presently 10) if the file is not modified. After each second, it will check for the lock file to be removed or modified. If it was modified, it resets the count to 0 sec and starts counting again. After _MaxSleep counts it then assumes lock file is orphaned and returns. Orphaned file will be removed when dropLock is called.

__getText ( self,  nodelist )

__getText is a private helper function that returns a string made up of all the text nodes of a node list.

Inputs: A list of xml nodes.

Returns: a string made up of all the text nodes of a node list.

Affects: None

Exceptions: None

Usage: If an xml file contains <person age=43> John Doe </person>, and the element you have (elem) is the person element, then self.__getText(elem.childNodes) will return John Doe, since John Doe is a child text node of person, and __getText strips leading and trailing whitespace.

__getXmlString ( self,  obj )

__getXmlString is a private helper function that extends str by making it return an empty string on a null object.

Inputs: obj - the object to be converted to a string.

Returns: if the object == None, returns '', otherwise returns str(obj). Normally str(None) returns "None"

Affects: None

Exceptions: None.

__init__ ( self,  madDB=None )

__init__ initializes MadrigalUserData by reading from MadridalDB..

Inputs: Existing MadrigalDB object, by default = None.

Returns: void

Affects: Initializes self.__metaDir.

Exceptions: None.

__isValidFileName ( self,  name )

__isValidFileName is a private helper function that validates that the string name does not contain excluded characters.

Inputs: name - the string to be validated.

Returns: 1 if all characters are allowed, 0 otherwise. Valid if the following characters are not found in the string after leading and trailing whitespace is removed: [' ', /, <, >, '']

Affects: None

Exceptions: None.

__loadUserData ( self )

__loadUserData is a private helper function that reads in user information from an xml file.

Inputs: None.

Returns: void

Affects: Populates self.__userList.

Exceptions: MadrigalError thrown if problem parsing users.xml.

Depends on: Existance of file in metadata dir self.__userXMLDir + / + self.__userXMLFile (now userdata/user.xml)

This file must be of the form of the following format:

<?xml version='1.0'?>

<users>

<user>

<name>brideout</name>

<password>briWy6v1L.z1E</password>

</user>

possibly more users...

</users>

The password is stored encrypted by crypt.crypt(password, self.__cryptStr). Implemented via xml.dom, since it is only a short file, but for higher speed (and more complex code) could be implemented with sax since read only.

addDirectory (
        self,
        username,
        dirname,
        dirtype,
        )

addDirectory returns 1 if directory added successfully to <username>.xml, error string otherwise.

Inputs: username string, directory name string, dirtype string (public or private).

Returns: 1 if directory added successfully, error string otherwise. dirtype must be either public or private. Directory names are case sensitive, so Bill and bill can both be directories

Affects: Adds new directory to <username>.xml file

Exceptions: MadrigalError thrown if unable to write to <username>.xml file

Notes: uses getLock and dropLock to insure exclusive access to <username>.xml file

addFilter (
        self,
        username,
        dirname,
        filter,
        )

addFilter returns 1 if a new filter is added successfully to a directory in <username>.xml, 0 otherwise.

Inputs: username string, directory name string, MadrigalFilter object to be added.

Returns: 1 if filter added successfully, error string otherwise.

Affects: Adds new filter to <username>.xml file

Exceptions: MadrigalError thrown if unable to write to <username).xml file

Notes: uses getLock and dropLock to insure exclusive access to <username>.xml file

addUser (
        self,
        username,
        password,
        )

addUser returns 1 if user added successfully, error string otherwise.

Inputs: username string, password string (password is not yet encrypted).

Returns: 1 if user added successfully, error string otherwise.

Affects: Adds new user to self.__userList, writes new empty <username>.xml file username is always converted and stored as lower case, so its case insensitive.

Exceptions: MadrigalError thrown if unable to write to user xml file

Notes: uses getLock and dropLock to insure exclusive access to user file

changePassword (
        self,
        username,
        password,
        )

changePassword returns 1 if user password changed successfully, error string otherwise.

Inputs: username string, password string (password is not yet encrypted).

Returns: 1 if password changed successfully, error string otherwise.

Affects: Modifies password in self.__userList, writes new user.xml file

Exceptions: MadrigalError thrown if unable to write user xml file

getAllDirInfo ( self )

getAllDirInfo returns a dictionary with key=username, value=list of MadrigalDirectory objects owned by user.

Inputs: none.

Returns: a dictionary with key=username, value=list of MadrigalDirectory objects owned by user. See this file for the description of the information in a MadrigalDirectory class.

Affects: builds __dirsDict. Other public functions that use __dirsDict will call getAllDirInfo to populate __dirsDict if its = None

Exceptions: MadrigalError thrown if unable to read a user file

Usage example:

            import madrigal.ui.userData

            test = madrigal.ui.userData.MadrigalUserData()

            userDirInfo = test.getAllDirInfo()

            # print all the directory information for user brideout

            for madDir in userDirInfo['brideout']:

                print 'Directory name is ' + madDir.dirName

                print 'This directory type (public or private) is ' + madDir.dirType

                print 'The filter names in this directory are:'

                for filtername in madDir.filterList:

                    print '    ' + filtername

Notes: Presently implemented by the sax handler class getDirInfoParser (included in this file).

getFilter (
        self,
        username,
        dirname,
        filtername,
        )

getFilter returns a MadrigalFilter object specified by the username, dirname, and filtername.

Inputs: username string (case insensitive), dirname string (case sensitive), filtername string(case sensitive).

Returns: a MadrigalFilter object specified by the username, dirname, and filtername. If none matches, return None

Affects: None

Exceptions: MadrigalError thrown if unable to read a user file

Notes: Presently implemented by the sax handler class getFilterParser (included in this file) for greater speed than the use of dom.

getFilterNameList (
        self,
        username,
        dirName,
        )

getFilterNameList returns a list of strings of the names of all filters in a given directory of a given user.

Inputs: username (string), directory name (string).

Returns: a list of strings of the names of all filters in a given directory of a given user (empty list if none)

Affects: Builds __dirsDict by calling getAllDirInfo if not yet populated

Exceptions: None

getPrivateDirNameList ( self,  username )

getPrivateDirNameList returns a list of strings of the names of all private directories for a given user.

Inputs: username (string).

Returns: a list of strings of the names of all private directories owned by that user. Empty list if none

Affects: Builds __dirsDict by calling getAllDirInfo if not yet populated

Exceptions: None

getPublicDirNameList ( self )

getPublicDirNameList returns a list of strings of the names of all public directories in form user:dirName.

Inputs: none.

Returns: a list of strings of the names of all public directories

Affects: Builds __dirsDict by calling getAllDirInfo if not yet populated

Exceptions: None

getRegisteredDict ( self )

will return a dictionary with key + email, and value = tuple of all registered experiments for that email.

This data will be stored in a text file: MADROOT/metadata/userdata/ regExp.txt. The format will be two space delimited columns: email experimentString.

getRegisteredExperiments ( self,  email )

getRegisteredExperiments will return a list of experiments as strings. For example, getRegisteredExperiments(brideout at haystack.mit.edu) might return ['experiments/2010/mlh/18jan10', experiments/2010/mlh/ 19jan10, 'experiments/2010/mlh/20jan10']. If the user has no registered experiments, it will return an empty list.

Inputs: user email

getRegisteredInstDict ( self )

will return a dictionary with key = email, and value = tuple of all registered instrument codes (int) for that email.

This data will be stored in a text file: MADROOT/metadata/userdata/ regInst.txt. The format will be two space delimited columns: email instrument code (int).

getRegisteredInstUsers ( self,  kinst )

getRegisteredInstUsers will return a list of users registered for a given instrument code (kinst) as strings. For example, getRegisteredInstUsers(30) might return ['brideout at haystack.mit.edu ', 'miguel.urco at jro.igp.gob.pe']. If the instrument has no registered users, it will return an empty list

getRegisteredInstruments ( self,  email )

getRegisteredInstruments will return a list of instruments as ints. For example, getRegisteredInstruments(brideout at haystack.mit.edu) might return [30, 31, 10]. If the user has no registered instruments, it will return an empty list.

Inputs: user email

getRegisteredUsers ( self,  experimentString )

getRegisteredUsers will return a list of users register for a given experiment as strings. For example, getRegisteredUsers(experiments/2010/mlh/18jan10) might return ['brideout at haystack.mit.edu ', 'miguel.urco at jro.igp.gob.pe']. If the experiment has no registered users, it will return an empty list

getUsersList ( self )

getUsersList returns a list of user names/encrypted passwords that already exist.

Inputs: none.

Returns: a list of user names/passwords. Each item in the returned list is itself a list with two strings: 1) username, and 2) encrypted password.

Usage example:

            import madrigal.ui.userData

            test = madrigal.ui.userData.MadrigalUserData()

            userlist = test.getUsersList()

            for user in userlist:

                print 'User name is ' + user[0] + ' and encrypted password is ' + user[1]

Affects: None

Exceptions: none

registerExperiment (
        self,
        email,
        experimentString,
        )

registerExperiment method will register an experiment for a given email. For example, registerExperiment(brideout at haystack.mit.edu, experiments/2010/mlh/ 18jan10) would register an experiment. If the experiment is already registed, it will not raise an error; it will simply do nothing.

Affects: This new data will be stored in a text file: MADROOT/metadata/userdata/ regExp.txt. The format will be two space delimited columns: email experimentString.

registerInstrument (
        self,
        email,
        kinst,
        )

registerInstrument method will register an instrument for a given email. For example, registerInstrument(brideout at haystack.mit.edu, 30) would register an instrument. If the instrument is already registed, it will not raise an error; it will simply do nothing.

Affects: This new data will be stored in a text file: MADROOT/metadata/userdata/ regInst.txt. The format will be two space delimited columns: email kinst.

removeDirectory (
        self,
        username,
        dirname,
        )

removeDirectory returns 1 if a directory is removed successfully from a directory in <username>.xml, error string otherwise.

Inputs: username string, directory name to be removed.

Returns: 1 if filter removed successfully, error string otherwise. Will not remove a directory that contains filters.

Affects: Removes existing dirctory from <username>.xml file

Exceptions: MadrigalError thrown if unable to write to <username).xml file

Notes: uses getLock and dropLock to insure exclusive access to <username>.xml file

removeFilter (
        self,
        username,
        dirname,
        filtername,
        )

removeFilter returns 1 if a filter is removed successfully from a directory in <username>.xml, error string otherwise.

Inputs: username string, directory name string, filtername of filter to be removed.

Returns: 1 if filter removed successfully, error string otherwise.

Affects: Removes existing filter from <username>.xml file

Exceptions: MadrigalError thrown if unable to write to <username).xml file

Notes: uses getLock and dropLock to insure exclusive access to <username>.xml file

unregisterExperiment (
        self,
        email,
        experimentString,
        )

unregisterExperiment method will unregister an experiment for a given email. For example, unregisterExperiment(brideout at haystack.mit.edu, experiments/2010/ mlh/18jan10) would unregister an experiment. If the experiment is not registed, it will not raise an error; it will simply do nothing.

Affects: This data will be removed from a text file: MADROOT/metadata/userdata/ regExp.txt. The format will be two space delimited columns: email experimentString.

unregisterInstrument (
        self,
        email,
        kinst,
        )

unregisterInstrument method will unregister an instrument for a given email. For example, unregisterInstrument(brideout at haystack.mit.edu, 30) would unregister an instrument. If the instrument is not registed, it will not raise an error; it will simply do nothing.

Affects: This data will be removed from a text file: MADROOT/metadata/userdata/ regInst.txt. The format will be two space delimited columns: email kinst.

userExists ( self,  username )

userExists returns 1 if username (case insensitive) exists, 0 otherwise.

Inputs: username string.

Returns: 1 if username (case insensitive) exists, 0 otherwise.

Affects: None

Exceptions: none

verifyUser (
        self,
        username,
        password,
        )

verifyUser returns 1 if username, password okay, 0 otherwise.

Inputs: username string, password string.

Returns: 1 if username, password okay, 0 otherwise.

Affects: None

Exceptions: none