- 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.
Note that the 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).Short
a useAbsolutePath Indicates that XDC should try to use the absolute path of specified resources for copy operations rather than REST calls.
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.
bs bufferSize Sets the buffer size option. Defaults to 256.
h help Displays this help text.
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 system ln command being on your path.
l local Indicates the local file to write to or read from.
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.
m method Indicates the HTTP method to be used for the operation. This can be one of GET, PUT, POST, or DELETE.
osa outputStreamAdapter Specifies an output stream adapter implementation to handle redirecting the output from your application.
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.
r remote Indicates the remote resource location. This should be a properly formatted URL, although it can indicate file as well as http resources.
s sessionId Indicates the session ID to be used for transactions. This replaces username/password authentication options.
ts trustStore Indicates the location of the trust store.
tsPass trustStorePassword Provides the password for accessing the trust store.
u username The user name for authentication.
v version Displays the version of this application.
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 back to Java 6 so I 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.