Page tree

Versions Compared


  • 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.

Running XDC

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:

Code Block
titleRunning XDC
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).



trustStoreIndicates the location of the trust store.
lslistUrisDirects 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.
CshowStatusLineTells XDC to show the resulting HTTP status line on exit.
bsbufferSizeSets the buffer size option. Defaults to 256.
HheaderIndicates the HTTP method to be used for the operation. This can be one of GET, PUT, POST, or DELETE.
auuallowUnsmoothUrlsIndicates 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).
osaoutputStreamAdapterSpecifies an output stream adapter implementation to handle redirecting the output from your application.
dbdata-binaryIndicates 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.
ddataIndicates 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).
dadata-asciiSee -d, --data.
bbatchIndicates 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.
cshowStatusCodeTells XDC to show the resulting HTTP status code on exit.
tsPasstrustStorePasswordProvides the password for accessing the trust store.
auseAbsolutePathIndicates that XDC should try to use the absolute path of specified resources for copy operations rather than REST calls.
ooutputNameIndicates the requested output name.
llocalIndicates the local file to be uploaded.
mmethodIndicates the HTTP method to be used for the operation. This can be one of GET, PUT, POST, or DELETE.
kuseSymlinksIndicates 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.
hhelpDisplays this help text.
xxoverwriteIndicates whether the specified output file should be overwritten without prompting if it exists.
vversionDisplays the version of this application.
uusernameThe user name for authentication.
ssessionIdIndicates the session ID to be used for transactions. This replaces username/password authentication options.
rremoteIndicates the remote resource location. This should be a properly formatted URL, although it can indicate file as well as http resources.
ppasswordThe password for authentication.
pppathPrefixIndicates 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.
xproxyIndicates the server address for the proxy (if required).


Here are some handy use cases for XDC.

Batch Copy

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.