BLUEJ EXTENSIONS

Overview

BlueJ now 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 lib folder of the BlueJ installation (<BLUEJ_HOME>/lib). Definitions found here will be used for all projects opened by BlueJ.
• the user's BlueJ configuration directory (<USER_HOME>/.bluej on Solaris/Linux, <USER_HOME>\bluej on Windows, or ~/Library/Preferences/org.bluej on Mac OS X). Definitions found here will be used for all BlueJ projects opened by that user.
• The BlueJ project folder. Definitions found here will be used only for that project, and will only be available while that project is open.

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.

Overview of features added January 2007

If you are already familiar with the submitter, then you may want to know that the new features in the January 2007 release are:

• HTTPS protocol.
• HTTP authentication if required by the server.
• mailto protocol enhancements (implemented with JavaMail 1.4): authentication and secure SSL/TLS connections.

There are no changes to the submission.defs file, other than being able to specify HTTPS as a protocol. New additions appear in the Preferences panel, shown below in the Setup section. For DIGEST-MD5 authentication, a new property, saslrealm, has to be set in the bluej.properties file.

The new version of the submitter can be downloaded here. Install it by overwriting the existing file of the same name in your BlueJ installation.

The User's View

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.

• User name. The name by which the user should be known for purposes of the submission.
• Email. The email address by which the user should be known for purposes of the submission.
• Server name. The name of an SMTP server which can be used to submit BlueJ projects by email. For users working in Labs, this will be the SMTP server provided by the institution. For users working remotely, it may still be possible to use the institution's SMTP server, depending on the security measures it has in place. Otherwise it will need to be the SMTP server provided by the user's ISP.
• Port. Port number in the SMTP server to connect to. If none is specified, 25 is used.
• Use name and password. Whether to use one of the authentication mechanisms available in the SMTP server. JavaMail 1.4 supports LOGIN, PLAIN, and DIGEST-MD5, and it considers them in that order when choosing the one to use. There is no client control over which mechanism is used. For DIGEST-MD5 authentication, the saslrealm property has to be set in the bluej.properties file.
• Name. Initial username in the authentication dialog.
• Use secure connection. When connecting to the port specified, choose either an SSL, TLS, or no secure connection.

Use

To submit an open project, the user clicks on the 'Submit' menu item (on BlueJ's Tools menu), and a dialog is opened (see right) showing the name of a submission scheme, with a 'Browse' button alongside; 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 entered before Submit can be pressed, either by directly typing in the name of the scheme, or by Browsing the available schemes.

If the user presses 'Browse', another dialog is presented (see left) with a tree view of available schemes. The user should select an appropriate leaf (expanding branches where necessary to navigate to it) and press the 'OK' button. If the 'Cancel' button is pressed instead, the dialog will close and any selection is ignored.

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

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 charactersitics 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. These will only be followed up should the user expand the branch containing such an insert.

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 on the user's tree. 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.

Some examples

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;
}

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>;

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;
}

The Software Engineering department have been given control of their own configuration file, which must be accessible if a user attempts to expand their branch of the scheme tree.

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 {}; }

Configuration Tokens

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

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=value2 etc
https://host/path?parameter1=value1&parameter2=value2 etc
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

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 (i.e. <username>, <address>, <title>, <simpletitle> and <date>) may be used in the filename.

Inserts

Disabling parts of the tree

Some tips and tricks

.transport = mailto:jack@my.highschool.com?subject=<title>&body=Here%27s+one+I+made+earlier

.transport = mailto:jack@my.highschool.com?subject=Help%21&body=<area:Message>

If using a CGI script to process the sent files, add the necessary parameters in the usual way. For example, suppose it needed the user's name and a PIN to validate them, you could do

.transport = http://cs.texasuni.edu/cs2/uploader.php?identity=<field:Username=username>&pin=<password:PIN>&folder=<simpletitle>

This prompts the user for a Username, but provides by default whatever is in the settings, and a password scheme (in which characters typed are shown as stars) called PIN. An extra parameter is also sent, called folder, giving the name of the scheme so that the server will know where to put these files. An example PHP file for handling the transport given above is available here (but note that no guarantee is given of its security!)

If using a CGI script which validates the information passed to it (or even tests the submitted files!) its response will be shown to the user. This can provide comforting assurance that their files have been successfully submitted. Clickable links in the response will (if followed) be displayed to the user in an external browser window.

If any configuration item in the file (or a file referenced by a .insert) is not valid, an error message will be displayed.

To lookup ASCII codes, see www.asciitable.com.

Depending on how your FTP server is set up, you may be able to use a double slash at the beginning of a path to go to the root, if that is not where you normally start from.

Supposing your student has an account on the cs server, and your network is newyorkuni.edu, and supposing the ftp: server is setup so that you start an FTP session at your home path, but you can navigate to the root of the system, you could set up a receiving repository in /courses/cs101/username/. The transport would be:

.transport = ftp://<field:Username=username>:<password:Password>@cs.newyorkuni.edu//courses/cs101/<00>/

If you need to use a Proxy Server for HTTP access, you'll need to start BlueJ with the appropriate settings for the Java VM property settings for http.proxyHost and http.proxyPort.

There is a known issue with Java's socket classes, the submission extension's email system and Norton Anti Virus's "scan outgoing email" option. Until this is resolved between Sun and Symantec, Norton's "scan outgoing email" option will need to be disabled for email submission of BlueJ projects to succeed.

To see the JavaMail debug log, have a file named javamail-debuglog.txt in your bluej home directory, the same directory where the BlueJ debug log is. You can find the name of this directory in the About BlueJ window, accessible from the About Bluej submenu of the Help menu, or at the bottom of this page.

For DIGEST-MD5 authentication, set the saslrealm property in the bluej.properties file.

If you are getting an SSL-handshake exception, it may be because your server's public-key certificate is not one that your JVM trusts, as is the case with self-signed certificates. Use the keytool command to store the certificate in the keystore of trusted certificates as follows:

keytool -import -alias <a-unique-alias-you-make-up> -file <file-containing-certificate-to-import> -keystore <JAVA_HOME>/jre/lib/security/cacerts

The initial password of cacerts is changeit; use the keytool subcommand storepasswd to change it. For more information see the keytool documentation for Java 1.4.2, Java 1.5 or Java 6.