Viewers

The TDS lists the set of known viewers for a direct dataset the bottom of its HTML web page. You can get your own viewer listed by creating a Java class that tells the TDS what datasets are viewable, and what HTML fragment to include.

Create a Viewer implementation class

Your class must implement the thredds.servlet.Viewer interface:

public interface Viewer {
1) public boolean isViewable( thredds.catalog.InvDatasetImpl dataset);
2) public String getViewerLinkHtml( InvDatasetImpl ds, HttpServletRequest req);
}

1. Your class is passed a thredds.catalog.InvDatasetImpl object, and it returns true if it is viewable by your viewer.
2. Your class is passed a viewable thredds.catalog.InvDatasetImpl, and it must return a well-formed HTML string that has an href link in it.

Example:

package my.package;
include thredds.catalog.*;


public class IDV implements Viewer {

 public boolean isViewable( InvDatasetImpl ds) {
   InvAccess access = ds.getAccess(ServiceType.DODS);
   if (access == null) access = ds.getAccess(ServiceType.OPENDAP);
1) if (access == null) return false;

2) return (ds.getDataType() == DataType.GRID);
 }

 public String getViewerLinkHtml( InvDatasetImpl ds, HttpServletRequest req) {
   InvAccess access = ds.getAccess(ServiceType.DODS);
3) if (access == null) access = ds.getAccess(ServiceType.OPENDAP);

4) URI dataURI = access.getStandardUri();
   try {
     URI base = new URI( req.getRequestURL().toString());
5)   dataURI = base.resolve( dataURI);
   } catch (URISyntaxException e) {
     log.error("Resolve URL with "+req.getRequestURL(),e);
   }

6) return "<a href='/thredds/view/idv.jnlp?url="+dataURI.toString()+"'>Integrated Data Viewer (IDV) (webstart)</a>";
 }

1. Requires there to be OPeNDAP access for the dataset.
2. Requires the dataset to be of DataType.GRID.
3. Get the OPeNDAP access object for the dataset.
4. Get the access URI.
5. Resolves the access URI against the request, which turns it into an absolute URI
6. Forms the HTML string to be placed on the dataset's TDS web page. Note that is has an href embedded in it, which will be displayed in this example as:

   Integrated Data Viewer (IDV) (webstart)

Creating the Viewer Link

Referencing an external URL

If the viewer you want to reference is not part of the TDS, just make the href absolute, eg:

 <a href='http://my.server/viewer?url=http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2'>My Server</a>

In this example, the server would see the OPeNDAP data access URL and remotely read it.

Returning a JNLP file

The IDV example returns a JNLP file, which allows the IDV client program to be automatically started through Java Webstart. If you have a webstart-enabled viewer, you can also get the TDS to return your own JNLP file. To do so:

1. The returned URL should start with /thredds/view/
2. The remaining part of the URL (before the ?) is the name of a JNLP template file in the ${tomcat_home}/content/thredds/views/ directory.
3. The JNLP template file is processed in the following way:
   1. Each parameter in the URL is read as a name=value pair (in the example, there is one parameter, whose name is url and value is http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2).
   2. The JNLP template file is searched for strings of the form {name}, and the corresponding value is substituted into it (in the example, all strings of the form {url} would be replaced by http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2).
4. Once the JNLP template file is processed, it is sent as the response to the user clicking on your link. If they have webstart installed, the application named in the JNLP file is downloaded (if necessary) and started up.

Example:

This is an approximately what is used in the IDV JNLP file. Note that the {url} string on the boldface line is replaced by the actual data access URL. This will create a command line argument -data type:opendap.grid:http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2 and pass it to the IDV application.

<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP File for Integrated Data Viewer -->
<jnlp spec="1.0+" codebase="http://www.unidata.ucar.edu/software/idv/webstart/">
  <information>
    <title>Integrated Data Viewer</title>
    <vendor>Unidata</vendor>
    <homepage href="http://www.unidata.ucar.edu/software/idv/index.html"/>
    <description>Integrated Data Viewer(IDV)</description>
    <description kind="short">A tool for geoscientific analysis and visualization.
    </description>
    <icon href="IDV/idv.gif"/>
    <offline-allowed/>
  </information>

  <security>
   <all-permissions/>
  </security>

  <resources>
   <j2se version="1.4+" max-heap-size="512m"/>
   <jar href="IDV/idv.jar"/>
   <extension name="IDV Base" href="IDV/idvbase.jnlp"/>
  </resources>
  <application-desc main-class="ucar.unidata.idv.DefaultIdv">
   <argument>-data</argument>
   <argument>type:opendap.grid:{url}</argument>
  </application-desc>

</jnlp>

Loading your class at runtime

You must place your Viewer class into the ${tomcat_home}/webapps/thredds/WEB-INF/lib or classes directory. (Previous instructions to place it into the ${tomcat_home}/shared directory doesn't work, because of classloader problems).

Then tell the TDS to load it by adding a line to the ${tomcat_home}/content/thredds/threddsConfig.xml file, for example:

  <viewer>my.package.MyViewer</viewer>

This document is maintained by John Caron and was last updated on Jan 31, 2007