 |
|
|
 |
Software Documentation
- About Transport Service
- Installation
- Operation
Download
Project Documentation
Operation
This document describes how to operate the Transport Service software contained in the transport-ofsn package. The Transport Service software is a web application for transporting files from Discipline Node local data repositories. The following topics can be found in this section:
Interface
The Transport Service provides a REST-based interface accessible via HTTP for interacting with the service. This interface accepts both HTTP GET and HTTP POST style requests. Because the REST-based interface operates over HTTP, there are several options for interacting with the Transport Service:
- Web Browser
Any standard web browser (e.g., Firefox, Safari, Internet Explorer, etc.) will allow interaction with the service.
- cURL
The cURL utility offers the most flexible means for interacting with the service. 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 service. 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.
Product Query
The Transport Service provides functionality for for transporting files from Discipline Node local data repositories. The following table details the parameter available:
| HTTP Parameter | Description |
|---|---|
| q | The DIS-Style query expression identifying the product (or set of files) to retrieve from the Transport Service. This is the preferred parameter for querying the Transport Service and is required if the xmlq parameter is not specified. Additional information regarding the DIS-Style query format can be found at the Apache OODT DIS-Style Query page. |
| xmlq | The XML query expression identifying the product (or set of files) to retrieve from the Transport Service. The details for the format of this query expression will not be covered here. Although supported, the q parameter is preferred and is utilized by all existing client interfaces. This parameter is required if the q parameter is not specified. |
The following is an example query request via cURL using the q parameter:
% curl -X GET -o results.out -v \
http://localhost:8080/transport-service/prod?q=<keyword-query>
The Transport Service accepts the following parameters in DIS-Style format for the parameter above:
| DIS Query Parameter | Description |
|---|---|
| OFSN | The online file specification name for a file or directory accessible by the Transport Service. The keyword can be specified in long form as ONLINE_FILE_SPECIFICATION_NAME. This keyword is required. |
| RT | The return type specifies how the file or directory will be returned to the client from the Transport Service. The keyword can be specified in long form as RETURN_TYPE. The table below details the valid value list for this keyword. This keyword is required. |
The keyword query expression must be properly encoded by the rules of Uniform Resource Identifiers whether they're part of the URL in an HTTP GET request or transmitted separately in an HTTP POST request. In general, this means that characters spaces and equals signs in query expressions need to be properly escaped. Most browsers and HTTP libraries will happily relax these rules, though, especially in cases where there is no ambiguity. For Transport Service queries, this basically means changing your spaces to +'s. The following example of a keyword query expression details the difference between an unencoded and encoded query:
OFSN EQ <online-file-specification-name> AND RT EQ <return-type>
properly encoded request:
OFSN+EQ+<online-file-specification-name>+AND+RT+EQ+<return-type>
The following table details the valid values for the return type keyword:
| Return Type | Description |
|---|---|
| DIRFILELIST | Returns an XML document containing all of the filenames (and only the files, not directories) and their sizes, recursing into subdirectories. |
| DIRFILELIST1 | Identical to DIRFILELIST except that it does not recurse into subdirectories. |
| DIRLIST | Returns an XML document with directory names (and only directory names) and total size of files in each directory starting in the requested directory and traversing into the subdirectories. |
| DIRLIST1 | Identical to DIRLIST but does not recursively descend into subdirectories. An example response looks like:
<?xml version="1.0"?>
<!DOCTYPE dirresult PUBLIC "-//JPL/DTD OODT dirresult 1.0//EN"
"http://starbrite.jpl.nasa.gov:80/dtd/dirresult.dtd">
<dirResult>
<dirEntry>
<OFSN>data/ody-m-rss-1-raw-v1.0/odrs_0001</OFSN>
<fileSize>39360</fileSize >
</dirEntry>
<dirEntry>
<OFSN>data/ody-m-rss-1-raw-v1.0/odrs_0008</OFSN>
<fileSize>42880</fileSize >
</dirEntry>
<dirEntry>
<OFSN >data/ody-m-rss-1-raw-v1.0/odrs_0002</OFSN>
<fileSize>35280</fileSize>
</dirEntry>
</dirResult>
|
| FILELIST | Returns an XML document naming the requested file and also giving its size. An example response looks like:
<?xml version="1.0"?>
<!DOCTYPE dirresult PUBLIC "-//JPL/DTD OODT dirresult 1.0//EN"
"http://starbrite.jpl.nasa.gov:80/dtd/dirresult.dtd">
<dirResult>
<dirEntry>
<OFSN>data/ody-m-rss-1-raw-v1.0/odrs_0001/eop/11352136.lbl</OFSN>
<fileSize>1440</fileSize>
</dirEntry>
</dirResult>
|
| FILELISTZIP | Similar to FILELIST except that it tells what the size of the requested file would be if compressed into a ZIP archive. |
| PDS_FILELIST | Returns a file listing of the requested PDS label file and its references in XML format. This is similar to FILELIST but instead of giving the size of the requested file, it parses the requested file as a PDS label and gives the sizes of all referenced files. |
| PDS_FILELISTZIP | Returns an XML document with the size of the ZIP archive that would be downloaded with PDS_ZIP but not if you expanded the archive. |
| PDS_JPEG | Returns the PDS-format image at the given OFSN, converted into the JPEG/JFIF image format. |
| PDS_JPEG_SIZE | Returns an XML document with the size of the JPEG file that would be generated by the corresponding PDS_JPEG query. |
| PDS_LABEL | Returns a plain text (MIME type text/plain) representation of the PDS label specified in the OFSN. |
| PDS_ZIP | Returns the PDS label and its references in a ZIP file. |
| PDS_ZIPD | Returns a ZIP archive of all of the files and directories under the given OFSN, which should be a directory. |
| PDS_ZIPD_SIZE | Returns an XML document with the size of the ZIP archive that would be generated by the corresponding PDS_ZIPD query. |
| PDS_ZIPN | Returns a ZIP archive containing the requested file and all of the files that it references. |
| PDS_ZIPN_SIZE | Returns an XML document with the size of the ZIP archive that would be generated by the corresponding PDS_ZIPN query. |
| PDS_ZIPN_TES | Returns a ZIP archive that contains all files matching the AAAnnnnn format in the same directory as the requested OFSN, and all of their referenced files. |
| PDS_ZIPN_TES_SIZE | Returns an XML document with the size of the ZIP archive that would be generated by the corresponding PDS_ZIPN_TES query. |
| PDS_ZIP_SIZE | Returns the total size of the PDS label file and its references in XML format if you were to download the product with PDS_ZIP and unzip the archive. |
| RAW | Returns the requested file without any modification (MIME type application/octet-stream). |
| RAW_SIZE | Returns an XML document with the size of the raw file that would be returned by the corresponding RAW query. |
The following query requests a directory listing from the data sub-directory found under the Transport Service's root directory (specified by the productRoot property during configuration):
% curl -X GET -o results.out -v \
http://localhost:8080/transport-service/prod?q=OFSN+EQ+data/+AND+RT+EQ+DIRLIST1
 |
 |
|
 |
|