| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <document> |
| <properties> |
| <title>Using the Product Servlet</title> |
| <author email="kelly@apache.org">Sean Kelly</author> |
| </properties> |
| |
| <body> |
| <section name="Using the Product Servlet"> |
| <p>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. |
| </p> |
| </section> |
| <section name="Requirements"> |
| |
| <p>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. |
| </p> |
| |
| <p>You also need to know</p> |
| |
| <ul> |
| <li>The URL of the product servlet that has access to the |
| product server you want to query.</li> |
| <li>The object name of the product server you want to |
| access.</li> |
| <li>The keyword query expression that can be understood by the |
| product server.</li> |
| </ul> |
| </section> |
| <section name="Making a Query"> |
| |
| <p>The product servlet accepts either <code>GET</code> or |
| <code>POST</code> 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). |
| </p> |
| |
| <p>The parameters that the servlet expects are:</p> |
| |
| <table border="0" cellpadding="3" cellspacing="0"> |
| |
| <thead> |
| <tr> |
| <th>Parameter Name</th> |
| <th>Obligation</th> |
| <th>Meaning</th> |
| </tr> |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td><code>object</code></td> |
| <td>Once</td> |
| <td>Names the product server to receive the query. This |
| parameter must be specified exactly once and takes the form |
| <code>urn:eda:<var>proto</var>:<var>name</var></code>, such |
| as <code>urn:eda:rmi:PDS.Atmos.Product</code> for the |
| RMI-accessed Atmoshpheres node of the Planetary Data System. |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td><code>keywordQuery</code></td> |
| <td>Once</td> |
| <td>Lists the keyword query expression to pass to the |
| product server, such as <code>PatientID = 19928</code> or |
| <code>ONLINE_FILE_SPECIFICATION_NAME = |
| data/images/mars.jpg</code>. |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td><code>id</code></td> |
| <td>None or Once</td> |
| <td>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 <code>id</code> parameter, you can select a |
| specific product when more than one match. (In practice, |
| not a single product server <em>to date</em> has ever |
| returned more than one match.) |
| </td> |
| |
| </tr> |
| |
| <tr> |
| <td><code>mimeType</code></td> |
| <td>Zero to Many</td> |
| <td>Optional parameter that lists acceptable MIME types for |
| the product (see below). |
| </td> |
| |
| </tr> |
| |
| </tbody> |
| </table> |
| </section> |
| <section name="MIME Types"> |
| |
| <p>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. |
| </p> |
| |
| <p>MIME type conversions are like <em>suggestions</em> 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 <code>text/html</code>). |
| </p> |
| |
| <p>The <code>mimeType</code> parameter is what drives this |
| mechanism. By specifying one or more <code>mimeType</code> |
| parameters in your <code>GET</code> or <code>POST</code> 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. |
| </p> |
| |
| <p>Here are some examples. Suppose the request URI part of the |
| URL contained:</p> |
| |
| <pre>...mimeType=text/rtf&mimeType=text/*...</pre> |
| |
| <p>This specifies two MIME types:</p> |
| |
| <ol> |
| <li><code>text/rtf</code>, the Rich Text Format, is the |
| preferred format for delivering products. |
| </li> |
| |
| <li><code>text/*</code> 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. |
| </li> |
| </ol> |
| |
| <p>Here's another example:</p> |
| |
| <pre>...mimeType=image/png&mimeType=image/jpeg...</pre> |
| |
| <p>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 |
| <code>&mimeType=image/*</code> would mean any image format |
| would be fine. Adding <code>&mimeType=*/*</code> means |
| <em>any format</em> would be acceptable, be it audio, video, text, |
| image, or otherwise. |
| </p> |
| |
| <p>If there are <em>no</em> <code>mimeType</code> parameters, then |
| the product servlet uses a default list containing just |
| <code>*/*</code>, meaning any type is fine. |
| </p> |
| </section> |
| <section name="Example"> |
| |
| <p>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: |
| </p> |
| |
| <p><code><a |
| href="http://starbrite.jpl.nasa.gov/prod?mimeType=image/png&mimeType=image/*&object=urn:eda:rmi:PDS.Img.Product&keywordQuery=ONLINE_FILE_SPECIFICATION_NAME+%3D+thumbnail/mgs-m-moc-na_wa-2-sdp-l0-v1.0/mgsc_1082/m09063/m0906352.imq.jpg">http://starbrite.jpl.nasa.gov/prod?<br/>mimeType=image/png&<br/>mimeType=image/*&<br/>object=urn:eda:rmi:PDS.Img.Product&<br/>keywordQuery=OFSN+%3D+thumbnail/mgs-m-moc-na_wa-2-sdp-l0-v1.0/mgsc_1082/m09063/m0906352.imq.jpg</a></code></p> |
| |
| <p>This URL contains linebreaks for readability only. Let's take |
| this URL apart to see what's going on: |
| </p> |
| |
| <ul> |
| <li>The URL to the product servlet in this case is |
| <code>http://starbrite.jpl.nasa.gov/prod</code>. Often the URL |
| will take this form, or may be |
| <code>http://<var>hostname</var>/servlet/jpl.oodt.servlets.ProductServlet</code>. |
| Most people prefer the shorter form. |
| </li> |
| |
| <li>The question mark <code>?</code> separates the request URI |
| from its parameters. |
| </li> |
| |
| <li>The first parameter, <code>mimeType=image/png</code>, says |
| that Portable Network Graphics images are preferred. |
| </li> |
| |
| <li>The second parameter, <code>mimeType=image/*</code>, says |
| that if the product server can't convert to or other provide |
| Portable Network Graphics format images, then <em>any image |
| format</em> is acceptable. |
| </li> |
| |
| <li>The third parameter, |
| <code>object=urn:eda:rmi:PDS.Img.Product</code>, identifies the |
| product server. |
| </li> |
| |
| <li>The fourth parameter, <code>keywordQuery=...</code> names |
| the query expression. In this case, it's <code>OFSN = |
| thumbnail/mgs-m-moc-na_wa-2-sdp-l0-v1.0/mgsc_1082/m09063/m0906352.imq.jpg</code>. |
| </li> |
| </ul> |
| |
| <p>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? |
| </p> |
| </section> |
| </body> |
| </document> |