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 transporting files from Discipline Node local data repositories. The service can be queried using 3 possible methods for encoding the HTTP request parameters: DIS-Style syntax, XML query expressions, or simple HTTP (name, value) pairs. The following table summarizes the parameters available:

HTTP ParameterDescription
qThe 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.
xmlqThe 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.
OFSN, RTThe Online File Specification Name (OFSN) and Return Type (RT) parameter names, set equal to the requested values.

The following is an example query request via cURL using the q parameter:

% curl -X GET -o results.out -v \
http://localhost:8080/transport-ofsn/prod?q=<keyword-query>
and following is the general syntax for using cURL with the direct HTTP parameters encoding:
% curl -X GET -o results.out -v \
http://localhost:8080/transport-ofsn/prod?OFSN=<ofsn value>&RT=<rt value>

When using DIS-Style format, the OFSN and RT parameters must be encoded as part of the "q" value parameter:

DIS Query ParameterDescription
OFSNThe 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.
RTThe 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>

For example, the following query requests a directory listing from the test-data1 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-ofsn/prod?q=OFSN+EQ+/test-data1+AND+RT+EQ+DIRLIST1

The following tables list all the valid values for the return type keyword. The examples provided assume the existence of a transport-ofsn application deployed within a local Tomcat container running on port 8080. For each possible value of RT, the same example request is shown as encoded with DIS-Style syntax, or simple (name, value) pairs.

"Listing" Return Types

Return TypeDescription
DIRFILELIST Returns an XML document containing all of the filenames (and only the files, not directories) and their sizes, recursing into subdirectories.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/+AND+RT+EQ+DIRFILELIST
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/&RT=DIRFILELIST
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
	<OFSN>/FF01.IMG</OFSN>
	<fileSize>1050624</fileSize>
  </dirEntry>
  <dirEntry>
	<OFSN>/FF01.LBL</OFSN>
	<fileSize>5143</fileSize>
  </dirEntry>
  <dirEntry>
	<OFSN>/test-data2/i943630r.raw</OFSN>
	<fileSize>126976</fileSize>
  </dirEntry>
  <dirEntry>
	<OFSN>/test-data2/i943630r.xml</OFSN>
	<fileSize>7862</fileSize>
  </dirEntry>
  .........
</dirResult>
            	
DIRFILELIST1Identical to DIRFILELIST except that it does not recurse into subdirectories.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/+AND+RT+EQ+DIRFILELIST1
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/&RT=DIRFILELIST1
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
	<OFSN>/FF01.IMG</OFSN>
	<fileSize>1050624</fileSize>
  </dirEntry>
  <dirEntry>
	<OFSN>/FF01.LBL</OFSN>
	<fileSize>5143</fileSize>
  </dirEntry>
</dirResult>
            	
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.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/+AND+RT+EQ+DIRLIST
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/&RT=DIRLIST
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <OFSN>/test-data1</OFSN>
  <fileSize>8669232</fileSize>
  </dirEntry>
  <dirEntry>
    <OFSN>/test-data2</OFSN>
    <fileSize>134838</fileSize>
  </dirEntry>
  <dirEntry>
    <OFSN>/test-data1/test-data11</OFSN>
    <fileSize>4334616</fileSize>
  </dirEntry>
</dirResult>
        		
DIRLIST1 Identical to DIRLIST but does not recursively descend into subdirectories.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/+AND+RT+EQ+DIRLIST1
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/&RT=DIRLIST1
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <OFSN>/test-data1</OFSN>
    <fileSize>8669232</fileSize>
  </dirEntry>
  <dirEntry>
    <OFSN>/test-data2</OFSN>
    <fileSize>134838</fileSize>
  </dirEntry>
</dirResult>
        		
FILELIST Returns an XML document naming the requested file and also giving its size.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/test-data1/FF01.IMG+AND+RT+EQ+FILELIST
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/test-data1/FF01.IMG&RT=FILELIST
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <OFSN>/test-data1/FF01.IMG</OFSN>
    <fileSize>1050624</fileSize>
  </dirEntry>
</dirResult>
            
FILE_LIST An alias for FILELIST.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/test-data1/FF01.IMG+AND+RT+EQ+FILE_LIST
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/test-data1/FF01.IMG&RT=FILE_LIST
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <OFSN>/test-data1/FF01.IMG</OFSN>
    <fileSize>1050624</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.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/FF01.IMG+AND+RT+EQ+FILELISTZIP
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/FF01.IMG&RT=FILELISTZIP
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <OFSN>FF01.IMG.zip</OFSN>
    <fileSize>816445</fileSize>
  </dirEntry>
</dirResult>
        		
FILE_LIST_ZIP An alias for FILELISTZIP.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/FF01.IMG+AND+RT+EQ+FILE_LIST_ZIP
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/FF01.IMG&RT=FILE_LIST_ZIP
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <OFSN>FF01.IMG.zip</OFSN>
    <fileSize>816445</fileSize>
  </dirEntry>
</dirResult>
        		

"Get" Return Types that apply both to PDS3 and PDS4 labels

Return TypeDescription
RAW Returns the requested file without any modification (MIME type application/octet-stream).
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+RAW
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=RAW
RAW_SIZE Generates an XML document containing the size of the raw file that would be returned by the corresponding RAW type.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/FF01.IMG+AND+RT+EQ+RAW_SIZE
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/FF01.IMG&RT=RAW_SIZE
Example response:
<dirResult xmlns="http://osr.jpl.nasa.gov/xml/namespaces/dirlist/1.0">
  <dirEntry>
    <fileSize>1050624</fileSize>
  </dirEntry>
