jitas.core
Interface TutorInterface

All Known Implementing Classes:
Tutor

public interface TutorInterface

The interface class for the Java Intelligent Tutor Authoring Shell (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.

Version:
24 August 2007
Author:
DeathMarch (c314g2) - David Thomson, Farah Mohamad, Louis Sayers, Lu Pan, Robert Lechte, Yuganeethen Yugaraja

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 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 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 a set of names of all the Domains that JITAS "knows" about.
 java.util.Map<java.lang.String,java.lang.String> getAllLongDomainNames()
          Gets all the names for the currently loaded domains as a map of pairs.
 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.
 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.
 void loadDomain(java.lang.String domainName)
          Loads a specified Domain from a .xml file.
 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 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.
 

Method Detail

login

void login(java.lang.String userName,
           java.lang.String password,
           java.lang.String domainName)
           throws DomainNotFoundException,
                  DomainNotLoadedException,
                  InvalidLoginException,
                  UserNotFoundException,
                  java.rmi.RemoteException
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.

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).
UserNotFoundException - If the user does not exist.
java.rmi.RemoteException

logout

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

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

boolean getLoginStatus(java.lang.String userName,
                       java.lang.String domainName)
                       throws UserNotFoundException,
                              java.rmi.RemoteException
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)

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

void addUser(java.lang.String userName,
             java.lang.String password,
             java.lang.String domainName)
             throws AddUserDeniedException,
                    DomainNotFoundException,
                    DomainNotLoadedException,
                    IllegalUserNameException,
                    StudentModelAlreadyExistsException,
                    java.rmi.RemoteException
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.

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

removeUser

void removeUser(java.lang.String userName,
                java.lang.String domainName)
                throws DomainNotFoundException,
                       DomainNotLoadedException,
                       UserNotFoundException,
                       UserNotLoggedInException,
                       java.rmi.RemoteException
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.

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

void deleteUser(java.lang.String userName)
                throws DomainNotFoundException,
                       DomainNotLoadedException,
                       UserNotFoundException,
                       UserNotLoggedInException,
                       java.rmi.RemoteException
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.

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

void addAllowedDomain(java.lang.String userName,
                      java.lang.String domainName)
                      throws AddUserDeniedException,
                             DomainNotFoundException,
                             DomainNotLoadedException,
                             StudentModelAlreadyExistsException,
                             UserNotFoundException,
                             java.rmi.RemoteException
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.

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

changePassword

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

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
UserNotLoggedInException - If the user was not logged in.
java.rmi.RemoteException
UserNotFoundException

getAllDomainNames

java.util.Set<java.lang.String> getAllDomainNames()
                                                  throws java.rmi.RemoteException
Returns a set of names of all the Domains that JITAS "knows" about. This can be called before a user logs in.

Returns:
A set of domain names
Throws:
java.rmi.RemoteException

getAllLongDomainNames

java.util.Map<java.lang.String,java.lang.String> getAllLongDomainNames()
                                                                       throws java.rmi.RemoteException
Gets all the names for the currently loaded domains as a map of pairs. Note: there is no garantee that any particular long name is not null.

Returns:
A map of name, longName pairs
Throws:
java.rmi.RemoteException

getSubdomains

java.util.Set<java.lang.String> getSubdomains(java.lang.String domainName)
                                              throws DomainNotFoundException,
                                                     DomainNotLoadedException,
                                                     java.rmi.RemoteException
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.

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

void loadDomain(java.lang.String domainName)
                throws DomainNotFoundException,
                       jess.JessException,
                       java.rmi.RemoteException
Loads a specified Domain from a .xml file. This includes loading all the problems and constraints. This can safely be called on a already loaded domain.

Parameters:
domainName - The name of the domain you want to load.
Throws:
DomainNotFoundException - if the Domain is not found.
jess.JessException - If something goes wrong in Jess (the rule engine)
java.rmi.RemoteException

selectSubdomain

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

Parameters:
userName - The name of the user.
domainName - The name of the domain the student is working on.
subdomainName - The name of the subdomain the student wants to work 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

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

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

Problem getNextProblem(java.lang.String userName,
                       java.lang.String domainName)
                       throws DomainNotFoundException,
                              DomainNotLoadedException,
                              InvalidProblemException,
                              UserNotFoundException,
                              UserNotLoggedInException,
                              java.rmi.RemoteException
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.

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

void setCustomProblemSelectionAlgorithm(java.lang.String domainName,
                                        java.lang.String fileName)
                                        throws DomainNotFoundException,
                                               DomainNotLoadedException
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

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

void setCustomFeedback(java.lang.String domainName,
                       java.lang.String fileName)
                       throws DomainNotFoundException,
                              DomainNotLoadedException
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

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

Problem getProblem(java.lang.String userName,
                   java.lang.String domainName)
                   throws DomainNotFoundException,
                          DomainNotLoadedException,
                          java.lang.InstantiationException,
                          java.lang.IllegalAccessException,
                          java.rmi.RemoteException,
                          UserNotFoundException,
                          InvalidProblemException
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

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

java.util.SortedMap<java.lang.Integer,Problem> getAllProblems(java.lang.String userName,
                                                              java.lang.String domainName)
                                                              throws DomainNotFoundException,
                                                                     DomainNotLoadedException,
                                                                     UserNotFoundException,
                                                                     UserNotLoggedInException,
                                                                     java.rmi.RemoteException
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.

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

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

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.
DomainNotFoundException - If the domain cannot be found.
DomainNotLoadedException - If the requested domain is not loaded.
java.rmi.RemoteException

submitSolution

Feedback submitSolution(Solution studentSolution,
                        java.lang.String userName,
                        java.lang.String domainName)
                        throws DomainNotFoundException,
                               DomainNotLoadedException,
                               InvalidSolutionException,
                               StudentModelNotFoundException,
                               UserNotFoundException,
                               UserNotLoggedInException,
                               jess.JessException,
                               java.rmi.RemoteException
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

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