- This line was added.
- This line was removed.
- Formatting was changed.
XnatDataClient, or XDC, is an application that helps perform data transactions with an XNAT server. In its simplest functions, it basically acts like curl or other command-line HTTP client. But XDC provides XNAT-specific operations on top of this basic query/response functionality, including the ability to resolve and retrieve multiple files and URIs from a single XNAT REST API call.
XDC is provided as a Java archive or jar file. The jar file is packaged as a Java application, with the required classpath included in the archive manifest. The practical result of this is that you can run the application just by specifying the XDC jar file (named data-client-version.jar; as of this writing, version is 1.6.2-SNAPSHOT) with the JVM call:
java -jar lib/data-client-1.6.5.jar -h
The pipeline engine also provides a script wrapper named XnatDataClient for this function. This script is located in the xnat-tools folder of the configured pipeline engine installation.
XDC has the following command options (you can also see these options by running XDC with the -h option).
|trustStore||Indicates the location of the trust store.|
|ls||listUris||Directs the client to render results as a list of files to the application output. This can be used for such applications as piping output from a call to the server to other commands or processing servers.|
|C||showStatusLine||Tells XDC to show the resulting HTTP status line on exit.|
|bs||bufferSize||Sets the buffer size option. Defaults to 256.|
|H||header||Indicates the HTTP method to be used for the operation. This can be one of GET, PUT, POST, or DELETE.|
|auu||allowUnsmoothUrls||Indicates that XDC should allow "unsmooth" URLs. "Unsmooth" URLs may have contiguous path separators (i.e. forward slashes) and other artifacts from string arithmetic and operations. By default, XDC smooths URLs before calling them (i.e. allow unsmooth URLs is false).|
|osa||outputStreamAdapter||Specifies an output stream adapter implementation to handle redirecting the output from your application.|
|db||data-binary||Indicates data to be POSTed with no extra processing. If the data starts with an @, the rest of the data should be a file name from which to read data; carriage returns and newlines are preserved.|
|d||data||Indicates data to be POSTed. If the data starts with an @, the rest of the data should be a file name from which to read data; carriage returns and newlines will be stripped out. This is identical to -da (--data-ascii).|
|da||data-ascii||See -d, --data.|
|b||batch||Indicates that this is a batch operation. Batch operations are currently only supported for download transfers, i.e. GET calls, that retrieve JSON that contains URI or absolutePath references.|
|c||showStatusCode||Tells XDC to show the resulting HTTP status code on exit.|
|tsPass||trustStorePassword||Provides the password for accessing the trust store.|
|a||useAbsolutePath||Indicates that XDC should try to use the absolute path of specified resources for copy operations rather than REST calls.|
|o||outputName||Indicates the requested output name.|
|l||local||Indicates the local file to be uploaded.|
|m||method||Indicates the HTTP method to be used for the operation. This can be one of GET, PUT, POST, or DELETE.|
|k||useSymlinks||Indicates that files should be linked via symlinks rather that copied during batch operations. Note that this function is dependent on your platform supporting symlinks and the ln command being on your path.|
|h||help||Displays this help text.|
|xx||overwrite||Indicates whether the specified output file should be overwritten without prompting if it exists.|
|v||version||Displays the version of this application.|
|u||username||The user name for authentication.|
|s||sessionId||Indicates the session ID to be used for transactions. This replaces username/password authentication options.|
|r||remote||Indicates the remote resource location. This should be a properly formatted URL, although it can indicate file as well as http resources.|
|p||password||The password for authentication.|
|pp||pathPrefix||Indicates a substitution for the path prefix. This lets you replace the first part of the returned absolute path with another path. The path tokens should be separated by the pound sign ('#'). For example, if you know that the absolute path returned by the server will be /data/project/archive/..., but your system has the same data archive mounted at /mnt/data/archive, you would specify the value for this option as /data/project#/mnt/data. Specifying this option implies the absolutePath option set to true.|
|x||proxy||Indicates the server address for the proxy (if required).|
Here are some handy use cases for XDC.
The ability to do a batch copy by symlink using the -k or --useSymlinks parameters. This is obviously very dependent on platform and hasn’t been tested extensively. It actually uses the Runtime.exec() method to run ln on the OS (Java 7 has a Files.createSymbolicLink() function, but we’re still compatible XDC is currently back to Java 6 so I XDC can’t use that), so I’m not sure what performance will be on this. It should definitely be better than copying a whole bunch of files though.
Listing output with the -ls or --listUris parameters. Instead of doing anything with the files found in a REST result, XDC just lists them. If you specify the absolutePath option, this will be listed by path, otherwise by server-relative URI. This is handy for piping the query results to other processing tools.