Changes from Sample RTE Version 1.2.1 to Version 1.2.2

1. The interactions data model element children changed from "id,objective_ids,time,type,correct_responses,weighting,student_response,result,latency" to "id,objectives,time,type,correct_responses,weighting,student_response,result,latency".

Changes from Sample RTE Version 1.2 to Version 1.2.1

1. The return error code for LMSSetValue calls on list elements that are non-sequential has been changed to 201.
2. Improper error codes were being returned for errors resulting from the values for certain data model elements such as cmi.student_preference being out of bounds. These error codes have also been changed.

Changes from Sample RTE Version 1.1

Welcome to the Advanced Distributed Learning (ADL) SCORM Version 1.2 Sample Run-Time Environment (RTE) Version 1.2.2. This Sample RTE is intended to provide an example implementation of the concepts described in the SCORM. Specifically, this sample was developed in order to provide an illustration of Content Packaging and the SCORM Run-Time Environment. The main focus is on the Run-Time Environment communication between the RTE and Sharable Content Objects (SCOs) using the API mechanism described in the SCORM. Robust exception and error handling has not been included in this sample code.

There are a number of possible Web-enabled implementations. This version of the Sample RTE was implemented as a Web-based client/server application using HTML, JavaScript, JavaServer Pages (JSP), Java Applets, Java Servlets, and Java Applications (See Section III of this readme for details). Specifically, this sample code consists of the following components:

1. Run-Time Environment Server Component: Implemented using Java Applications and Java Servlets.
2. Run-Time Environment Client Component: Implemented using JSP, Java Applets, HTML, and JavaScript.
3. Sample Course: Implemented using HTML and JavaScript.

The Run-Time Environment server component is implemented using Java Servlets and HTML. The Servlets respond to requests from the Run-Time Environment client component and are responsible for data model persistence as well as serving the student course menu, the course lesson menu and launching the selected lesson.

The server components are described below:

LMSManifestHandler.java
This Java class is responsible for accessing information in the imsmanifest.xml file, and storing it in the Sample RTE database.

LMSPackageHandler.java
Provides a zip utility to access and extract the imsmanifest.xml file from a Content Package represented as a Package Interchange File (PIF).

LMSCMIServlet.java
Provides a mechanism for communication between the Run-Time Environment server component and SCOs. This particular implementation is specifically for the data model that is described in the SCORM. Other modules could be created to handle other data models as they come into existence. The "LMSCMIServlet" sends and receives serialized data model objects via HTTP to and from the Run-Time Environment client component (see below). Data persistence is handled by Java's built-in serialization mechanism using a file on the local file system.

Sample Run-Time Environment Client Component (Java Files)

The Run-Time Environment client side component consists of a sample user interface implemented in HTML and JavaScript and the Run-Time Environment API Adapter implemented as a Java Applet. The Applet is downloaded to the client when the user accesses the Run-Time Environment main start page through a Web browser. The API Adapter Applet provides the communication to the Run-Time Environment server component for data model element persistence. The SCOs make calls to the API functions from JavaScript. (See the description of the sample course below for a description of how the RTE API function calls are made from the SCOs). The SCOs do not need to know about any of the RTE implementation details.

The Java client components are described below:

APIAdapterApplet.java
This contains the full implementation of the API Adapter that is described in The SCORM. This file implements the Run-Time Environment API functions (i.e. LMSInitialize(), LMSFinish(), etc.).

LMSErrorManager.java
This contains the LMSErrorManager class, which encapsulates the error handling capabilities specified for the Run-Time Environment API. It maintains the most recent error code and the mapping of error codes to the error text and diagnostic information.

ServletProxy.java
This contains the ServletProxy class that encapsulates the communication between the Run-Time Environment client component API Adapter Applet and the Run-Time Environment server component.

ServletWriter.java
This contains the ServletWriter class that provides the low level input and output serialized object-streaming capability that is used by ServletProxy to actually communicate with the Servlets via HTTP. This class was downloaded from www.javasoft.com.

Sample Run-Time Environment Client Component (Web Files) is divided into the following main conceptual modules:

User Interfaces
The interfaces provide the ability to login, logout, register and unregister for courses, view courses, and gain access to online help built into the Sample RTE. The following files comprise the user interfaces:

