LabKey Server supports
transformation scripts for assay data at upload time. This feature is primarily targeted for Perl or R scripts; however, the framework is general enough that any application that can be externally invoked can be run as well, including a Java program.
Java appeals to programmers who desire a stronger-typed language than most script-based languages. Most important, using a Java-based validator allows a developer to leverage the remote client API and take advantage of the classes available for assays, queries, and security.
This page outlines the steps required to configure and create a Java-based transform script. The ProgrammaticQCTest script, available in the BVT test, provides an example of a script that uses the remote client API.
Configure the Script Engine
In order to use a Java-based validation script, you will need to configure an external script engine to bind a file with the .jar extension to an engine implementation.
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Views and Scripting.
- Select Add > New External Engine.
- Set up the script engine by filling in its required fields:
- File extension: jar
- Program path: (the absolute path to java.exe)
- Program command: -jar "${scriptFile}" "${runInfo}"
- scriptFile: The full path to the (processed and rewritten) transform script. This is usually in a temporary location the server manages.
- runInfo: The full path to the run properties file the server creates. For more about this file, see "How Transformation Scripts Work".
- srcDirectory: The original directory of the transform script (usually specified in the assay definition).
- Click Submit.
The program command configured above will invoke the java.exe application against a .jar file passing in the run properties file location as an argument to the java program. The run properties file contains information about the assay properties including the uploaded data and the location of the error file used to convey errors back to the server. Specific details about this file are contained in the data exchange specification for Programmatic QC.
Implement a Java Validator
The implementation of your java validator class must contain an entry point matching the following function signature:
public static void main(String[] args)
The location of the run properties file will be passed from the script engine configuration (described above) into your program as the first element of the args array.
The following code provides an example of a simple class that implements the entry point and handles any arguments passed in:
public class AssayValidator
{
private String _email;
private String _password;
private File _errorFile;
private Map<String, String> _runProperties;
private List<String> _errors = new ArrayList<String>();
private static final String HOST_NAME = "http://localhost:8080/labkey";
private static final String HOST = "localhost:8080";
public static void main(String[] args)
{
if (args.length != 1)
throw new IllegalArgumentException("Input data file not passed in");
File runProperties = new File(args[0]);
if (runProperties.exists())
{
AssayValidator qc = new AssayValidator();
qc.runQC(runProperties);
}
else
throw new IllegalArgumentException("Input data file does not exist");
}
Create a Jar File
Next, compile and jar your class files, including any dependencies your program may have. This will save you from having to add a classpath parameter in your engine command. Make sure that a ‘Main-Class’ attribute is added to your jar file manifest. This attribute points to the class that implements your program entry point.
Set Up Authentication for Remote APIs
Most of the remote APIs require login information in order to establish a connection to the server. Credentials could be provided as either a username/password combination or by using an
API key. They can be hard-coded into your validation script or passed in on the command line.
Using an API Key substitution parameter in your transformation script is a straightforward way to accomplish this. Learn more in this topic:
Alternatively, a .netrc file can be used to hold the credential necessary to login to the server. For further information, see:
Create a netrc file. The following example code can be used to extract username/password details from a .netrc file:
private void setCredentials(String host) throws IOException
{
NetrcFileParser parser = new NetrcFileParser();
NetrcFileParser.NetrcEntry entry = parser.getEntry(host);
if (null != entry)
{
_email = entry.getLogin();
_password = entry.getPassword();
}
}
Associate the Validator with an Assay
Finally, the QC validator must be attached to an assay. To do this, you will need to edit the assay design.
- Click Add Script, and either:
- Leave the Upload file option selected and drop your .jar file into the @scripts location, OR
- Choose the Enter file path option, and specify the absolute location of the .jar file you have created.
- Click Apply, then Save the assay design.
- The engine created earlier will bind the .jar extension to the java.exe command you have configured.
Related Topics