Package org.fairdatapipeline.api

Class Coderun

java.lang.Object

org.fairdatapipeline.api.Coderun

All Implemented Interfaces:

java.lang.AutoCloseable

public class Coderun
extends java.lang.Object
implements java.lang.AutoCloseable

Java implementation of the FAIR Data Pipeline API

Users should initialise this library using a try-with-resources block or ensure that .close() is explicitly closed when the required file handles have been accessed.

Usage example

    try (var coderun = new Coderun(configPath, scriptPath, regToken)) {
       ImmutableSamples samples = ImmutableSamples.builder().addSamples(1, 2, 3).rng(rng).build();
       String dataProduct = "animal/dodo";
       String component1 = "example-samples-dodo1";
       Data_product_write dp = coderun.get_dp_for_write(dataProduct, "toml");
       Object_component_write oc1 = dp.getComponent(component1);
       oc1.raise_issue("something is terribly wrong with this component", 10);
       oc1.writeSamples(samples);
     }
     

Or, to write a CSV file, with issues on the DP and on the Code_repo:

    try (var coderun = new Coderun(configPath, scriptPath, regToken)) {
       String dataProduct = "human/health";
       Data_product_write dp = coderun.get_dp_for_write(dataProduct, "toml");
       Object_component_write oc1 = dp.getComponent();
       CleanableFileChannel f = oc1.writeFileChannel();
       my_analysis_csv_writer(f);
       Issue i = coderun.raise_issue("something is terribly wrong with this component", 10);
       i.add_components(oc1);
       i.add_fileObjects(coderun.getCode_repo());
     }
     

Constructor Summary

Constructors

Constructor	Description
Coderun(java.nio.file.Path configFilePath)	Constructor using only configFilePath - scriptPath is read from the config.
Coderun(java.nio.file.Path configFilePath, @Nullable java.nio.file.Path scriptPath)	Constructor using both configFilePath and ScriptPath
Coderun(java.nio.file.Path configFilePath, @Nullable java.nio.file.Path scriptPath, @Nullable java.lang.String registryToken)	Constructor specifying configPath, scriptPath, and registryToken.

Method Summary

Modifier and Type	Method	Description
void	close()	Finalize and register the coderun.
Data_product_read	get_dp_for_read(java.lang.String dataProduct_name)	Obtain a data product for reading.
Data_product_write	get_dp_for_write(java.lang.String dataProduct_name)	Obtain a data product for writing.
Data_product_write	get_dp_for_write(java.lang.String dataProduct_name, java.lang.String extension)	Obtain a data product for writing.
FileObject	getCode_repo()	Access the code repository in order to raise a code repository issue.
FileObject	getConfig()	Access the configuration file (config.yaml); in order to raise a Config issue.
FileObject	getScript()	Access the Submission_script; in order to raise a Submission_script issue.
Issue	raise_issue(java.lang.String description, java.lang.Integer severity)	create an Issue that can be linked to a number of object components and/or fileObjects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Coderun

public Coderun(java.nio.file.Path configFilePath)

Constructor using only configFilePath - scriptPath is read from the config.

Parameters:

configFilePath - the Path to the config file, which must be located in the local data store CodeRun folder with timestamp name.

Coderun

public Coderun(java.nio.file.Path configFilePath,
               @Nullable java.nio.file.Path scriptPath)

Constructor using both configFilePath and ScriptPath

Parameters:

configFilePath - the Path to the config.yaml file

scriptPath - the Path to the script file - this may be null if the script path is given in the config file.

both startup files are usually provided by fair run in the local data registry jobs/{timestamp} folder.

Coderun

public Coderun(java.nio.file.Path configFilePath,
               @Nullable java.nio.file.Path scriptPath,
               @Nullable java.lang.String registryToken)

Constructor specifying configPath, scriptPath, and registryToken.

Parameters:

configFilePath - the Path to the config.yaml file

scriptPath - the Path to the script file - this may be null if the script path is given in the config file.

both startup files are usually provided by fair run in the local data registry jobs/{timestamp} folder.

registryToken - the authentication token of the local registry (or null if the token is to be read from the config or from ~/.fair/registry/token)

Method Detail

getScript

public FileObject getScript()

Access the Submission_script; in order to raise a Submission_script issue.

Returns:

the FileObject representing the Submission_script.

Usage:

     coderun.getScript.raise_issue("this is a very bad script", 10);
 

OR

     Issue i = coderun.raise_issue("Seriously bad stuff", 10);
     i.add_fileObjects(coderun.getScript(), coderun.getConfig());
 

getConfig

public FileObject getConfig()

Access the configuration file (config.yaml); in order to raise a Config issue.

Returns:

the FileObject representing the config file.

Usage:

     coderun.getConfig.raise_issue("this is a very bad config file", 10);
 

OR

     Issue i = coderun.raise_issue("Seriously bad stuff", 10);
     i.add_fileObjects(coderun.getScript(), coderun.getConfig());
 

getCode_repo

public FileObject getCode_repo()

Access the code repository in order to raise a code repository issue.

Returns:

the FileObject representing the code repository (which is given in the config file)

Usage:

     coderun.getCode_repo.raise_issue("this contains very bad code", 10);
 

OR

     Issue i = coderun.raise_issue("Seriously bad stuff", 10);
     i.add_fileObjects(coderun.getCode_repo(), coderun.getConfig());
 

get_dp_for_read

public Data_product_read get_dp_for_read(java.lang.String dataProduct_name)

Obtain a data product for reading.

Parameters:

dataProduct_name - the name of the dataProduct to obtain.

Returns:

the data product.

get_dp_for_write

public Data_product_write get_dp_for_write(java.lang.String dataProduct_name,
                                           java.lang.String extension)

Obtain a data product for writing.

Parameters:

dataProduct_name - the name of the dataProduct to obtain.

extension - the file extension representing the file type we will write, e.g. csv or toml

Returns:

the data product

get_dp_for_write

public Data_product_write get_dp_for_write(java.lang.String dataProduct_name)

Obtain a data product for writing. (gets the extension from config)

Parameters:

dataProduct_name - the name of the dataProduct to obtain.

Returns:

the data product

raise_issue

public Issue raise_issue(java.lang.String description,
                         java.lang.Integer severity)

create an Issue that can be linked to a number of object components and/or fileObjects.

Parameters:

description - text description of the issue

severity - integer representing the severity of the issue, larger integer means more severe

Returns:

the Issue

close

public void close()

Finalize and register the coderun. (this gets called automatically when using Coderun in a try-with-resources block)

Specified by:

close in interface java.lang.AutoCloseable