jitas.core
Class Tutor

java.lang.Object
  extended by jitas.core.Tutor
All Implemented Interfaces:
TutorInterface

public class Tutor
extends java.lang.Object
implements TutorInterface

The main class for the JITAS class library (core classes). All other applications will use this class to interface with JITAS. This class provides all the necessary functionality for a higher level application to act as an Intelligent Tutoring System. To use this class it needs to be imported by the calling class, which can then directly call methods on this class.

Version:
24 August 2007
Author:
DeathMarch (c314g2)

Constructor Summary
Tutor()
          The default constructor for the tutor class.
Tutor(java.lang.String domainsFilePath)
          Constructor that takes in a file path for the domains.xml file
 
Method Summary
 void addAllowedDomain(java.lang.String userName, java.lang.String domainName)
          This method will attempt to give the user access to the specific domain.
 void addAllowedDomain(java.lang.String userName, java.lang.String domainName, boolean bypassSecurity)
           
 void addUser(java.lang.String userName, java.lang.String password, java.lang.String domainName)
          Adds a user to the JITAS system and authorize them to access domains.
 void addUser(java.lang.String userName, java.lang.String password, java.lang.String domainName, boolean bypassSecurity)
           
 void changePassword(java.lang.String userName, java.lang.String oldPassword, java.lang.String newPassword)
          Change user's existing password to a new password.
 void deleteUser(java.lang.String userName)
          Delete a user from the JITAS system.
 java.util.Set<java.lang.String> getAllDomainNames()
          Returns the names of all the domains this tutor knows about (loaded or otherwise)
 java.util.Map<java.lang.String,java.lang.String> getAllLongDomainNames()
          This gets the long domain names for all loaded domains
 java.util.SortedMap<java.lang.Integer,Problem> getAllProblems(java.lang.String userName, java.lang.String domainName)
          Gets all the problems in the current working subdomain of the domain and returns them as a SortedMap.
 java.util.Set<java.lang.String> getAllStudentUsernames()
           
 java.util.Set<java.lang.String> getAllStudentUsernames(java.lang.String filter)
           
 boolean getLoginStatus(java.lang.String userName, java.lang.String domainName)
          Get the login status for the user, for all the domains a student is logged into (i.e.
 Problem getNextProblem(int problemNumber, java.lang.String userName, java.lang.String domainName)
          Gets the next problem, specified by the user.
 Problem getNextProblem(java.lang.String userName, java.lang.String domainName)
          Gets the next problem, based on the current problem number.
 Problem getProblem(java.lang.String userName, java.lang.String domainName)
          Gets the next problem, specified by the system.
 java.lang.String getProblemStatus(java.lang.String userName, java.lang.String domainName, int problemID)
          Get the status of a problem for a particular domain and user.
 java.util.Set<java.lang.String> getSubdomains(java.lang.String domainName)
          Returns a set of all the subdomain names in a given domain, as Strings.
 boolean isStudentAllowedInDomain(java.lang.String userName, java.lang.String domainName)
           
 boolean isUserCreationAllowed(java.lang.String domainName)
           
 void loadDomain(java.lang.String domainName)
          Load the domain from XML
 void login(java.lang.String userName, java.lang.String password, java.lang.String domainName)
          Login method.
 void logout(java.lang.String userName, java.lang.String domainName)
          Logs a specified user out of the domain.
 void refreshStudentList()
           
 void removeUser(java.lang.String userName, java.lang.String domainName)
          Remove a user from a domain.
 void selectSubdomain(java.lang.String userName, java.lang.String subdomainName, java.lang.String domainName)
          Allows a user to select a subdomain to work on.
 void setCustomFeedback(java.lang.String domainName, java.lang.String fileName)
          Set the custom feedback object for a domain.
 void setCustomProblemSelectionAlgorithm(java.lang.String domainName, java.lang.String fileName)
          Set the custom problem selection algorithm for a domain.
 Feedback submitSolution(Solution studentSolution, java.lang.String userName, java.lang.String domainName)
          Used when a student wishes to submit their solution to the current problem.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Tutor

public Tutor()
      throws java.io.IOException
The default constructor for the tutor class. This method should be called whenever an application wants to create a new Tutor. All subsequent method calls should be made on that Tutor object. eg. In the higher level application: Tutor t = new Tutor(); ...

Throws:
java.io.IOException

Tutor

public Tutor(java.lang.String domainsFilePath)
      throws java.io.IOException
Constructor that takes in a file path for the domains.xml file

Parameters:
domainsFilePath - The path to an xml file containing information about all the domains. The path must include the filename.
Throws:
java.io.IOException
Method Detail

login

public void login(java.lang.String userName,
                  java.lang.String password,
                  java.lang.String domainName)
           throws DomainNotFoundException,
                  DomainNotLoadedException,
                  InvalidLoginException,
                  java.rmi.RemoteException,
                  UserNotFoundException
Description copied from interface: TutorInterface
Login method. This must be called on each tutor for each user before they can do anything else. A user can log into domains with their global login details. If the user does not have permissions for a particular domain, or if the domain does not exist, then an InvalidLoginException is thrown. If for some reason the student doesnt have a StudentModel for the domain, but has already been added to it (eg their Model got deleted from the XML file, then this method will create a new fresh StudentModel for that user. If this method does not throw any exceptions then it was succesfull.

Specified by:
login in interface TutorInterface
Parameters:
userName - The user name of the user.
password - The password for the user.
domainName - The Domain name the user wants to log into.
Throws:
DomainNotFoundException - If the domain is not found.
DomainNotLoadedException - If the domain is not loaded.
InvalidLoginException - If the login is invalid (wrong password).
java.rmi.RemoteException
UserNotFoundException - If the user does not exist.

logout

public void logout(java.lang.String userName,
                   java.lang.String domainName)
            throws DomainNotFoundException,
                   DomainNotLoadedException,
                   UserNotFoundException,
                   UserNotLoggedInException,
                   java.rmi.RemoteException
Description copied from interface: TutorInterface
Logs a specified user out of the domain. If this method does not throw any exceptions it was succesfull.

Specified by:
logout in interface TutorInterface
Parameters:
userName - The user to be logged out.
domainName - The Domain name the user wants to log out of.
Throws:
DomainNotFoundException - If the domain is not found.
DomainNotLoadedException - If the domain is not loaded.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user was not logged in.
java.rmi.RemoteException

getLoginStatus

public boolean getLoginStatus(java.lang.String userName,
                              java.lang.String domainName)
                       throws UserNotFoundException,
                              java.rmi.RemoteException
Description copied from interface: TutorInterface
Get the login status for the user, for all the domains a student is logged into (i.e. if they are logged into the domain or not)

Specified by:
getLoginStatus in interface TutorInterface
Parameters:
userName - The user name of the user who wants to log out.
domainName - The Domain name.
Returns:
true if they are logged in, false otherwise.
Throws:
UserNotFoundException - If the user could not be found.
java.rmi.RemoteException

addUser

public void addUser(java.lang.String userName,
                    java.lang.String password,
                    java.lang.String domainName)
             throws AddUserDeniedException,
                    DomainNotFoundException,
                    DomainNotLoadedException,
                    IllegalUserNameException,
                    StudentModelAlreadyExistsException,
                    java.rmi.RemoteException
Description copied from interface: TutorInterface
Adds a user to the JITAS system and authorize them to access domains. If the user already exists, then this method will attempt to give the user access to the specific domain. If the domain does not allow users to add themselves then a AddUserDeniedException will be thrown. If the user does not already have an account (they are new), then all necessary account data will be created. This method does NOT automatically log the user in; the login method must be explicitly called after the user has been added. If this method does not throw any exceptions then it was succesfull.

Specified by:
addUser in interface TutorInterface
Parameters:
userName - The user name of the new user.
password - The password for the new user.
domainName - The Domain name the user wants to create an account for.
Throws:
AddUserDeniedException - If new users are not allowed to be added to the domain.
DomainNotFoundException - If the domain could not be found.
DomainNotLoadedException - If the requested domain is not loaded.
IllegalUserNameException - If the user specified an illegal username.
StudentModelAlreadyExistsException - If a student model already exists.
java.rmi.RemoteException

addUser

public void addUser(java.lang.String userName,
                    java.lang.String password,
                    java.lang.String domainName,
                    boolean bypassSecurity)
             throws AddUserDeniedException,
                    DomainNotFoundException,
                    DomainNotLoadedException,
                    IllegalUserNameException,
                    StudentModelAlreadyExistsException,
                    java.rmi.RemoteException
Throws:
AddUserDeniedException
DomainNotFoundException
DomainNotLoadedException
IllegalUserNameException
StudentModelAlreadyExistsException
java.rmi.RemoteException

removeUser

public void removeUser(java.lang.String userName,
                       java.lang.String domainName)
                throws DomainNotFoundException,
                       DomainNotLoadedException,
                       UserNotFoundException,
                       UserNotLoggedInException,
                       java.rmi.RemoteException
Description copied from interface: TutorInterface
Remove a user from a domain. The user must be logged in to run this method. This method will delete the user history from the domain xml files. This method however will not Delete a user, and they will still be able to log into any other domains of which they have access, and accounts for.

Specified by:
removeUser in interface TutorInterface
Parameters:
userName - The user name of the user.
domainName - The name of the Domain the user is to be removed from.
Throws:
DomainNotFoundException - If the domain could not be found.
DomainNotLoadedException - If the requested domain is not loaded.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user was not logged in.
java.rmi.RemoteException

deleteUser

public void deleteUser(java.lang.String userName)
                throws DomainNotFoundException,
                       DomainNotLoadedException,
                       UserNotFoundException,
                       UserNotLoggedInException,
                       java.rmi.RemoteException
Description copied from interface: TutorInterface
Delete a user from the JITAS system. The user must be logged in to run this method. This method will delete the user history from the domain xml files and the JITAS system (students.xml). This method will Delete a user, and they will not be able to log into any domains.

Specified by:
deleteUser in interface TutorInterface
Parameters:
userName - The user name of the user.
Throws:
DomainNotFoundException - If the domain could not be found.
DomainNotLoadedException - If the user is logged into a domain that's not loaded.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user was not logged in.
java.rmi.RemoteException

addAllowedDomain

public void addAllowedDomain(java.lang.String userName,
                             java.lang.String domainName)
                      throws AddUserDeniedException,
                             DomainNotFoundException,
                             DomainNotLoadedException,
                             StudentModelAlreadyExistsException,
                             UserNotFoundException,
                             java.rmi.RemoteException
Description copied from interface: TutorInterface
This method will attempt to give the user access to the specific domain. If the domain does not allow users to add themselves then a AddUserDeniedException will be thrown. Allows a student to log into a new domain.

Specified by:
addAllowedDomain in interface TutorInterface
Parameters:
userName - the user name of the user
domainName - the name of the domain the student wishes to have access to.
Throws:
AddUserDeniedException - If new users are not allowed to be added to the domain.
DomainNotFoundException - thrown if the domain with domainName is not found.
DomainNotLoadedException - If the requested domain is not loaded.
StudentModelAlreadyExistsException - If a student model already exists
UserNotFoundException - thrown if the student with user name userName is not found
java.rmi.RemoteException

addAllowedDomain

public void addAllowedDomain(java.lang.String userName,
                             java.lang.String domainName,
                             boolean bypassSecurity)
                      throws AddUserDeniedException,
                             DomainNotFoundException,
                             DomainNotLoadedException,
                             StudentModelAlreadyExistsException,
                             UserNotFoundException,
                             java.rmi.RemoteException
Throws:
AddUserDeniedException
DomainNotFoundException
DomainNotLoadedException
StudentModelAlreadyExistsException
UserNotFoundException
java.rmi.RemoteException

changePassword

public void changePassword(java.lang.String userName,
                           java.lang.String oldPassword,
                           java.lang.String newPassword)
                    throws InvalidPasswordException,
                           UserNotFoundException,
                           java.rmi.RemoteException
Description copied from interface: TutorInterface
Change user's existing password to a new password. The user must be logged in to run this method.

Specified by:
changePassword in interface TutorInterface
Parameters:
userName - The user name of the user.
oldPassword - The users current password
newPassword - The new password that the user wants to change to.
Throws:
InvalidPasswordException - if the current password given is invalid
java.rmi.RemoteException
UserNotFoundException

getAllStudentUsernames

public java.util.Set<java.lang.String> getAllStudentUsernames()

getAllStudentUsernames

public java.util.Set<java.lang.String> getAllStudentUsernames(java.lang.String filter)

isStudentAllowedInDomain

public boolean isStudentAllowedInDomain(java.lang.String userName,
                                        java.lang.String domainName)
                                 throws UserNotFoundException
Throws:
UserNotFoundException

isUserCreationAllowed

public boolean isUserCreationAllowed(java.lang.String domainName)
                              throws DomainNotFoundException,
                                     DomainNotLoadedException
Throws:
DomainNotFoundException
DomainNotLoadedException

refreshStudentList

public void refreshStudentList()
                        throws java.io.FileNotFoundException
Throws:
java.io.FileNotFoundException

getAllDomainNames

public java.util.Set<java.lang.String> getAllDomainNames()
                                                  throws java.rmi.RemoteException
Returns the names of all the domains this tutor knows about (loaded or otherwise)

Specified by:
getAllDomainNames in interface TutorInterface
Returns:
Set of domain names
Throws:
java.rmi.RemoteException

getAllLongDomainNames

public java.util.Map<java.lang.String,java.lang.String> getAllLongDomainNames()
                                                                       throws java.rmi.RemoteException
This gets the long domain names for all loaded domains

Specified by:
getAllLongDomainNames in interface TutorInterface
Returns:
Map
Throws:
java.rmi.RemoteException

getSubdomains

public java.util.Set<java.lang.String> getSubdomains(java.lang.String domainName)
                                              throws DomainNotFoundException,
                                                     DomainNotLoadedException,
                                                     java.rmi.RemoteException
Description copied from interface: TutorInterface
Returns a set of all the subdomain names in a given domain, as Strings. A domain must be loaded before this method can be called successfully.

Specified by:
getSubdomains in interface TutorInterface
Parameters:
domainName - The name of the domain.
Returns:
A set of subdomain names.
Throws:
DomainNotFoundException - if the domain is not found (or not loaded).
DomainNotLoadedException - If the requested domain is not loaded
java.rmi.RemoteException

loadDomain

public void loadDomain(java.lang.String domainName)
                throws DomainNotFoundException,
                       java.rmi.RemoteException
Load the domain from XML

Specified by:
loadDomain in interface TutorInterface
Parameters:
domainName - The name of the domain you want to load.
Throws:
DomainNotFoundException - if the Domain is not found.
java.rmi.RemoteException

selectSubdomain

public void selectSubdomain(java.lang.String userName,
                            java.lang.String subdomainName,
                            java.lang.String domainName)
                     throws DomainNotFoundException,
                            DomainNotLoadedException,
                            ProblemsNotFoundException,
                            SubdomainNotFoundException,
                            UserNotFoundException,
                            UserNotLoggedInException,
                            java.rmi.RemoteException
Description copied from interface: TutorInterface
Allows a user to select a subdomain to work on.

Specified by:
selectSubdomain in interface TutorInterface
Parameters:
userName - The name of the user.
subdomainName - The name of the subdomain the student wants to work on.
domainName - The name of the domain the student is working on.
Throws:
DomainNotFoundException - If the domain could not be found.
DomainNotLoadedException - If the requested domain is not loaded.
ProblemsNotFoundException - If no problems could be found for the subdomain.
SubdomainNotFoundException - If the Subdomain is not found.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user is not logged in to the domain.
java.rmi.RemoteException

getNextProblem

public Problem getNextProblem(int problemNumber,
                              java.lang.String userName,
                              java.lang.String domainName)
                       throws DomainNotFoundException,
                              DomainNotLoadedException,
                              InvalidProblemException,
                              UserNotFoundException,
                              UserNotLoggedInException,
                              java.rmi.RemoteException
Description copied from interface: TutorInterface
Gets the next problem, specified by the user.

Specified by:
getNextProblem in interface TutorInterface
Parameters:
problemNumber - The number(id) of the problem the user wants.
userName - The name of the user.
domainName - The name of the domain.
Returns:
The problem object
Throws:
DomainNotFoundException - If the domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.
InvalidProblemException - If the problem cannot be found.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user is not logged in to the domain.
java.rmi.RemoteException

getNextProblem

public Problem getNextProblem(java.lang.String userName,
                              java.lang.String domainName)
                       throws DomainNotFoundException,
                              DomainNotLoadedException,
                              InvalidProblemException,
                              UserNotFoundException,
                              UserNotLoggedInException,
                              java.rmi.RemoteException
Description copied from interface: TutorInterface
Gets the next problem, based on the current problem number. The problem with the next highest id number that has not been completed by the student is returned.

Specified by:
getNextProblem in interface TutorInterface
Parameters:
userName - The name of the user who wants the problem.
domainName - The name of the domain.
Returns:
The problem object
Throws:
DomainNotFoundException - If the domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.
InvalidProblemException - If the problem cannot be found.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user is not logged in to the domain.
java.rmi.RemoteException

setCustomProblemSelectionAlgorithm

public void setCustomProblemSelectionAlgorithm(java.lang.String domainName,
                                               java.lang.String fileName)
                                        throws DomainNotFoundException,
                                               DomainNotLoadedException
Description copied from interface: TutorInterface
Set the custom problem selection algorithm for a domain. A class implementing ProblemSelectionAlgorithm should be in a jar located in domains//CustomProblemSelectionAlgorithm.jar This will be different if you are not using the default path

Specified by:
setCustomProblemSelectionAlgorithm in interface TutorInterface
Parameters:
domainName - The domain name
fileName - The class name of the class in the jar
Throws:
DomainNotFoundException - If the domain doesn't exist
DomainNotLoadedException - If the domain is not loaded

setCustomFeedback

public void setCustomFeedback(java.lang.String domainName,
                              java.lang.String fileName)
                       throws DomainNotFoundException,
                              DomainNotLoadedException
Description copied from interface: TutorInterface
Set the custom feedback object for a domain. A class implementing Feedback should be in a jar located in domains//Feedback.jar This will be different if you are not using the default path

Specified by:
setCustomFeedback in interface TutorInterface
Parameters:
domainName - The domain namee
fileName - The class name of the class in the jar
Throws:
DomainNotFoundException - If the domain doesn't exist
DomainNotLoadedException - If the domain is not loaded

getProblem

public Problem getProblem(java.lang.String userName,
                          java.lang.String domainName)
                   throws DomainNotFoundException,
                          DomainNotLoadedException,
                          java.lang.InstantiationException,
                          java.lang.IllegalAccessException,
                          java.rmi.RemoteException,
                          UserNotFoundException,
                          InvalidProblemException
Description copied from interface: TutorInterface
Gets the next problem, specified by the system. The system runs an algorithm to determine what problem to give the student next. The problem is returned as a Problem Object

Specified by:
getProblem in interface TutorInterface
Parameters:
userName - The name of the user who wants the problem.
domainName - The name of the domain.
Returns:
The problem object
Throws:
DomainNotFoundException - If the domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.
java.lang.InstantiationException - If instantiation fails.
java.lang.IllegalAccessException - when an application tries to reflectively create an instance (other than an array),set or get a field, or invoke a method.
java.rmi.RemoteException
UserNotFoundException
InvalidProblemException

getAllProblems

public java.util.SortedMap<java.lang.Integer,Problem> getAllProblems(java.lang.String userName,
                                                                     java.lang.String domainName)
                                                              throws DomainNotFoundException,
                                                                     DomainNotLoadedException,
                                                                     UserNotFoundException,
                                                                     UserNotLoggedInException,
                                                                     java.rmi.RemoteException
Description copied from interface: TutorInterface
Gets all the problems in the current working subdomain of the domain and returns them as a SortedMap. This can then be used by the users to choose what problem they want to do next.

Specified by:
getAllProblems in interface TutorInterface
Parameters:
userName - The name of the user who wants the problem.
domainName - The name of the domain.
Returns:
A sorted map of Problem objects
Throws:
DomainNotFoundException - If the domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user is not logged in to the domain.
java.rmi.RemoteException

getProblemStatus

public java.lang.String getProblemStatus(java.lang.String userName,
                                         java.lang.String domainName,
                                         int problemID)
                                  throws UserNotFoundException,
                                         UserNotLoggedInException,
                                         java.rmi.RemoteException,
                                         DomainNotFoundException,
                                         DomainNotLoadedException
Description copied from interface: TutorInterface
Get the status of a problem for a particular domain and user.

Specified by:
getProblemStatus in interface TutorInterface
Parameters:
userName - The name of the user
domainName - The name of the domain
problemID - The id of the problem you want the status of
Returns:
The status of the problem
Throws:
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user is not logged in to the domain.
java.rmi.RemoteException
DomainNotFoundException - If the domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.

submitSolution

public Feedback submitSolution(Solution studentSolution,
                               java.lang.String userName,
                               java.lang.String domainName)
                        throws DomainNotFoundException,
                               DomainNotLoadedException,
                               InvalidSolutionException,
                               StudentModelNotFoundException,
                               UserNotFoundException,
                               UserNotLoggedInException,
                               jess.JessException,
                               java.rmi.RemoteException
Description copied from interface: TutorInterface
Used when a student wishes to submit their solution to the current problem. This method will evaluate the student's solution against the domain constraints, and returns a Feedback Object. The constraints and attempt both need to be sent to the evaluator, which will do the actual evaluation. A Solution has the following structure: (("CASE" "N")("GENDER" "N")("ARTICLE" "D")("ANSWER" "graue")) This method uses the Students current problem to the the ideal solution

Specified by:
submitSolution in interface TutorInterface
Parameters:
studentSolution - the students attempt, in a String of key-value pairs.
userName - The name of the user who wants the problem.
domainName - The name of the domain.
Returns:
A Feedback Object.
Throws:
DomainNotFoundException - If the supplied domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.
InvalidSolutionException - If either the students or ideal solution is invalid.
StudentModelNotFoundException - If the students StudentModel cannot be found.
UserNotFoundException - If the user could not be found.
UserNotLoggedInException - If the user is not logged in to the domain.
jess.JessException - If something goes wrong in Jess (the rule engine)
java.rmi.RemoteException