Virtual Apparatus Framework Specification 1a

Last updated: 25th August, 1997 (provide guideline for the messages that are sent

Modification since created before last update: 22nd August, 1997 (provide alternate event notification mechanism)

Created: 1st August, 1997.

Copyright	All rights reserved by Albert Ip, 1997.
Condition of use	You may use this specification to develop education software component (refered to as "virtual apparatus" hereafter), without paying a fee if you agree to some conditions. Please refer to the accompanying file VA01COPY.txt for details.
Disclaimer	See this for details
Acknowledgement	The author acknowledges with thanks the contribution by Dr. Ric Canale, Mr. Paul Fritze and Mr. Gangmeng Ji during all the development stage of this specification.
Objective	To enable "virtual apparatus" to communicate and inter-operate when hosted by a scriptable web browser irrespective of the language and technology in which the educational software components are developed.
Supported Technology	This version of the specification supports Java Applets, ActiveX controls and Macromedia Shockmovie.
Supported Browsers	Netscape 3.0 or above, Internet Explorer 3.0 or above.
Compulsory behaviour	All "virtual apparatus" must support the following: Name Each "Virtual Apparatus" should be able to accept a name assigned by the author. This helps to ensure uniqueness when the same type of "Virtual Apparatus" have been instantiated more than once. The scripting mechanism will refer to the name as required. Vainfo All "Virtual Apparatus" will have an internal structure called VAinfo which will store the information about the "Virtual Apparatus". Version All "Virtual Apparatus" will have an internal variable called Version. The current "Virtual Apparatus" specification support version 0.x.xx only. In addition, version 0.0.xx applies to all "Virtual Apparatus" which partially meets the specification. "Virtual Apparatus" can only be promoted to 0.1.xx to 0.9.xx if all the compulsory behaviour decribed in this specification are fully complied with. Version number beginning with 1 or above is reserved pending the development of Java Bean and/or Active X and the support of shocked movies of either of these technologies. ChannelNum All "virtual apparatus" can be assigned a channel number through the parameter list in the html page. The default is Channel 0. VAmessenge() will route messages to specific channel when it is specified. If no channel is specified, VAmessenge() will broadcast the message to all the "virtual apparatus" hosted on the page. GetVAinfo() This is a compulsory method that must be supported by all "virtual apparatus". After being called, the "virtual apparatus" should fill the variable, VAinfo, in the scripting environment with its internal VAinfo. Exposed methods All "virtual apparatus" must expose the methods as sepecified in the VAinfo. Raising Events All "virtual apparatus" should raise events by calling a function called VAmessenger() in the scripting environment and passes the parameters as specified below. For technologies which do not allow raising events to the browser, it should allow at least one of the following: provide a getEvent() function which will return the last unread raised event of the "virtual apparatus". Note that after the event has been retrieved by the broswer, it should be removed from the queue Browser Environment At the header of the html page hosting "virtual apparatus", VAmessenge() and VAinfo must be defined. The function VAmessenge() will take four parameters: VAname, SeqNum, Msg, ChannelNum. Vaname is the name assigned to a "virtual apparatus" by the author. SeqNum is an unsign integer incrementing from 0 for each message sent. This is used for enabling synchronous communication. If synchronous communication is unnecessary, the script inside VAmessenge() should ignore this. Msg is a string containing the message the event wish to communicate. ChannelNum is the Channel number for communication.
Optional behaviour.	The current "virtual apparatus" may optionally support this. Log_Structure. "Virtual Apparatus" can optionally expose a database table structure which will define the log information which it would like to be saved by a data logging "Virtual Apparatus" into a database. If Log_structure is not exposed, data logging "virtual apparatus" would not be able to save the log information into a database. However, unstructured log information may still be save by appropriate data logging "virtual apparatus".
Guideline for messages.	The messages sent by "virtual apparatus" should not contain any comman (,). If more than one piece of information must be sent (e.g. see our cloze.class Applet in which the answer is sent with information of "correctness" and "sub-item ID"), the more important information should go first followed by the less important information and separated by semi-collon (;). Other optional delimiter may be used, but should be explicitly documented. VaMessenger() may need modification to support this.