Programmer's Guide to jTRACE

$Date: 2005-07-13 19:05:38 -0400 (Wed, 13 Jul 2005) $
by Harlan Harris and Ted Strauss

Introduction

This document provides an introduction to the jTRACE implementation, for development, maintenance, and extension.

The Introduction gives a high-level summary of the design.
the Build Instructions describe how to build jTRACE from source,
the GUI Design section describes how the GUI is put together,
and the Files and Scripts section overviews how the XML schemas are used to define file formats and scripts. The jTRACE javadoc are generated from the code; javadoc gives full class specs, including variable and method declarations.



jTRACE is a Java 1.4.2 application with a GUI front-end and a XML-based file structure.

Build Instructions

Install Netbeans and Java

jTRACE was developed in Netbeans 4.0, using version 1.4.2 of Java. It should be possible to build the application with any 4.X version of Netbeans and with Java 2 SDK 5.X. Sun has a combined package available for download:. Follow the usual installation instructions. Note that the Netbeans source assumes that you're using J2SE 1.4.2, and you'll have to make a small change before you can use this more recent version of Java to build. See below.

Install Subversion (optional)

To access our source tree, you'll need to install Subversion. We're using a 1.0 build of the subversion server, but you can probably use the most recent client. On Mac OS X, try this version.

You'll also need to install the Subversion plugin for Netbeans, here.

Ask the authors how/where the SVN server with the jTRACE source is.

Alternatively, you can just download a copy of the source from the jTRACE web page, and ignore SVN entirely.

Confirm Java version

OK, you've now got a big source tree, and you're ready to use it with Netbeans. First step is to change the Java package information in jTRACE. Right-click on jTRACE in the projects or file window, then select Properties, then General, then change the Java Platform to Default Platform. (Or, if you've got J2SE 1.4.2 installed, you can create a new platform called J2SE142 and use everything as-is.)

Set up libraries

jTRACE... Properties... Compiling sources... From there, you'll need to create several new libraries by selecting .jar files from the libs directory. As follows:

JAXB
lib/jaxb-impl.jar
lib/jaxb-api.jar
lib/jaxb-libs.jar
lib/jaxb-xjc.jar
lib/jaxp-api.jar
lib/endorsed/dom.jar
lib/endorsed/sax.jar
lib/endorsed/xalan.jar
lib/endorsed/xercesImpl.jar
lib/jax-qname.jar
lib/namespace.jar
lib/relaxngDatatype.jar
lib/xsdlib.jar
JaxFront
lib/castor-0.9.5.3-xml.jar
lib/commons-beanutils.jar
lib/commons-collections.jar
lib/commons-httpclient-2.0.1.jar
lib/commons-logging.jar
lib/jaxfront-core.jar
lib/jaxfront-dbm.jar
lib/jaxfront-swing.jar
lib/jaxfront-xuieditor.jar
lib/jgoodiesLF.jar
lib/jimi.jar
lib/log4j.jar
JFreeChart
lib/gnujaxp.jar
lib/jcommon-1.0.0-pre2.jar
lib/jfreechart-1.0.0-pre2.jar
lib/junit.jar
lib/servlet.jar
Builds

At this point the project should build correctly! To run from within Netbeans, just hit Run. You can also make "official" builds and source packages by using the package/makepackage and makesrczip scripts.

Object Design

The following objects are in the Model directory:

TracePhones

The TracePhones class defines a number of static methods used to validate phonetic strings and TraceWords, to calculate phoneme representations in the input layer of the model, and to define phoneme continua.

@@@ methodName
A brief text description
TraceWord

A TraceWord is a tuple of phonetic form, frequency, and familiarity (which is not currently used).

TraceLexicon

A TraceLexicon is a simple class that maintains a set of TraceWords. It's currently implemented as just an array.

TraceParam

The parameters of a TRACE simulation are specified in a TraceParam object. These parameters include a TraceLexicon, an input string, and the numerous numeric parameters of the model.

TraceNet

A TraceNet is the core of the model itself.

TraceSim

A TraceSim is a wrapper around a TraceNet object. It stores the internal states of a TraceNet at each time step, for real-time display and for later analysis.

TraceSimAnalysis

A TraceSimAnalysis does LCR calculations based on a TraceSim object.

TraceGraph

A TraceGraph is a wrapper around (subclass of?) TraceSimAnalysis that also includes graph visualization preferences.

TraceScript

A TraceScript is an object that can iterate over parameters, create and run TraceSim objects, create derivative TraceGraph objects, export data to files, etc. It is described in more detail in the Files and Scripts section below.

The following objects are in the UI directory:

jTRACEMDI

jTRACE

ParametersPanel

SimPanel

GraphPanel

ScriptFrame

ScriptPanel

DataPlot

InputDataPlot

FeatureDataPlot

PhonemeDataPlot

PhonemeBoxDataPlot

WordDataPlot

WordBoxDataPlot

The following objects are in the IO directory:

@@@

GUI Design

jTRACE uses a multiple-document-interface (MDI) approach. Documents are views of linked TraceSim, TraceParam, and TraceGraph objects. The TraceSim and TraceParam objects may be saved or loaded (see below) as .jt files. Each subwindow contains one tab for each of these objects.

The scripting window (there can only be one) is separate from jTRACE document windows. It is a view of a TraceScript object. There are tabs for the associated TraceParam object, for the main TraceScript object, and for a TraceGraph object that plots the compiled results. Additionally, the TraceScript object can request that the scripting window create new jTRACE documents (as above) from individual runs of the script.

Files and Scripts