0.8.1-rc1/product/src/site/xdoc/servlet/index.xml - oodt - Git at Google

 <?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&amp;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&amp;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>&amp;mimeType=image/*</code> would mean any image format
 	would be fine.  Adding <code>&amp;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&amp;mimeType=image/*&amp;object=urn:eda:rmi:PDS.Img.Product&amp;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&amp;<br/>mimeType=image/*&amp;<br/>object=urn:eda:rmi:PDS.Img.Product&amp;<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>
	<?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>