A request that is submitted to the LAS product server contains the ID of the operation which is to be performed. An operation can be the combination of one or more sub-operations. When the operation is complete, a "product" is returned to the user -- usually an HTML page with a combination of images, text and/or data files. LAS knows what operations are to be run, what services are to be invoked to perform those operations, what options are associated with the operation and what the resulting products will be because of configuration information contained in the operationsV7.xml file.
Understanding the details of the operationsV7.xml file is a necessary step to being able to define new operations. The details you need are presented on this page and the file itself contains lots of examples of correct configuration information for many different types of operations and products.
We'll begin with a relatively simple operation. The complete definition of the operation to create a text table is shown below.
<operation ID="Data_Extract" default="true" name="Table of values (text)"
output_template="table"
service_action="Data_Extract" order="0300"
category="table" minvars="1" maxvars="9999">
<service>ferret</service>
<response ID="Data_Extract_Response">
<result type="text" ID="ferret_listing" streamable="true"
mime_type="text/plain" />
<result type="debug" ID="debug" file_suffix=".txt"/>
</response>
<region>
<intervals name="x" />
<intervals name="y" />
<intervals name="z" />
<intervals name="t" />
<intervals name="xy" />
<intervals name="xz" />
<intervals name="xt" />
<intervals name="yz" />
<intervals name="yt" />
<intervals name="zt" />
<intervals name="xyz" />
<intervals name="xyt" />
<intervals name="xzt" />
<intervals name="yzt" />
<intervals name="xyzt" />
<degenerate/>
</region>
<grid_types>
<grid_type name="regular" />
</grid_types>
<optiondef IDREF="Options_Data"/>
</operation>
Let's break it down element by element and attribute by attribute starting with the <operation> element.
<operation ID="Data_Extract" default="true" name="Table of values (text)"
output_template="table"
service_action="Data_Extract" order="0300"
category="table" minvars="1" maxvars="9999">
The name attribute is used by the Version 7+ user interface to display this operation to the user. It should be short, but descriptive phrase of the product. The ID should be a string that is unique among all of the other operation IDs. The output_template will correspond to a file name in the WebContenet/productserver/templates directory. For this example, the file should be named table.vm. This is the file is the Velocity template that will be used to render the output from the product into its final form. The product is normally rendered as an HTML page, but any text document can be created using the Velocity Template Language. The service_action attribute also corresponds to a file that is used by LAS. However, this file belongs to the backend service that is ultimately responsible for creating the product. In the distribution these files are found in the JavaSource/resources directory in a sub-directory under a directory named after the service. The actual location of these files is controlled by the configuration file for that service. In this particular example the directory is JavaSource/resources/ferret/scripts and the file is Data_Extract.jnl. The order attribute controls the order in which this operation is listed in the version 7 user interface. The first two digits are typically used to group similar operations together ("03" are data extraction operations) and the last two digits are used to control the order of this particular operation within that group. The category attribute determines where the operation appears on the interface. The operations in the "visualization" category appear in the left-hand navigation section. Other categories appear elsewhere in the interface. The type attribute is used to further group similar operations of a particular category together on the interface.
<service>ferret</service>
The <service> is used to name the service which will perform this operation. The collection of services available for a particular LAS are found in the productserver.xml configuration file which is created and placed in the conf/server directory during the LAS installation and configuration process.
Now let's take a look at the <response> element and its children the <result> elements.
<response ID="Data_Extract_Response">
<result type="text" ID="ferret_listing" streamable="true"
mime_type="text/plain" file_suffix=".txt"/>
<result type="debug" ID="debug" file_suffix=".txt"/>
</response>
A single operation can create multiple output files. A <result> element is used to describe the characteristics of each of the possible output files. A particular invocation of an operation may or may not actually create all of the result files depending on options selected by the user. However, the product server will use the description of each result to communicate to the backend server where to place the files it does create and the backend service will respond with information letting which results were created and where they are located. The attribute which describe a result are as follows:
| Attribute | Meaning |
|---|---|
| type | This is a general output time. Known types are image, netCDF and text. There are strict requirements for this attribute. |
| ID | This identifies the result and must be unique (at least among the results in a particular <response> element). |
| streamable | If you'd like the product server to optional stream back the bytes of this result to the client when requested, you must include this attribute with the value equal to "true". This is handy for embedding the URL of an LAS image into a the <img> tag of an HTML page. |
| mime_type | When the result streams back to the client, this is the MIME type that will be set in the content header of the response. |
| file_suffix | When the product server creates the file names for the backend service to use for creating the result, it will give the file a name that ends in with the value of this attribute. |
The <region> element determines the "view" (which of the underlying 4 axes can be specified as an interval) when a request is made for this product.
<region>
<intervals name="x" />
<intervals name="y" />
<intervals name="z" />
<intervals name="t" />
<intervals name="xy" />
<intervals name="xz" />
<intervals name="xt" />
<intervals name="yz" />
<intervals name="yt" />
<intervals name="zt" />
<intervals name="xyz" />
<intervals name="xyt" />
<intervals name="xzt" />
<intervals name="yzt" />
<intervals name="xyzt" />
</region>
With this operation any and all axes could be defined on a interval when making a request for this product.
The <grid_types> element is a container for the <grid_type> elements. The grid_type is a description of the underlying grid upon which the data are defined. Right now only two values are allowed, "regular" and "scattered". When the new user interface asks for a list of all possible operations for a particular data set, variable and axes selection it will only display operations that match the underlying grid_type of the selected variable.
<grid_types>
<grid_type name="regular" />
</grid_types>
Finally, the user interface presents the user a collection of options that control some characteristics of the final product.
<optiondef IDREF="Options_Data"/>
Which options go with which operation in the new user interface is controlled by this association with entries in the options.xml file.
There are a few more things we need to learn about the file to fully understand how it is used in LAS to build operations. The operations in the visualization category appear in the left-hand navigation section of the UI. Those operations have additional information in their <region> section.
For example, the operations that makes 1D plots along the x, y, or z axis looks like this:
<operation ID="Plot_1D_zoom" default="true" name="Line plot"
minvars="1" maxvars="12"
type="Line Plots" output_template="zoom"
service_action="Plot_1D" order="0102"
category="visualization" isZoomable="true">
<service>ferret</service>
<response ID="PlotResp">
<result type="image" ID="plot_image" streamable="true" mime_type="image/gif" file_suffix=".gif"/>
<!-- <result type="ps" ID="plot_postscript" streamable="true" mime_type="application/postscript" file_suffix=".ps"/> -->
<result type="image" ID="ref_map" file_suffix=".gif"/>
<result type="map_scale" ID="map_scale" file_suffix=".xml"/>
<result type="debug" ID="debug" file_suffix=".txt"/>
<result type="cancel" ID="cancel" file_suffix=".txt"/>
</response>
<region>
<intervals name="x" type="Line Plots" title="Longitude"/>
<intervals name="y" type="Line Plots" title="Latitude"/>
<intervals name="z" type="Line Plots" title="Depth"/>
<!--<intervals name="t" />-->
</region>
<grid_types>
<grid_type name="regular" />
</grid_types>
<optiondef IDREF="Options_1D_7"/>
</operation>
In this case, since the operation is a visualization it will appear in the left-hand navigation section of the interface. These operations are group according to the dimension which is specified as an interval (rather than as a fixed point). In the collection of <interval> elements, the type groups these with other "Line Plots" operations and specifies the name that will appear in the interface when presenting this type of plot to the user in the <title> element.