The query servlet is nice for general purpose queries, but for those who just want to retrieve products, it's a bit annoying to have to process all that XML and do base-64 conversions. Is there a simpler way? Absolutely. The product servlet deals with just products, and delivers them in their appropriate form direct over HTTP.
Requirements
The product servlet provides HTTP access to products, so naturally, you'll need to use a language or system that supports HTTP client access to HTTP servers. Where can you find such a system? Your handy-dandy web browser is one! Most programming languages also have HTTP APIs either built-in or freely available.
You also need to know
- The URL of the product servlet that has access to the product server you want to query.
- The object name of the product server you want to access.
- The keyword query expression that can be understood by the product server.
Making a Query
The product servlet accepts either GET or POST requests of URL-encoded form data. In response, it delivers a matching product (if any can be found) in the format appropriate to the product's MIME type. You can also request a specific MIME type. If there's no matching product, you get HTTP error 404 (not found).
The parameters that the servlet expects are:
| Parameter Name | Obligation | Meaning |
|---|---|---|
| object | Once | Names the product server to receive the query. This parameter must be specified exactly once and takes the form urn:eda:proto:name, such as urn:eda:rmi:PDS.Atmos.Product for the RMI-accessed Atmoshpheres node of the Planetary Data System. |
| keywordQuery | Once | Lists the keyword query expression to pass to the product server, such as PatientID = 19928 or ONLINE_FILE_SPECIFICATION_NAME = data/images/mars.jpg. |
| id | None or Once | Optional parameter that identifies a single product to retrieve if more than one product match. A product server may return multiple matching products. By default, the product servlet returns the first matching product only. By specifying the id parameter, you can select a specific product when more than one match. (In practice, not a single product server to date has ever returned more than one match.) |
| mimeType | Zero to Many | Optional parameter that lists acceptable MIME types for the product (see below). |
MIME Types
Many product servers are capable of conversion of products from a system-specific storage medium into an Internet-standard interoperable format. Internet-standard MIME types are what drives this mechanism. The product servlet can take a list of specific MIME types and pass them to the product server for consideration in retrieving your products.
MIME type conversions are like suggestions to product servers. Product servers are not obligated to honor all conversions, and indeed you may well receive 404 (not found) for a conversion that makes no sense to a particular product server (such as an audio clip to text/html).
The mimeType parameter is what drives this mechanism. By specifying one or more mimeType parameters in your GET or POST request, you list the preferred MIME types in which you would like the product delivered. Furthermore, you can use wildcards to further enable a product server to satisfy you. The ordering of the parameters is significant.
Here are some examples. Suppose the request URI part of the URL contained:
...mimeType=text/rtf&mimeType=text/*...
This specifies two MIME types:
- text/rtf, the Rich Text Format, is the preferred format for delivering products.
- text/* means any text type. Any text is better than no text if for some reason the product server can't give a Rich Text Format product.
Here's another example:
...mimeType=image/png&mimeType=image/jpeg...
This indicates that you'd like a Portable Network Graphic format image, if possible, but will settle for a JPEG-JFIF format image. No other image format (especially not the proprietary and ancient GIF format) is acceptable. Adding an additional &mimeType=image/* would mean any image format would be fine. Adding &mimeType=*/* means any format would be acceptable, be it audio, video, text, image, or otherwise.
If there are no mimeType parameters, then the product servlet uses a default list containing just */*, meaning any type is fine.
Example
To retrieve an image of Mars from the PDS product server at the Imaging Node, in PNG format if possible and any image format otherwise, try the following:
This URL contains linebreaks for readability only. Let's take this URL apart to see what's going on:
- The URL to the product servlet in this case is http://starbrite.jpl.nasa.gov/prod. Often the URL will take this form, or may be http://hostname/servlet/jpl.oodt.servlets.ProductServlet. Most people prefer the shorter form.
- The question mark ? separates the request URI from its parameters.
- The first parameter, mimeType=image/png, says that Portable Network Graphics images are preferred.
- The second parameter, mimeType=image/*, says that if the product server can't convert to or other provide Portable Network Graphics format images, then any image format is acceptable.
- The third parameter, object=urn:eda:rmi:PDS.Img.Product, identifies the product server.
- The fourth parameter, keywordQuery=... names the query expression. In this case, it's OFSN = thumbnail/mgs-m-moc-na_wa-2-sdp-l0-v1.0/mgsc_1082/m09063/m0906352.imq.jpg.
The response to this URL's GET request is a JPEG-JFIF image (sorry, PNG's not yet available from the PDS Image Node) containing a picture of some planetary surface. Neat, huh?