Operation

This document describes how to operate the Web Grid Product Server software contained in the pds-web-ps package. The Product Server software is a web application for for transporting files from Discipline Node local data repositories. The following topics can be found in this section:

Interface

The Web Grid Product Server 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 Product Server:

  • 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 URL for the service.

Product Query

The Web Grid Product Server provides functionality for for transporting files from Discipline Node local data repositories. The following table details the parameters available for querying a product:

ParameterDescription
qThe keyword query expression that selects what product (or set of files) to retrieve from the Product Server. This is the preferred parameter for querying the Product Server. This parameter is required if the xmlq parameter is not specified.
xmlqThe XML query expression that selects what product (or set of files) to retrieve from the Product Server. The details for the format of this query expression will not be covered here. Although supported, the q parameter 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 product.out -v \
http://localhost:8080/pds/prod?q=<keyword-query>
      

The following table details the required keywords for the keyword query expression:

KeywordDescription
OFSNThe online file specification name for a file or directory accessible by the Product Server. 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 Product Server. 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 Product Server queries, this means changing your spaces to +'s and your equals signs to %3D's. The following example of a keyword query expression details the difference between an unencoded and encoded query:

OFSN = <online-file-specification-name> AND RT = <return-type>

  properly encoded request:

OFSN+%3D+<online-file-specification-name>+AND+RT+%3D+<return-type>
      

The following table details the valid values for the return type keyword:

Return TypeDescription
DIRFILELISTReturns an XML document containing all of the filenames (and only the files, not directories) and their sizes, recursing into subdirectories.
DIRFILELIST1Identical to DIRFILELIST except that it does not recurse into subdirectories.
DIRLISTReturns 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>
            
FILELISTZIPSimilar to FILELIST except that it tells what the size of the requested file would be if compressed into a ZIP archive.
PDS_FILELISTReturns 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_FILELISTZIPReturns 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_JPEGReturns the PDS-format image at the given OFSN, converted into the JPEG/JFIF image format.
PDS_JPEG_SIZEReturns an XML document with the size of the JPEG file that would be generated by the corresponding PDS_JPEG query.
PDS_LABELReturns a plain text (MIME type text/plain) representation of the PDS label specified in the OFSN.
PDS_ZIPReturns the PDS label and its references in a ZIP file.
PDS_ZIPDReturns a ZIP archive of all of the files and directories under the given OFSN, which should be a directory.
PDS_ZIPD_SIZEReturns an XML document with the size of the ZIP archive that would be generated by the corresponding PDS_ZIPD query.
PDS_ZIPNReturns a ZIP archive containing the requested file and all of the files that it references.
PDS_ZIPN_SIZEReturns an XML document with the size of the ZIP archive that would be generated by the corresponding PDS_ZIPN query.
PDS_ZIPN_TESReturns 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_SIZEReturns an XML document with the size of the ZIP archive that would be generated by the corresponding PDS_ZIPN_TES query.
PDS_ZIP_SIZEReturns 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.
RAWReturns the requested file without any modification (MIME type application/octet-stream).
RAW_SIZEReturns 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 Product Server's root directory (specified by the jpl.pds.server.FileQueryHandler.productDir property during configuration):

% curl -X GET -o product.out -v \
http://localhost:8080/pds/prod?q=OFSN+%3D+data/+AND+RT+%3D+DIRLIST1