</dirResult>
        		
MD5 Returns a MD5 hash of the file bytes generated on the server side, as plain text.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+MD5
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=MD5
Example response: c3bc003bb99d7364bc7abbdb981f6e09
PDS_TO_JPEG Converts a PDS image to JPEG format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_JPEG
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_JPEG
PDS_TO_JPG Converts a PDS image to JPG format (same as JPEG handler above).
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_JPG
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_JPG
PDS_TO_JP2 Converts a PDS image to JPG 2000 format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_JP2
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_JP2
NOTE: currently, a library bug prevents this handler to work for PDS3 images.
PDS_TO_BMP Converts a PDS image to Windows BMP format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_BMP
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_BMP
NOTE: currently, a library bug prevents this handler to work for PDS3 images.
PDS_TO_GIF Converts a PDS image to Graphics Interchange Format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_GIF
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_GIF
PDS_TO_PNG Converts a PDS image to Portable Network Graphics Format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_PNG
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_PNG
PDS_TO_RAW Converts a PDS image to Raw image Format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_RAW
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_RAW
PDS_TO_TIF Converts a PDS image to Tagged Image File Format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_TIF
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_TIF
PDS_TO_TIFF Converts a PDS image to Tagged Image File Format (same as TIF handler above).
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_TIFF
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_TIFF
PDS_TO_PNM Converts a PDS image to Portable Any Map format.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS_TO_PNM
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS_TO_PNM

"Get" Return Types that apply only to PDS4 labels

Return TypeDescription
PDS4_TO_PVL Converts a PDS4 label into a Parameter Value Language file.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS4_TO_PVL
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS4_TO_PVL
PDS4_TO_HTML Converts a PDS4 label into an HTML representation of the label.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS4_TO_HTML
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS4_TO_HTML
PDS4_TO_HTML_STRUCTURE_ONLY Converts a PDS4 label into an HTML representation of the label structure. As a result, the element contents are stripped out in the resulting file.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/i943630r.xml+AND+RT+EQ+PDS4_TO_HTML_STRUCTURE_ONLY
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/i943630r.xml&RT=PDS4_TO_HTML_STRUCTURE_ONLY
PDS4_TO_CSV Specify to transform a given table into a comma-separated value file.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/Product_Table_Character.xml+AND+RT+EQ+PDS4_TO_CSV
Example request: http://localhost:8080/transport-ofsn/prod?OFSN=/Product_Table_Character.xml&RT=PDS4_TO_CSV

"Get" Return Types that apply only to PDS3 labels

Return TypeDescription
PDS3_TO_PDS4_LABEL Converts a PDS3 label into a PDS4 Product Observational product label.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/ELE_MOM.LBL+AND+RT+EQ+PDS3_TO_PDS4_LABEL
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/ELE_MOM.LBL&rt=PDS3_TO_PDS4_LABEL
NOTE: currently not working because cannot loaf file context-classes.xml
PDS_LABEL Returns a plain text (MIME type text/plain) representation of the PDS3 label specified in the OFSN, including and expanding the STRUCTURE pointers.
Example request: http://localhost:8080/transport-ofsn/prod?q=OFSN+EQ+/CHAN_DATA_20020617.LBL+AND+RT+EQ+PDS_LABEL
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/CHAN_DATA_20020617.LBL&rt=PDS_LABEL
PDS_ZIP Returns the PDS3 label and its references in a ZIP file.
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/mgn-v-rdrs-5-dim-v1.0/mg_1220/fl30s114/fl33s117.img&rt=PDS_ZIP
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/go-j_jsa-ssi-2-redr-v1.0/go_0017/g1/ganymede/c034976/0100r.lbl&rt=PDS_ZIP
PDS_ZIP_SIZE Returns the total size of the PDS3 label file and its references in XML format if you were to download the product with PDS_ZIP and unzip the archive.
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/mgn-v-rdrs-5-dim-v1.0/mg_1220/fl30s114/fl33s117.img&rt=PDS_ZIP_SIZE
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/go-j_jsa-ssi-2-redr-v1.0/go_0017/g1/ganymede/c034976/0100r.lbl&rt=PDS_ZIP_SIZE
Example response:
<?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>
    <fileSize>10390</fileSize>
  </dirEntry>
</dirResult>

"Get" Return Types that apply to PDS3 and PDS4 directories

Return TypeDescription
PDS_ZIPD Returns a directory content packaged as a ZIP file.
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/mgn-v-rdrs-5-dim-v1.0/mg_1416/fo42s186&rt=PDS_ZIPD
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/mgn-v-rdrs-5-dim-v1.0/mg_1220/fl30s114&rt=PDS_ZIPD
PDS_ZIPD_SIZE Returns the total size of a directory content in XML format if you were to download the product with PDS_ZIPD and unzip the archive.
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/mgn-v-rdrs-5-dim-v1.0/mg_1416/fo42s186&rt=PDS_ZIPD_SIZE
Example request: http://localhost:8080/transport-ofsn/prod?ofsn=/data/mgn-v-rdrs-5-dim-v1.0/mg_1220/fl30s114&rt=PDS_ZIPD_SIZE
Example response:
<?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>
    <fileSize>26563938</fileSize>
  </dirEntry>
</dirResult>