COMP 523 - Software Engineering Laboratory
Knowledge Discovery and Data Mining in Social Welfare

• Home
• Team Rules
• Concept
• Personas and User Stories
• Contract
• Demo1
• Project Plan
• Functional Spec
• Design document
• User manual
• Adminstrator manual
• Test plan
• Temporary Code repository
• Final presentation

Use Cases

Requirements

Interfaces

There are two primary interfaces to our application: a command line client, and a Swing-based GUI wrapper. This document also describes the API provided to the Velocity programmer.

Command line client

The command line client will be invoked by a script named matemplate (on Unix), or matemplate.cmd on Windows. The script takes an optional -b flag, followed by three arguments. If an incorrect number of arguments are given, it prints usage information as specified below:

Usage: 
  matemplate.cmd template-location config-file output-file
  or 
  matemplate.cmd -b template-location config-directory output-directory
  Template location: This may be either a file or a directory.  If it is a 
      directory, it is expected to contain the template file(s) referred to by
      the config(s) specified later.
  Config location: This may be a file or a directory, depending on whether the
    -b flag is set.  If it is a directory, processing occurs for each config 
	file in that directory.  (Config files are identified by the extension 
	'.mtc')
  Output location: This may be a file or a directory, depending on whether the
    -b flag is set.  Specifies the locaiton to which output is written.
    location to which
Semantics: 
    If the template and config locations are both directories, then each
  config file is processed (using the template specified in the "template" 
  attribute of it's root element), and an output file created in the output 
  location.  The output file's name is produced by removing '.mtc' from the end
  of the config file's name and appending the extension '.sas'.  It is an error
  if a config specifies a template that does not exist.
    If the config location is only a single file, the behavior is the same as if
  a directory containing only one file was specified, except 
    If the template location is a single file and the config location is a 
  directory, then only configs specifying that template are processed.
    If the template location and config locations are both single files, the
  behavior is the same as in the previous case, except that if the template
  filename does not agree with the template attribute in the config file, it is
  an error.

The command line client prints error and warning messages from the templates to stdout, prefixed with the strings "ERROR: " and "WARNING: ". If multiple configs are specified, an error causes the execution of the current file to fail, but does not terminate the job. The error message generated if a config specifies a template that does not exist is:

ERROR: config file config-filename references template template-filename, which does not exist.

GUI client

The GUI client is similar to the command line client, with a few exceptions:

• Erroneous input is detected immediately and indicated via the error message in the lower-left. The go button is not enabled until input is valid.
• When the template location refers to a folder instead of a file, an additional panel is added (shown below), giving the user to select which templates should be used.
• Error and warning messages are provided via JOptionPane dialog boxes. If a template runs with no errors or warnings, a dialog with a green check mark and brief message is displayed.

Velocity Context

Templates are written in the velocity template language. Central to this language is the idea of the "Velocity Context", which contains variable bindings. The following bindings are provided to templates:

• tmpl_name: the name of the template file, with the '.vm' extension dropped.
• tmpl_modified: the modified date of the template file, in this format: Tue Oct 20 01:16:07 EDT 2009
• config_name: the name of the config file, with the '.mtc' extension dropped.
• config_modified: the modified date of the config file, in the same format as tmpl_modified.
• Util: Object providing 3 methods:
  • error: signals a warning message to the user, and continues execution.
  • warning: signals an error message to the user, and aborts execution of this template
  • nvl: takes any number of arguments and returns the first one which is not null.
• config: a pointer to the root element of the config document. This is a wrapper with the following features:
  • The wrapper provides an iterator method returning each of it's child elements, allowing it to be used with Velocity's #foreach directive
  • The string representation of a wrapper is its text content.
  • The wrapper provides a get(String) method which returns the named attribute or child element, allowing the tree to be traversed using Velocity's property references. For example, given the following config file, ${config.topvars.DATANAME} returns 'foo'

    <?xml version="1.0" encoding="utf-8" ?>
    <root>
      <topvars DATANAME="foo">
    </root>

  • A method isTrue() which returns true if the text content of this node is true or yes (case-insensitively); and a corresponding method isFalse