courseRegister.jsp LMSLogin.jsp LMSMenu.jsp LMSLogin.htm LMSLogin2.htm LMSMain.htm LMSNext.htm LMSStart.htm

importHelp.htm launchCourseHelp.htm newUserHelp.htm gotoMenu.jsp logout.jsp processChangePwd.jsp processCourseReg.jsp viewCourses.jsp

courseComplete.jsp changePwd.jsp changePwd2.htm changePwdHelp.htm courseRegisterHelp.htm confirmImport.jsp readme.htm

Administration
The administration files provide the ability to import courses, manage courses, and manage users. The following files comprise the administration module:

clearDatabase.jsp deleteCourse.jsp deleteUser.jsp

processDeleteCourse.jsp processDeleteUser.jsp processNewUser.jsp

importCourse.jsp newUser.jsp

Functional
These files provide the API Adapter, allow sequencing and provide navigation controls. The following files comprise the functional module:

• LMSFrame.jsp
  This page contains the API Adapter designed as an Applet. The API Adapter has no visual display elements and is therefore invisible to the user. Note that the API Adapter object is exposed to SCOs via the LMSMain.htm page. The SCOs communicate with the Run-Time Environment through this API. This page also contains the Run-Time Environment login and logout buttons.
• code.jsp
  This file is used to setup the look and feel of the menu. JavaServer Pages (JSP) is used to dynamically create the menu structure based on the imsmanifest.xml item elements.
• LMSCourseImport.jsp
  This file is responsible for moving the PIF to the server, extracting the files, and moving the files under the web root. This file includes the LMSManifestHandler and the LMSPackageHandler. See the server component for details.
• importUtil.jsp
  This file contains importing utilities used by LMSCourseImport.jsp.
• pleaseWait.jsp
  This file is used to set up client-side variables before the next course item is presented
