DataShop - Logging Package

Table of Contents

• 1. Introduction
• 2. Package Organization
• 3. Loggers included in this API
  • 3.1 FileLogger
  • 3.2 OLI DiskLogger
  • 3.2 OLI DatabaseLogger
• 4. How to Log
• 5. Classes
• 5.1 File Logger
• 5.2 Context Message
• 5.3 Tool Message
• 5.4 Tutor Message
• 6. Version Information
• 7. Code Sample

1. Introduction [top]

The Tutor Logging API, provided by the DataShop, is a Java package intended to make the logging of tutor messages easier for anyone developing a tool, tutor, or authoring tool using Java. This API follows the tutor_message_v4.xsd schema which is detailed in the Guide to the Tutor Message Format. This guide serves as a single resource for all information regarding the Tutor Message Format, including element and attribute descriptions, diagrams, code examples as well as DataShop XML processing expectations. You may also find the sample XML file another useful reference.

In this document the word tool refers to the front-end, user interface. Tool messages should be logged when the student makes an action. Tool messages should also be used for media events. The word tutor refers to the backend system, e.g. the tutor, which logs whether an answer is correct, incorrect or provides hints. Tutor messages are logged when the system responds to the student’s action.

The API conforms to Version 4 of the Tutor Message Format.

2. Package Organization [top]

The DataShop Logging package is organized in the following manner:

3. Loggers included in this API [top]

There are three types of loggers provided by this library, the FileLogger, OLIDiskLogger and OLIDatabaseLogger.

3.1 FileLogger

The FileLogger is a simple file logger, which creates a well-formed XML file. This type of file can easily be read into the DataShop.

3.2 OLI DiskLogger

The Oli DiskLogger creates a file which can easily be imported into an OLI-style log database. It is not, however, easily read with the naked eye.

3.3 OLI DatabaseLogger

The OliDatabaseLogger logs directly to an OLI-style log database. Use this logger with caution, as we don’t want to fill up either test or production databases with a lot of test data. It is recommended that you start first with the FileLogger so that the results can easily be checked for correctness.

4. How to Log [top]

The general steps are as follows:

1. Create a logger.
2. For each new problem that the student starts, create a ContextMessage and fill in the details.

e.g. ContextMessage contextMsg = ContextMessage. createStartProblem (metaElement);

3. Log that message.
4. The tool (i.e. UI application) should create and log a ToolMessage to capture what the student actually did.
5. The tutor (i.e. the backend system) should then log a response using a TutorMessage, to capture whether the student was right/wrong and what they should’ve done in case they were wrong.

Note: that with this complete rewrite of the logging library, every effort was made to reduce the size of the logging library itself and reduce the number of dependencies. The logging library no longer depends on the log4j or jdom jars, but only depends on the OLI logclient.jar. The reduction in size was done primarily to support Java applets.

The datashop-logging.jar is 52 k.

The logclient.jar is 23 k.

Note: If you need a version that does not depend even on the logclient.jar, please contact us. We can easily do that too.

5. Classes [top]

A subset of classes and methods are outlined below. For detailed information about the classes provided in the datashop-logging.jar, please reference the Javadoc API.

Also see the sample application for more details.

5.1 FileLogger

Create one logger to log messages across a span of attempts and responses.

FileLogger fileLogger = FileLogger.create("MyPlainFile.xml");

Note: When logging to files, you may want to produce multiple files, perhaps a file per student.

5.2 ContextMessage

This message is needed to put the problem in context. Logging this information once instead of with every tool and tutor message saves space.

String timeString = "2006-08-30 11:22:33";
MetaElement metaElement = new MetaElement(userId, sessionId, timeString, timeZone);
ContextMessage contextMsg = ContextMessage.createStartProblem(metaElement);>

Generating globally unique IDs:

This can be done with the generageGUID method. This will return something like: “JUNK-2c72fcf0:10d8424c05d:-8000”

String sessionId = Message.generateGUID("JUNK");

The time string can be of the following formats:

• yyyy-MM-dd HH:mm:ss.SSS
• yyyy-MM-dd HH:mm:ss
• yyyy-MM-dd HH:mm
• MMMMM dd, yyyy hh:mm:ss a
• MM/dd/yy HH:mm:ss:SSS
• MM/dd/yy HH:mm:ss

5.3 ToolMessage

Create a tool message for student’s action:

ToolMessage toolMsg = ToolMessage.create(contextMsg);
toolMsg.setProblemName(problemName);

To log an attempt at a step in the problem:

toolMsg.setAsAttempt();

To log a request for help at a step in the problem:

toolMsg.setAsHintRequest();

To add the Selection, Action and Input to the message, i.e. what the student actually did:

toolMsg.addSai("TextBox1", "EnterText", "box");

To log this message:

fileLogger.log(toolMsg);

5.4 TutorMessage

Create a tutor message when responding to the student's action:

TutorMessage tutorMsg = TutorMessage.create(toolMsg);

To log a system response to the student's attempt at a step in a problem:

tutorMsg.setAsCorrectAttemptResponse();

To log a system response to the student's request for a hint:

tutorMsg.setAsHintResponse();

To add the Selection, Action and Input to the message, i.e. what the student should’ve done:

tutorMsg.addSai("ButtonOne", "PressButton", "square");

To add a skill to the response:

tutorMsg.addSkill(new SkillElement("Dictation", "General", "Basic"));

To log this message:

fileLogger.log(tutorMsg);

6. Version Information [top]

To get the version of the jar file, execute a command something like this:

java -classpath "dist/datashop-logging.jar;extlib/log4j-1.2.13.jar" edu.cmu.pslc.datashop.util.VersionInformation

7. Code Sample [top]

To run the sample application which produces a log file to the local disk, execute something like this:

java -classpath "dist/datashop-logging.jar;extlib/logclient.jar;extlib/commons-lang-2.2.jar" edu.cmu.pslc.logging.Sample

Also see the Sample.java to see how these classes are used.