The BlueJ Submitter Extension

Overview

BlueJ includes a mechanism for writing and deploying extensions to its core functionality, for which general documentation can be found here. At the moment, there is only one extension which is distributed with BlueJ: support for online submission of BlueJ projects for assessment or assistance -- the "submitter".

The submitter extension shipped with BlueJ is pre-installed as a "System level" extension. If you do not wish to use it, remove the file submitter.jar from the lib/extensions folder of the BlueJ installation.

The Submitter Extension

The submitter extension allows course tutors to set up mechanisms by which their students can submit work to them. The system is designed to encompass a broad range of uses, ranging from an installation that has only one or two courses running on it, to one that has a structured hierarchy involving a number of different people, departments and computers.The extension does not provide mechanisms for dealing with work once it has been submitted.

The submitter allows submission of BlueJ projects, or specific files from them, using a number of "transport" mechanisms: file copy, file transfer (ftp), email, or by sending them to a script on a web server. Files may be included or excluded from the submission, and may be packed into a JAR file before shipping.

The actions of the submitter are guided by one or more submission.defs files, placed in:

The contents of these files are combined (in the order given above) to form a list of "schemes", the submission actions available at any given time.

A simple submission.defs file, containing a few example submission schemes, is available here. Copy it into an existing BlueJ project, and you should immediately be able to use the Submitter extension to deliver the project's Java files.

Features

Submitter supports the following mechanisms to send files:

How to use Submitter Setup

Before using any of the features of the Submitter, users must fill in appropriate fields in the Preferences panel. These settings are remembered by BlueJ.


Submit a project

To submit an open project, the user clicks on the 'Submit' menu item (on BlueJ's Tools menu), and a dialog is opened (see screenshot below) showing the name of a submission scheme, a 'Submit' button and a 'Cancel' button. Pressing the 'Submit' button will immediately proceed with the submission, displaying the progress along the way and finally a results window. Should further information be required (such as an FTP password), a dialog box is shown requesting that information before the submission proceeds. A valid scheme has to be selected from the list before Submit can be pressed

The last-used scheme is remembered as a default for the current project.

Note: The presentation of the schemes has been updated in Submitter 2.0.0 from a tree view representation to a list. For compatibility with previous versions, Submitter still reads each hierarchical level from submission.defs and preserves configuration inheritance, but now presents each level as an individual entry (cf. Writing Submission schemes).

Writing Submission Schemes

A submission.defs file defines the names of available submission schemes, the "transport" mechanism which a scheme uses to submit a BlueJ project, and which files from the project should be included in the submission. Schemes may be nested, in which case the transport and files-to-be-submitted characteristics of a scheme are "inherited" by all its sub-schemes. For example, if all assessments for a particular course should be sent to the same email address, that address can be defined in the course branch rather than in every leaf.

So that different departments and/or people can have control of their own schemes, other schemes can be inserted into the tree at appropriate points by reading their definitions from a specified URL.

The files to be sent with a particular submission are defined by those that are included, less those which are excluded. Files that are essential must be present when submission is attempted, and are automatically also included. If no file options are present, all the files in the BlueJ project are included.

The transport used to send the files from the user to the desired recipient is defined by a URL. The URL protocols supported are: ftp:, http:, https:, mailto: and file:. Also,a pseudo protocol message: which does not send files at all, but instead just issues a message to the user, for example to state that this particular scheme will not be available until next week, or that a deadline has already passed.

Parts of the tree can be disabled. By placing a # character in front of a scheme or branch title, that scheme or branch and any branches or schemes below it, will be disabled and will not appear . This is useful if you want to set up the whole term's assignment schedule, but only switch each one on when it's time to use it.

All configuration definitions are reloaded whenever the user invokes the Submit menu item.

Grammar details expected in submission.defs can be found here

Some examples

A simple configuration might be

Send to Mrs Smith {
	.file.include = *.java;
	.transport = mailto:jks@hiskool.com;
}

This offers just one scheme to the user, Send to Mrs Smith. It sends all .java files in the project as MIME attachments to an otherwise empty email, to the address jks@hiskool.com.

Supposing Mrs Smith had several classes, and wanted to receive submissions with different titles.

Send to Mrs Smith {
	.file.include = *.java;
	.transport = mailto:jks@hiskool.com?subject=<title>;
	Class 1A;
	Class 2A;
	Class 3B;
}

Here, the three classes are all leaves, but with no further configuration, so they inherit the configuration of their enclosing scheme. The subject of the email sent is the title of the scheme, eg, Class 1A or whichever the user selected.

If Mrs Smith wanted her students to be able to type a short message to go with the email, the transport URL might be:

mailto:jks@hiskool.com?subject=<title>&body=<area:Message>;

The user will be issued a dialog box called Message in which to type a multi-line message. This will then become the body of the email.

In a more complicated scenario, there may be a more structured tree.

Computer Science {
	.file.include = *.java;
	CS101 Introduction to Programming {
		.transport = mailto:cs101tutor@bigskool.com?subject=<title>;
		Assignment 1 { .file.essential = Stars.java; }
		Assignment 2 { .file.essential = Picture.java; }
		Assignment 3 { .file.essential = Person.java, Student.java; }
	}
	CS102 Advanced Programming {
		.transport=mailto:cs102tutor@bigskool.com?subject=<title>;
		Noughts and Crosses;
		Chessboard;
		Foxes and Rabbits;
	}
	Java Help! {
		.transport=mailto:javahelp@bigskool.com?subject=Help&body=<area:Problem>;
	}
}	
Software Engineering {
	.insert = http://cs.bigskool.com/softeng/submission.defs;
}

For the Computer Science branch, all schemes just send all the .java files. For the three assignments of CS101, specific .java files must be present for the submission to go ahead. This aids automatic testing, but also helps to ensure that the student has submitted through the appropriate scheme.

The Software Engineering department have been given control of their own configuration file. The corresponding scheme and potential sub-level schemes appear in the list displayed when "submit..." is selected from the Tools menu of BlueJ.

Grammar 
Statements:
	Statement
	Statements Statement

Statement:
	BLOCK_START Statements BLOCK_END
	EMPTY_SCHEME
	CONFIG
	Comment
	WHITESPACE
	EMPTY

BLOCK_START:
	SchemeTitle {

BLOCK_END:
	}
		
EMPTY_SCHEME:
	SchemeTitle ;

CONFIG:
	ConfigurationToken = ConfigurationValue ;

Comment:
	// { Any characters but \n } \n
	/* { Any characters but */ } */