• sequencingEngine.jsp
  This file is responsible for the sequencing of a course. At this time, sequencing occurs as a preordered transversal of items defined in the manifest organization. There is currently an investigation into sequencing issues. The results will find their way into a future version of The SCORM. This sequencing and navigation implementation is specific to this RTE and in no way represents a SCORM sequencing model.
  At this time, sequencing occurs as follows:
  • A NEXT REQUEST (The user clicks the "next" button on the top RTE frame):
    This launches the next logical item from the manifest's organization structure.
  • A PREVIOUS REQUEST (The user clicks the "previous" button on the top RTE frame):
    This launches the previous logical item from the manifest's organization structure.
  • A MENU REQUEST (The user clicks a menu option in the left RTE frame):
    This serves the resource that is associated with the item that the user selected.
  • FIRST LAUNCH OF COURSE SESSION (The user selects a course to view):
    This launches the first item from the manifest's organization structure that is not in a completed state.

  At this time prerequisites and mastery do not factor into sequencing decisions.

  At this time, the controls present during a course are selected by an administrator during import. The control modes available are "flow" (Previous and Next buttons are presented) and "choice" (a menu tree representing the manifest's organization structure is presented).

SCORM Run-Time Environment Data Model

The SCORM Run-Time Environment Data Model is derived from the AICC CMI Data Model and is the only data model that is currently used to communicate from the SCOs to the Run-Time Environment. At this time all of the data elements are implemented in this Sample RTE. Several classes are included to represent the data elements of the data model. These classes are used by both the Servlets and the API Adapter Applet.

The source for these classes is as follows:

CMICore.java
Contains the implementation of the cmi.core data model elements needed for the SCO to LMS communication.

CMISuspendData.java
Contains the implementation of the cmi.suspend_data data model elements needed for the SCO to LMS communication.

CMILaunchData.java
Contains the implementation of the cmi.launch_data data model elements needed for the SCO to LMS communication.

CMIComments.java
Contains the implementation of the cmi.comments data model elements needed for the SCO to LMS and communication.

CMICommentsFromLms.java
Contains the implementation of the cmi.comments_from_lms data model elements needed for the SCO to LMS communication.

CMIObjectives.java / CMIObjectiveData.java
Contains the implementation of the cmi.objectives data model elements needed for the SCO to LMS communication.

CMIInteractions.java / CMIInteractionData.java
Contains the implementation of the cmi.interactions data model elements needed for the SCO to LMS communication.

CMIStudentData.java
Contains the implementation of the cmi.student_data data model elements needed for the SCO to LMS communication.

CMIPreferences.java
Contains the implementation of the cmi.student_preference data model elements needed for the SCO to LMS communication.

Supporting Classes - used by the SCORM Run-Time Environment Data Model Classes:

CMIScore.java
Contains an implementation of the Score element used by the data model.

Element.java
Class used to represent the base element (i.e. cmi.core.student_id).

CMICategory.java
Class used to encapsulate commonality between the CMI Categories.

CMIRequest.java
Class used to represent a Request from a SCO (i.e. LMSGetValue(cmi.core.student_id) ).

CMITime.java
Contains the implementation of the CMITime data type.

DataModelValidator.java
Contains the implementation of a class that parses and validates LMSSetValue and LMSGetValue requests.

DataModelInterface.java
Class that contains the implementation of the interface between the RTE API Adapter and the rest of the data model implementation.

SCODataManager.java
Class that manages the data model elements for a single Sharable Content Object.

DMErrorManager.java
Contains the implementation of a Data Model Error Manager. This class manages error state related specifically to data model errors.

Sample Run-Time Environment Debug Indicator

The DebugIndicator.java is a class that contains a static attribute that is used to indicate to other Java classes if Debug is turned on. If debug is turned on, then debug statements will be displayed. Debug information from the Run-Time Environment server side will be displayed in the Web server console window. Debug information from the Run-Time Environment client side API Adapter will be printed to the Java Runtime Environment (JRE 1.4.2_02 recommended) Java Console if running in Microsoft Internet Explorer, or to the Netscape Java Console if running in Netscape Navigator. The DebugIndicator can be set to on to present debug information in the consoles (this may slow down the Sample Run-Time Environment). However, this requires recompilation of the source code.

RTE Sample Maritime Navigation Course

The course provided with the Sample Run-Time Environment contains one lesson. It is designed as a simple "page turner" lesson consisting of seven SCOs. The course is not meant to serve as an example of instructionally sound learning content, but rather as an example of how to communicate data between the Run-Time Environment and the SCOs using the API.

The lesson implementation makes use of two JavaScript "include" files called APIWrapper.js and SCOFunctions.js. The APIWrapper.js file contains a set of "API wrapper" functions that encapsulate the functionality that a SCO might use to find and communicate with the LMS Run-Time Environment via the API. The SCOFunctions.js file contains JavaScript navigation functions used by all of the SCO HTML pages. It is included at run-time in each of the SCO HTML pages.

The API wrapper does not implement the API functions, but rather encapsulates the logic needed to:

1. Find the API in the LMS client framework
2. Call the desired API function
3. Handle errors that might be generated by the call to the API function.

The SCOs that comprise the HTML implementation of Lesson 01 consist of the following files:

1. scoXX.htm

Each SCO that is launched in the course either has an assessment or a review question at the end. In order to get a cmi.core.lesson_status set to a completed state (completed or passed), you must experience the review questions. If the SCO is unloaded before completion the status will remain incomplete.

The example Maritime Navigation course PIF file is located in the Sample RTE installation directory and is called "ADL_Maritime_Navigation.zip". To run this course it must be imported into the Sample RTE and the user must register for it.

Back to Top

It is recommended that you read through all of the installation instructions prior to beginning installation.

Prerequisites

Sun Java 2 SDK Standard Edition 1.4.2_02
The Sample RTE is built using Sun's Java 2 SDK Standard Edition Version 1.4.2_02, including the Java 2 Runtime Environment, Standard Edition Version 1.4.2_02. In addition, when running the Sample RTE in Microsoft Internet Explorer, the Java 2 Runtime Environment, Standard Edition 1.4.2_02 is used to provide the Java Virtual Machine (JVM) instead of relying on the Microsoft JVM. The Apache Jakarta-Tomcat Servlet Container and Web server that is included with the Sample RTE also requires the Java 2 SDK, so it is imperative that it be installed prior to running the RTE.

Notes:

• If you install the Sample RTE on one machine and intend to access it from another machine using Microsoft Internet Explorer, the Sun Java 2 Runtime Environment, Standard Edition 1.4.2_02 must be installed on both machines.
• The Sample RTE requires the full Java 2 Software Development Kit (SDK). Alone, the Java 2 Run-Time Environment (JRE) is NOT sufficient.

The Sun Java 2 SDK Standard Edition is freely available at http://java.sun.com/j2se/1.4.2/download.html. It must be downloaded and installed prior to running the SCORM 2004 Sample RTE Version 1.2.2.

After installing the Java 2 SDK Standard Edition 1.4.2_02, you must do the following:

1. Add the full path of the SDK bin directory (where the java.exe is located) to the PATH environment variable (e.g. C:\j2sdk1.4.2_02\bin).
   • For Windows 2000 and XP: Right click on "My Computer", select "Properties", select the "Advanced" tab and then click on "Environment Variables". Add the SDK 1.4.2_02 bin directory to the Path by adding a semicolon followed by the bin directory.
   • For Windows NT: Select Start -> Control Panel. Select System, select Environment, and look for "Path" in the User Variables and System Variables. Add the SDK 1.4.2_02 bin directory to the Path by adding a semicolon followed by the bin directory.
   • For Window 98: Open and edit the AUTOEXEC.BAT file and add or change the PATH statement. To do so, click Start-> Run and enter Sysedit. Add the SDK 1.4.2_02 bin directory to the Path. This change requires a reboot to be effective.
2. Set a JAVA_HOME environment variable to the SDK 1.4.2_02 root directory (e.g. C:\j2sdk1.4.2_02)
   • For Windows 2000 and XP: Right click on "My Computer", select "Properties", select the "Advanced" tab and then click on "Environment Variables". Add a JAVA_HOME entry in the User or System Variables that points to the location where the SDK 1.4.2_02 was installed.
   • For Windows NT: Select Start -> Control Panel. Select System, select Environment. Add a JAVA_HOME entry in the User or System Variables that points to the location where the SDK 1.4.2_02 was installed.
   • For Window 98: Open and edit the AUTOEXEC.BAT file and add or change the PATH statement. To do so, click Start-> Run and enter Sysedit. Add the line "SET JAVA_HOME=" ending with the path pointing to the location where the SDK 1.4.2_02 was installed. This change requires a reboot to be effective.

Constraints

The Sample Run-Time Environment has been tested on Microsoft Windows 2000 Professional and Windows XP Professional, both on the Intel Pentium PC platform with Internet Explorer 5.5 and 6.0. It was not tested with any other browsers on any other platforms.

Installation

Installation of the Sample RTE is to be done only after installing the Sun Java 2 SDK Standard Edition 1.4.2_02.

TO INSTALL: Click on the Sample RTE self extracting executable file and follow the installation instructions on the screen.

NOTE: The jakarta-tomcat-5.0.16 Servlet Engine and Web server is pre-configured to run on port 8080.

This completes the installation of the Sample RTE.

Back to Top

The instructions provided are for running the Sample RTE on a Windows platform. This is the only platform that the software has been tested on and is the only platform that instructions are provided for at this time.

To Run the RTE:

First you need to start the jakarta-tomcat-5.0.16 that is provided with this installation. To do this:

• Click on the Start Menu -> Programs -> ADL -> SampleRTE1.2.2 -> Startup or click on the startup icon on your desktop. You will see a command prompt window open. This window will remain open until you stop the server.
  
• Next click on the Start Menu -> Programs -> ADL -> SampleRTE1.2.2 -> SampleRTE1.2.2 or click on the SampleRTE1.2.2 shortcut on your desktop. This will launch the RTE Main page. The first time that you visit this page you will need to login with username: "admin", password: "admin". (Be sure that Microsoft Internet Explorer is your default browser.)

Online help pages are available once the Sample RTE is started. "Help" links appear at the bottom of each page.

To stop the jakarta-tomcat-5.0.16 server click on the Start Menu -> Programs -> ADL -> SampleRTE1.2.2 -> shutdown or click on the shutdown shortcut on your desktop.

Back to Top

Sequencing and Navigation

Navigation controls are included in the Sample RTE to allow navigation through content. At this time the available controls are:

• flow: Previous and Next Buttons are presented on the top RTE frame.
  
  A Next Request launches the SCO or asset that is referenced by the next sequential item in the imsmanifest.xml file.
  A Previous Request launches the SCO or asset that is referenced by the previous sequential item in the imsmanifest.xml file.

• choice: A menu is presented in the left RTE frame.

On first launch of a course, the "cmi.core.lesson_status" of each SCO is checked for completion. Completion is determined by a value of "completed", "passed", or "failed". The first sequential item that is not completed is launched. (NOTE: To reset a learners status in a course, unregister for the course, and then re-register. See the online RTE help for details.) When all items are completed, the course becomes unavailable.

NOTE: The control type for a course is determined on import by the user. See the online RTE Help for details.

Known Issues

1. Occasionally the top and/or left RTE frame return an "Internal Server Error" when the RTE is first launched. Simply close the browser window and re-launch the RTE to alleviate.
2. If a package manifest contains references to external SCOs, a cross-domain JavaScript security error will occur. This may prevent communication between the SCOs and the RTE provided API.
3. The "Clear Database" option will remove all courses, course items, and course records from the internal RTE database. The actual files must be removed manually from:
   <webRoot>\webapps\adl\CourseImports\*.
4. The Microsoft Internet Explorer Browser must be set to check for a new page every visit to the page. To configure the browswer:
   • Open a Microsoft Internet Explorer Browser
   • Click on "Tools" -> "Internet Options"
   • On the "General" tab, "temporary internet files" sub-section, click "Settings"
   • Ensure that the "Every visit to the page" radio button is selected
   • Click "OK" Twice
5. If you intend to build the RTE and the installation directory of the Sample RTE contains spaces in the path, you will need to edit the ADL_SRTE122_HOME variable and use the XXXXXX~1 notation for any directories with spaces. This is due to the batch file that builds the Sample RTE. For example "Program Files" can be represented in the variable path as "PROGRA~1".
6. If an "out of environment space" error occurs when starting and stopping the jakarta-tomcat-5.0.16 server in Win9X/ME-based operating systems, use the following method to create shortcuts for starting and stopping the server. In Windows Explorer, right-click on the STARTUP.BAT and SHUTDOWN.BAT files located in the jakarta-tomcat\bin directory. Click on "Properties" then on the "Memory" tab. For the "Initial environment" field, enter 4096. After you click apply, Windows will create shortcuts in the directory which can be used to start and stop the server. These shortcuts may be copied to the desktop. The original shortcuts and the Start Menu items for starting and stopping the server will not work.

Third Party Components

The Sample RTE uses the following third party tools:

• jspSmartUpload
  The jspSmartUpload classes are used to move PIFs to the RTE Server.
  
  This code uses jpSmartUpload. jspSmartUpload - Copyright (c) 2001 ADVANTYS. All rights reserved. "This product includes software developed by Advantys (http://www.advantys.com)."
  
  
• Morten's JavaScript Tree Menu
  The Tree Menu is used when a course is running in choice mode. The menu is presented in the left RTE frame
  
  Morten's JavaScript Tree Menu version 2.3.0, dated 2001-04-30 http://www.treemenu.com/ Copyright (c) 2001, Morten Wang & contributors All rights reserved.
  
  
• This product includes software developed by the Apache Software Foundation ( http://www.apache.org )
  
   
  Please read the Apache License Agreement below or view it at http://xml.apache.org/LICENSE
  
   
  /*
  * The Apache Software License, Version 1.1
  *
  *
  * Copyright (c) 1999 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  *
  * 1. Redistributions of source code must retain the above copyright
  *   notice, this list of conditions and the following disclaimer.
  *
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in
  *    the documentation and/or other materials provided with the
  *    distribution.
  *
  * 3. The end-user documentation included with the redistribution,
  *    if any, must include the following acknowledgment: 
  *       "This product includes software developed by the
  *        Apache Software Foundation (http://www.apache.org/)."
  *    Alternately, this acknowledgment may appear in the software itself,
  *    if and wherever such third-party acknowledgments normally appear.
  *
  * 4. The names "Xerces" and "Apache Software Foundation" must
  *    not be used to endorse or promote products derived from this
  *    software without prior written permission. For written
  *    permission, please contact apache@apache.org.
  *
  * 5. Products derived from this software may not be called "Apache",
  *    nor may "Apache" appear in their name, without prior written
  *    permission of the Apache Software Foundation.
  *
  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  * ====================================================================
  *
  * This software consists of voluntary contributions made by many
  * individuals on behalf of the Apache Software Foundation and was
  * originally based on software copyright (c) 1999, International
  * Business Machines, Inc., http://www.ibm.com.  For more
  * information on the Apache Software Foundation, please see
  * http://www.apache.org/

Back to Top