This library provides the methods used to download the examples of the optimizationBenchmarking tool suite. Details about the licensing of this project and the projects it depends on are given in LICENSE.md.
By default, our example listing and downloading tools use the repository http://optimizationBenchmarking.github.io/documentation-examples/.
However, all job builders have the method
setBaseUri, allowing you to use any other repository that can be identified by and accessed via a URI or URL. These repositories must have the following structure
|-- exampleList.txt |-- data | |-- firstExample | | |-- fileList.txt | | |-- ... | |-- secondExample | | |-- fileList.txt | | |-- ... | |--- ...
exampleList.txt provides a list of the examples in the repository. It is a text file where always three lines identify one example. This file has the format
[minEvaluatorVersion,maxEvaluatorVersion] exampleFolderName human readable example title HTML description
maxEvaluatorVersion identify the minimum and maximum version of the optimization benchmarking evaluator for which the example can be used. They have the format
major.minor.patch, i.e., follow the Semantic Versioning guides. The reason why we specify versions is that the available evaluator modules may change over time and even the structure of the configuration or data files itself might change. Both
maxEvaluatorVersion are optional, i.e., you could write something like
[0.8.5,] to indicate only the minimal required version (here, 0.8.5) or
[,1.0.2] for making the example available only up to evaluator version 1.0.2. Finally, you can even write
[,] to indicate that the example is available for all versions.
exampleFolderName is the folder name of the example, relative to
data. In the repository structure displayed above, this could be
secondExample. This name (as well as any other file or folder name used) should not cause any problems within an URL or URI.
human readable example title is the title of the example. It can be any plain text and might be copied into a HTML document into
HTML description is a single line of description in HTML format. It may contain multiple
<p> tags. If it does not start with
<p>, the example loader will wrap it into
There can be an arbitrary number of such line-triples in the
exampleList.txt file, each identifying another example.
Each example folder contains a file
fileList.txt which identifies the resources belong to an example. Each line of this file has the following shape:
maxEvaluatorVersion have the same meaning as in
exampleList.txt : A resource will only loaded by the example loader if the evaluator version matches the resource version range.
resourcePathRelativeToExampleFolder is the path of the resource relative to the example folder, e.g.,
data/firstExample in the structure displayed above. Each such path must identify a file. Files may additionally be structured in folders, however the example downloader will only preserve the file name itself. In other words, if you download
data/firstExample/1.0.6/config.xml into folder
/home/user/x/, the downloader will produce
/home/user/x/config.xml. Special case: If the resource name ends with
data/firstExample/1.0.6/results.zip, the archive will be directly extracted into the destination folder instead, into
/home/user/x/ in our example.