SchemeTitle:
	#opt { Any characters but {}=;/ }

ConfigurationToken:
	. { Any characters of .a-z }

ConfigurationValue:
	{ Any characters but {}; }

Newlines, together with the spaces that surround them, are treated as a single space character, and appear as such in Strings.
Quoted strings in "" allow the otherwise unacceptable characters.

Configuration Tokens

The actual configuration data, as described by a ConfigurationTokencan be:

Token Use Note
.transport The transport URL that will be used to send the submitted files 1
.file.include Files to include. 2,3
.file.exclude Files to exclude. 2,3
.file.essential Files that must be present for the submission to go ahead 2
.file.jar Package the required files into a single JAR archive with the name given here, and send that. The name given should include the extension .jar or .zip as approppriate.
.insert A URL of another configuration file to be inserted at this point.

Notes:

  1. Only one .transport item may be defined in a leaf.
  2. These can be supplied as a comma-separated list, or as multiple definitions. All definitions will be accumulated, and throughout the upper branches of the tree.
  3. Wildcards can be used here: Star * stands for zero or more of any characters; Question mark ? stands for one of any character.

Configuration Values: the transport URL

The scheme's transport protocol is defined by the parameter .transport = URL

Several protocols are available (currently ftp:, http:, https:, mailto: and file:). These are described by standard URL notation, ie,
ftp://username:password@host/path
http://host/path?parameter1=value1&parameter2=value2etc
https://host/path?parameter1=value1&parameter2=value2etc
mailto:user@host?subject=subject&body=message
file:path

