Getting Started with Data Sources

This section introduces SimpleExampleServlet, which is the simplest example implementation of a data source that is provided with the library. This section also provides step-by-step instructions on how to run and test SimpleExampleServlet.

Introducing SimpleExampleServlet

The SimpleExampleServlet class is located in the examples package. This class provides an example of the simplest implementation of a data source. SimpleExampleServlet inherits from DataSourceServlet, implements generateDataTable(), and must be run within a servlet container.

A snippet of SimpleExampleServlet is provided below. The generateDataTable function exposes data to the library. This function creates a data table description, defines the data table columns, and populates the data table with data. The library handles all other actions required to return the data table to the querying visualization.

// This example extends DataSourceServlet
public class SimpleExampleServlet extends DataSourceServlet {

  @Override
  public DataTable generateDataTable(Query query, HttpServletRequest request) {
    // Create a data table,
    DataTable data = new DataTable();
    ArrayList cd = new ArrayList();
    cd.add(new ColumnDescription("name", ValueType.TEXT, "Animal name"));
    cd.add(new ColumnDescription("link", ValueType.TEXT, "Link to wikipedia"));
    cd.add(new ColumnDescription("population", ValueType.NUMBER, "Population size"));
    cd.add(new ColumnDescription("vegeterian", ValueType.BOOLEAN, "Vegetarian?"));

    data.addColumns(cd);

    // Fill the data table.
    try {
      data.addRowFromValues("Aye-aye", "http://en.wikipedia.org/wiki/Aye-aye", 100, true);
      data.addRowFromValues("Sloth", "http://en.wikipedia.org/wiki/Sloth", 300, true);
      data.addRowFromValues("Leopard", "http://en.wikipedia.org/wiki/Leopard", 50, false);
      data.addRowFromValues("Tiger", "http://en.wikipedia.org/wiki/Tiger", 80, false);
    } catch (TypeMismatchException e) {
      System.out.println("Invalid type!");
    }
    return data;
  }
}

Running and testing SimpleExampleServlet

This section provides instructions on how to run and test SimpleExampleServlet.

If you haven't already done so, see the Installation section for information about prerequisites, and instructions on how to download and build the library. Make sure you install a web server that also functions as a servlet container, such as Apache Tomcat, if you do not already have one on your system. The instructions in this section are specific to Apache Tomcat on a Windows system.

To run and test SimpleExampleServlet, create a web application that runs the SimpleExampleServlet data source, then run an example web page with a visualization showing data queried from the data source. This is described in the following sections:

Creating a Web Application on Apache Tomcat

Follow or adapt the instructions below to create a web application on Apache Tomcat. These instructions are specific to Apache Tomcat on a Windows system:

  1. Navigate to the directory in which you installed Tomcat. This is written in this document as <tomcat_home>.
     
  2. Navigate to the webapps subdirectory.
     
  3. Create a subdirectory called myWebApp.
     
  4. Change to the subdirectory you have just created and create another subdirectory called WEB-INF.
     
  5. Change to the WEB-INF subdirectory and create another subdirectory called lib.
    The full path should be <tomcat_home>/webapps/myWebApp/WEB-INF/lib.
     
  6. Copy web.xml from <data_source_library_install>/examples/src/html to the WEB-INF directory. Where <data_source_library_install> is the directory in which you installed the data source library. The following lines in web.xml define and map SimpleExampleServlet:
    <servlet>
  <servlet-name>My Servlet</servlet-name>
  <description>My servlet description.</description>
  <servlet-class>SimpleExampleServlet</servlet-class>
</servlet>

<servlet-mapping>
  <servlet-name>My Servlet</servlet-name>
  <url-pattern>/simpleexample</url-pattern>
</servlet-mapping>
  7. Navigate to the directory in which you installed the data source library. This is written in this document as <data_source_library_install>.
     
  8. Copy all the dependency packages to <tomcat_home>/webapps/myWebApp/WEB-INF/lib. The packages are installed in <data_source_library_install>/lib, unless you put them in a different directory.
     
  9. If you have built the library yourself, copy visualization-datasource-1.0.2.jar and visualization-datasource-examples.jar
    from <data_source_library_install>/build
    to <tomcat_home>/webapps/myWebApp/WEB-INF/lib.

    If you have unzipped the zip file, copy visualization-datasource-1.0.2.jar and visualization-datasource-examples.jar
    from <data_source_library_install>
    to <tomcat_home>/webapps/myWebApp/WEB-INF/lib.
    Note that the version number in the jar file name may vary depending on the latest version number.
     
  10. Start Tomcat, or restart Tomcat if it is already running.
     
  11. Click the following link:

    http://localhost:8080/myWebApp/simpleexample

    The screen displays 6-7 lines of text, depending on your screen width.
    The text begins with google.visualization.Query.setResponse
    and ends with /Tiger'},{v:80.0},{v:false}]}]}});

    This is the data that is returned by your data source to a querying visualization.

Using a Visualization to View the Data

The getting_started.html file in the <data_source_library_install>/examples/src/html directory can be used to view a visualization of the data. The following line, taken from getting_started.html, specifies the servlet to use. The servlet mapping was set up in step 8 of Creating a Web Application on Apache Tomcat.

var query = new google.visualization.Query('simpleexample');

For more information on how to specify a visualization and use the query language, see Using Charts and the Query Language Reference.

Follow, or adapt, the instructions below to view a visualization of the data provided by the data source:

  1. Copy the getting_started.html file from the <data_source_library_install>/examples/src/html directory
    to the <tomcat_home>/webapps/myWebApp/ directory.
     
  2. Click the following link http://localhost:8080/myWebApp/getting_started.html, you should see the following:
     


    That's it! You have set up your first data source.

Next Steps

The next example is described in the Using an External Data Store section. Alternatively you can return to the Introduction, or explore the following links: