Software Documentation
- About Transport Service
- Installation
- Operation
Download
Project Documentation
This document describes how to operate the Transport Service software contained in the transport-registry package. The Transport Service software is a web application for retrieving product files from a local repository either by querying a Registry Service or a Search Service for discovering a product or products. The following topics can be found in this section:
The Transport Service provides a REST-based interface accessible via HTTP for interacting with the service. Because the REST-based interface operates over HTTP, there are several options for interacting with the Transport Service:
Any standard web browser (e.g., Firefox, Safari, Chrome, Internet Explorer, etc.) will allow interaction with the service.
The cURL utility offers the most flexible means for interacting with the application. The utility comes installed on most UNIX-based platforms and is available for download for the Windows platform. The examples in the sections that follow utilize cURL to interact with the application. If cURL is not installed on the local machine but Wget is, see the Using Wget section for converting cURL commands to Wget commands.
The examples below use http://localhost:8080 as the default base end point for the service.
The Transport Service web application provides functionality for querying the Registry Service or Search Service for a product or products and retrieving the associated files. The service can be queried using 3 possible methods for encoding the HTTP request parameters: Simple HTTP syntax (name, value) pairs, DIS-Style syntax, or XML query expressions. The following table summarizes the parameters available:
| HTTP Parameter | Description |
|---|---|
| Simple HTTP Syntax - This is the preferred method to query the transport-registry service. | |
| identifier | The identifier for the product to be retrieved in the form of a PDS logical identifier (LID) or the LID and the version identifier (LIDVID). This parameter is required, unless the identifier-list parameter is specified, and may be specified more than once. Due to the 5000 character limit for HTTP POST commands, a safe maximum of specified identifiers is around 50. |
| identifier-list | Because of the 5000 character limitation, the service also supports passing in a URL reference to a text file containing a list of LID/LIDVIDs (one per line in the file). This reference can either be local to the service (e.g., file://) or remote to the service (e.g., http://). This parameter is only available when the service is configured to access a Search Service. This parameter is required, unless the identifier parameter is specified. |
| package | The package type to be returned from the Transport Service. The valid values are ZIP, TGZ to return the compressed packages, and SIZE to return the total size of all files (in bytes) contained in the package once the compressed package is expanded. The values are not case sensitive. The default value is ZIP. This parameter is optional. |
| DIS-Style Syntax | |
| q | The DIS-Style query expression identifying the product (or set of products) to retrieve from the Transport Service. The use of the q parameter is preferred over the use of the xmlq parameter, but it is still discouraged with respect to the use of Simple HTTP Syntax. See the DIS-Style Query page for additional information regarding this syntax. |
| XML Query Expression | |
| xmlq | The XML query expression identifying the product (or set of products) to retrieve from the Transport Service. The details for the format of this query expression will not be covered here. Although supported, the use of the xmlq parameter is discouraged. |
This section details the Simple HTTP syntax for querying the Transport Service. The following is an example syntax for querying a single product:
% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?identifier=<LID|LIDVID>
Assuming the LID or LIDVID was specified correctly, the above query should return a ZIP package (the default) containing the files associated with the specified product along with a text file (md5_checksums.txt) containing an MD5 checksum for each file. The following is an example of querying for two products:
% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?identifier=<LID|LIDVID>&identifier=<LID|LIDVID>
The above query should return a ZIP package containing the files associated with both products. The following is an example of querying for a list of products by specifying a local file containing that list:
% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?identifier-list="file:///tmp/product-list.txt"
The above query should return a ZIP package containing the files associated the products in the list. To specify a remote product list, place the file on an accessible web server and provide a fully qualified URL to the file (e.g., http://...). The following is an example query that will return a TAR/GZIP package:
% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?identifier=<LID|LIDVID>&package=TGZ
The above query should return a TAR/GZIP package containing the files associated with the specified product. The following is an example of a request for the size of the products returned:
% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?identifier=<LID|LIDVID>&package=SIZE
The above query will return an XML document containing the total size of all files (in bytes) contained in the package once the compressed package is expanded. The following is an example of the XML document:
<dirResult>
<dirEntry>
<fileSize>132</fileSize>
</dirEntry>
</dirResult>
When using DIS-Style format, the identifier, identifier-list and package parameters must be encoded as part of the q value parameter. The following is an example query using DIS-Style query syntax:
% curl -X GET -o package.zip -v \
http://localhost:8080/transport-registry/prod?q=identifier+EQ+<LID|LIDVID>+AND+package+EQ+TGZ