Streamable Output
Introduction
Sometimes it is nice to be able to reference an LAS product directly using the URL of the product. For an output page it's easy, just reference the URL of the Product Server with the encoded LAS UI request in a query parameter called "xml". For example, this giant URL:
http://ferret.pmel.noaa.gov/las/ProductServer.do?xml=%3C%3Fxml+version%3D%221.0%22%3F%3E%3ClasRequest+package%3D%22%22+href%3D%22file%3Alas.xml%22%3E%3Clink+match%3D%22%2Flasdata%2Foperations%2Foperation%5B%40ID%3D%27Plot_2D_XY%27%5D%22+%2F%3E%3Cproperties%3E%3Cferret%3E%3Csize%3E.5%3C%2Fsize%3E%3Cview%3Exy%3C%2Fview%3E%3Cformat%3Eshade%3C%2Fformat%3E%3Ccontour_levels+%2F%3E%3Ccontour_style%3Edefault%3C%2Fcontour_style%3E%3Cexpression+%2F%3E%3Cfill_levels+%2F%3E%3Cimage_format%3Edefault%3C%2Fimage_format%3E%3Cinterpolate_data%3Efalse%3C%2Finterpolate_data%3E%3Cmark_grid%3Edefault%3C%2Fmark_grid%3E%3Cpalette%3Edefault%3C%2Fpalette%3E%3Cset_aspect%3Edefault%3C%2Fset_aspect%3E%3Csize%3E0.5%3C%2Fsize%3E%3Cuse_graticules%3Edefault%3C%2Fuse_graticules%3E%3Cuse_ref_map%3Etrue%3C%2Fuse_ref_map%3E%3C%2Fferret%3E%3C%2Fproperties%3E%3Cargs%3E%3Clink+match%3D%22%2Flasdata%2Fdatasets%2FNOAA-CIRES-CDC-Leetmaa_Ocean_Analysis%2Fvariables%2FCDC_DS17-otemp2027%22+%2F%3E%3Cregion%3E%3Crange+low%3D%22122.0%22+type%3D%22x%22+high%3D%22288.5%22+%2F%3E%3Crange+low%3D%22-35.0%22+type%3D%22y%22+high%3D%2245.0%22+%2F%3E%3Cpoint+v%3D%22500.00%22+type%3D%22z%22+%2F%3E%3Cpoint+v%3D%2201-Jan-1980%22+type%3D%22t%22+%2F%3E%3C%2Fregion%3E%3C%2Fargs%3E%3C%2FlasRequest%3E
will return an output page from the product server.
In addition to being able to reference the entire HTML page of an output product, sometimes it's nice to be able to include a link to just the plot image for example. The LAS product server can stream back certain products so that just the image itself is returned. Here are the steps necessary to prepare an operation so that one or more of its results can be streamed back to the client directly (including using the a Product Server URL in the src attribute of the img tag).
Step 1 - Setting up the streamable output in the operation definition
Configuration for a typical operation for LAS looks something like this:
<operation name="2D Plot" ID="Plot_2D" template="output" script="Plot_2D">
<service>ferret</service>
<response ID="PlotResp">
<result type="image" ID="plot_image" streamable="true" mime_type="image/gif"/>
<result type="ps" ID="plot_postscript" streamable="true" mime_type="application/postscript"/>
<result type="image" ID="ref_map"/>
<result type="map_scale" ID="map_scale"/>
<result type="debug" ID="debug"/>
<result type="cancel" ID="cancel"/>
</response>
</operation>
What's interesting about this operation are the two result elements which are identified as "streamable" with the streamable="true" attribute.
If your operation creates a file and you want to be able to stream the bytes of that file directly to the client (which will cause the browser clients to open the assoicated helper application) you can do so by first setting the streamable=true attribute in the result definition.
Step 2 - Adding query parameters to the URL to request a streamable result
To get a particular result to stream back there are two query parameters that must be added to the Product Server request. They are:
-
stream=true
-
stream_ID=result_ID
If those two parameters are added to the URL, then the Product Server will stream back the bytes of the identified result directly to the requesting client. Adding "&stream=true&stream_ID=plot_image" to the example above gives a ULR that will return an image only. Go ahead and click on it and see for yourself.
http://ferret.pmel.noaa.gov/las/ProductServer.do?xml=%3C%3Fxml+version%3D%221.0%22%3F%3E%3ClasRequest+package%3D%22%22+href%3D%22file%3Alas.xml%22%3E%3Clink+match%3D%22%2Flasdata%2Foperations%2Foperation%5B%40ID%3D%27Plot_2D_XY%27%5D%22+%2F%3E%3Cproperties%3E%3Cferret%3E%3Csize%3E.5%3C%2Fsize%3E%3Cview%3Exy%3C%2Fview%3E%3Cformat%3Eshade%3C%2Fformat%3E%3Ccontour_levels+%2F%3E%3Ccontour_style%3Edefault%3C%2Fcontour_style%3E%3Cexpression+%2F%3E%3Cfill_levels+%2F%3E%3Cimage_format%3Edefault%3C%2Fimage_format%3E%3Cinterpolate_data%3Efalse%3C%2Finterpolate_data%3E%3Cmark_grid%3Edefault%3C%2Fmark_grid%3E%3Cpalette%3Edefault%3C%2Fpalette%3E%3Cset_aspect%3Edefault%3C%2Fset_aspect%3E%3Csize%3E0.5%3C%2Fsize%3E%3Cuse_graticules%3Edefault%3C%2Fuse_graticules%3E%3Cuse_ref_map%3Etrue%3C%2Fuse_ref_map%3E%3C%2Fferret%3E%3C%2Fproperties%3E%3Cargs%3E%3Clink+match%3D%22%2Flasdata%2Fdatasets%2FNOAA-CIRES-CDC-Leetmaa_Ocean_Analysis%2Fvariables%2FCDC_DS17-otemp2027%22+%2F%3E%3Cregion%3E%3Crange+low%3D%22122.0%22+type%3D%22x%22+high%3D%22288.5%22+%2F%3E%3Crange+low%3D%22-35.0%22+type%3D%22y%22+high%3D%2245.0%22+%2F%3E%3Cpoint+v%3D%22500.00%22+type%3D%22z%22+%2F%3E%3Cpoint+v%3D%2201-Jan-1980%22+type%3D%22t%22+%2F%3E%3C%2Fregion%3E%3C%2Fargs%3E%3C%2FlasRequest%3E&stream=true&stream_ID=plot_image
In theory, one should be able to steam back more that one result by including multiple stream_ID query parameters in the request URL, but yours truely has not yet figured out how to manage a multi-part MIME message you now you'll just get a message explaining that if you have more than one stream_ID parameters on a request. Stay tuned.