In the case of http: or https: the response from the server is shown to the user, and if the server requires http authentication then the user is prompted for username and password.
A pseudo protocol, message: shows a message to the user instead of sending files. This takes the form:
message:message. Simple HTML tage may be used to control the layout of the message.

In the case of the ftp: and file: URLs, the files submitted from the project will be created in a folder with the same name as the project, at the target location (with sub-directories created as necessary), but note that all of the directories in the transport URL must already exist.

In the case of the mailto: URL, the files from the project will be attached (with content type text/plain) to the generated email message. The structure of the project folder (sub-folders etc) cannot be transmitted using this transport mechanism, due to restrictions imposed by MIME (see RFC 2183 section 2.3).

In the case of the http: URL, the files will be sent to the given URL using HTTP POST. Any HTML returned by the target URL will be displayed to the user in a dialog box. Clickable links in the returned HTML will be active in this window, and if the user clicks them will cause an external browser to be displayed.

In the case of the https: URL, the functionality is the same as the http: URL, except that an SSL connection is used.

Further enhancements to the URL format allow special information to be included, or the user to be presented with a dialog box requesting information. These are inserted into the URL where the information should go. The available parameters are listed here:

Extra parameters for the URL
Parameter Use
<username> The username of the user, as set on the Preferences Panel.
<address> The user's email address, as set on the Preferences Panel.
<title> The full title of this scheme.
<simpletitle> The title of this scheme, just the final part.
<date> The full date and time of the submission.
<isodate> The full date and time of the submission, encoded in an easily sortable form as per ISO 8601. Equivalent to the Java simple date format "yyyy-MM-dd'T'HH:mm:ssZ"
<field:user_display>* Ask the user to enter this data in a single line field. user display is presented as the prompt.
<password:user_display>* Ask the user to enter this data in a single line secret field. user display is presented as the prompt.
<area:user_display>* Ask the user to enter this data in a text area. user display is presented as the prompt.
<show:user_display=parameter> Show the user what the parameter is, but do not allow editing.
<00> Re-use the first value of the first parameter used/given in this transport URL, 01 is the second parameter, etc.

(*)These three parameters can also be appended with =parameter which will then use that parameter as the default value. It is not recommended for password.
Note that substitution is not performed for message: protocol.

Although user entries are escaped, the URL read from configuration files is not, so you should do this manually. This means changing all spaces into +, and replacing other dodgy characters by their ASCII code in the form %NN where NN is the hexidecimal code for that character. This is not necessary for anything inside <angle brackets>, nor for message:. You should only use alphanumeric characters and $-_.+!*'(), plus %+ to escape and /?:@&= where they are supposed to be. Don't forget to terminate your URL with ;!

Configuration Values: files to send

.file.include = Files that should be included in the submission.
.file.exclude = Files that should then be excluded from the list.
.file.essential = Files that must be present in order to allow the submission to proceed.

Any or all of these three parameters can be present. If a file is referenced by both the include and the exclude, it will be excluded. If a file is referenced only by essential, it will automatically be included. If it appears as essential and excluded, an error will be generated, saying that the file is missing.
include and exclude can contain wildcards. Star * stands for zero or more of any characters. Question mark ? stands for one of any character.
All three parameters can contain a comma separated list of names.

As an alternative to sending files one-by-one, they can be packaged into a .jar file, by specifying:
.file.jar = Filename of the .jar file.
Parameters which do not prompt for user input (ie, <username>, <address>, <title>, <simpletitle> and <date>) may be used in the filename.

Inserts

In order to distribute submission data, reference can be made to a file accessible by URL that contains additional parameters. This allows individual tutors to control their own submission mechanisms, and can ensure that students are using the most up-to-date versions. The file referenced by the URL is inserted literally at that point, so follow the syntax as if the text was all in the one file.

Disabling parts of the tree

If you want to temporarily 'switch off' a part of the tree - perhaps because a deadline has passed, or you are not yet ready to receive a set of submissions - place a # in front of the title of the branch or scheme. Everything in the hierarchy below that branch is then also disabled. This saves having to carefully comment out sections of the tree that you want to deactivate - you only need to make a change to the title itself.

Some tips and tricks