At times it may be useful to have a product that consists entirely of the results of a database query. Scattered data (i.e. insitu or non-gridded) is often stored in relational databases. In the operations V7.xml file operations defined with the database service will make use of the LAS database backend service to connect to a RDBMS, issue queries and store the results in the LAS output directory in the desired format. For operations where no further processing is required the webrowset format should be specified. This standard XML format allows results to be communicated back to the client web page and processed by an accompanying XSL stylesheet.
This document describes the steps necessary to add a database-only service to the default LAS configuration and can be used as a starting point for developing your own dabase-only operations.
operationsV7.xml
The first step is to define a new operation. Add the following to the operationsV7.xml file just after the opening <operations ...> tag:
<!-- BEGIN DB_only operation --> <operation name="DB_only" ID="DB_only" output_template="DB_only" service_action="DB_only"> <response ID="DBExtractResponse"> <result type="debug" ID="db_debug" file_suffix=".txt"/> <result type="xml" ID="webrowset" file_suffix=".xml"/> </response> <service>database</service> </operation> <!-- END DB_only operation -->
The attributes specified in the <operation ...> tag are:
- name
- The name that will appear in the LAS V7 user interface for this operation
- ID
- LAS internal ID used also in ui.xml (Note -- Must begin with a capital letter.)
- output_template
- Velocity template used by the product server to create the response sent back to the browser.
- service_action
- Velocity template used by the database backend service to create the SQL query sent to the RDBMS.
The most important thing here is to make sure to specify the webrowset <result .../>:
<result type="xml" ID="webrowset" file_suffix=".xml"/>
Products created in the LAS output directory will appear with '_webrowset.xml' appended. The webrowset is a set of XML markup for the output of SQL queries. It is popular among java devopers.
In order to take advantage of the new operation we must add it to our user interface.
If you set up your default LAS to include the insitu demos you should have the insitu_demo_ui.xml file in the conf/server/ directory. We will be adding this new operation to the list of operations available for the surface only insitu data configured with insitu_demo_2.xml.
las.xml
First make sure that this dataset is referenced and that this reference is not commented out. In las.xml you should see:
... <!-- Sample insitu datasets --> <!ENTITY insitu_demo_1 SYSTEM "insitu_demo_1.xml"> <!ENTITY insitu_demo_2 SYSTEM "insitu_demo_2.xml"> ... <!-- Datasets --> ... &insitu_demo_2; ...
insitu_ui.xml
Now we need to add the DB_only operation to the set of operations defined for the insitu_demo_2 dataset. Look for the following block of code in insitu_ui.xml and amend it by adding a menu item for the DB_only operation:
<menu type="ops" name="Ops_insituSurfaceXY"> <item values="insitu_poly_xy,gif">Raw data plot</item> <item values="insitu_gaussian_xy,gif">Gridded data plot</item> <item values="insitu_data_cdf,cdf,20">NetCDF file</item> <item values="insitu_data,txt,20">ASCII table</item> <item values="DB_only,xml,1">DB_only (webrowset)</item> </menu>
database template
The database templates should be located in $LAS_HOME/WebContent/WEB-INF/classes/resources/database/templates/. When LAS is compiled and deployed, this directory will be expanded in the TOMCAT server at $CATALINA_HOME/WEB-INF/classes/resources/database/templates/.
It is often useful, when working on a template, to place it directly into the Tomcat server so that no recompile/deploy step is needed. Note, however, that templates placed directly into $CATALINA_HOME will be lost whenever Tomcat is restarted.
Our simple DB_only template will query for the unique countries that contributed data to the insitu_demo_2 dataset.
In the appropriate directory, create a file named DB_only.vm with the following content:
#set($table=$las_backendrequest.getDatabaseProperty("db_table"))
#set($region=$las_backendrequest.getRegionAsConstraint())
/* Simple query to identify countries contributing data within a region */
SELECT DISTINCT(country) FROM $table WHERE $region
output template
The output template should be located in $LAS_HOME/WebContent/productserver/templates/DB_only.vm. When LAS is compiled and deployed, this directory will be expanded in the TOMCAT server at $CATALINA_HOME/webapps/$LAS_NAME/productserver/templates/. The templates can also be placed directly into Tomcat with the same reservations.
We'll set up an output template that uses both the default stylesheet and one of our own creation so we can see the difference.
In the appropriate directory, create a file named DB_only.vm with the following content:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- LAS SERVER OK -->
<head>
<title>LAS Output -- $las_config.getTitle()</title>
</head>
<body>
<h1>getResultAsTable("webrowset")</h1>
$las_response.getResultAsTable("webrowset")
<hr>
<h1>getResultTransformedByXSL("webrowset","DB_only.xsl")</h1>
$las_response.getResultTransformedByXSL("webrowset","DB_only.xsl")
</body>
</html>
XSLT
The eXtensible Style Language Transforms (XSLT) is an XML based language used for the transformation of XML documents like the '~webrowset.xml' file output by the LAS database service.
LAS ships with the following default stylesheet: $LAS_HOME/WEB-INF/classes/resources/productserver/stylesheets/webrowsetToTable.xsl
This is the stylesheet that is applied in the following line in the Velocity output template:
$las_response.getResultAsTable("webrowset")To apply our own stylesheet we must use
$las_response.getResultTransformedByXSL("webrowset","DB_only.xsl")To create the stylesheet, first copy the contents of webrowsetToTable.xsl to file named DB_only.xsl. Customizing DB_only.xsl is left as an exercise for the reader.
Access to the WebRowSet Java Object
The LAS product server will place a copy of the WebRowSet object into the context of the output template so you can manipulate this object directly to prepare your output for display. To access the object in the Velocity template use $las_webrowset. The webrowset.vm is an example template that uses this object to loop through a set of results and display them in a table.