# Implementation Tips

This section covers some tips that
will help you write more complex implementations of the library:

- [Using Your Own Servlet](https://developers.google.com/chart/interactive/docs/dev/dsl_key_concepts#servlet)
- [Defining Capabilities](https://developers.google.com/chart/interactive/docs/dev/dsl_key_concepts#capabilities)
- [Customizing the Flow of Events](https://developers.google.com/chart/interactive/docs/dev/dsl_key_concepts#events)
- [Passing Parameters to `DataTableGenerator.generateDataTable`](https://developers.google.com/chart/interactive/docs/dev/dsl_key_concepts#params)
- [Implementing a Non-servlet Data Source](https://developers.google.com/chart/interactive/docs/dev/dsl_key_concepts#nonservlet)

## Using Your Own Servlet

The simplest data source implementations inherit from the library's `DataSourceServlet` class.
To inherit from a class other than `DataSourceServlet`, implement
a data source as follows:

1. Implement the `DataTableGenerator` interface and override `getCapabilities()` and `generateDataTable()`.
2. Call `DataSourceHelper.executeDataSourceServletFlow()` from within your servlet's code to run the data source flow. This method takes the following parameters :
   - An `HttpServletRequest` object.
   - An `HttpServletResponse` object.
   - Your implementation of the `DataTableGenerator` interface from step 1 above.
   - A boolean to specify restricted or unrestricted access mode.

For example, if you want to inherit your servlet from another servlet
class, called `AuthServlet` that provides built-in authentication,
you can rewrite the `SimpleServletExample` to inherit `AuthServlet` rather
than `DataSourceServlet` as follows:

1. Implement the `DataTableGenerator` interface.
2. Move `generateDataTable()` from your `DataSourceServlet` implementation to your `DataTableGenerator` implementation.
3. Override `getCapabilities()` in your `DataTableGenerator` implementation to return `Capabilities.None`.
4. Call `DataSourceHelper.executeDataSourceServletFlow()` from within your servlet code (`doGet()` or `doPost()`), and pass your `DataTableGenerator` implementation. This method runs the entire flow of the datasource, including rendering the data source results into the servlet response.

You can use the same technique if you are using a servlet framework
in which you normally inherit an abstract class provided by the framework.
For example, if you are using WebWork you might want to inherit the `ActionSupport` class.

## Defining Capabilities

If your data store contains a large amount of data, and you want
to increase the efficiency of your data source, you can use the querying
capabilities of your data store. For example, suppose that your data store
is a database, and the database has a large number of columns. If a visualization
requests only a few of those columns, then running a `SELECT` operation
within the database is more efficient than retrieving all the columns and
using the library's querying capabilities to perform the `SELECT`.
To implement `SELECT` capabilities, you write code
to run a `SELECT` operation within the database and to return
a data table.

Use the `Capabilities` enum
to define the querying capabilities that your code
provides. Available options are:

- `NONE`: the default, your code provides no query operations.
- `SQL`: your code provides SQL query operations.
- `SORT_AND_PAGINATION`: your code provides both sort and pagination query operations.
- `SELECT`: your code provides a select operation.
- `ALL`: your code provides `SQL`, `SORT_AND_PAGINATION`, and `SELECT` operations.

**Note**: In all cases the library handles
any query operations that are not provided by your code.

To implement a capability other than `NONE`, override `Capabilities.getCapabilities()`and
implement `DataTable.generateDataTable()` to query the data
store and return a data table.

Three of the examples illustrate how to implement capabilities: `AdvancedExampleServlet`,
`AdvancedExampleServlet2`, and `SqlDataSourceServlet`.
All are in the `example` package. `AdvancedExampleServlet2` is
discussed in [Defining Capabilities and the Flow of Events](https://developers.google.com/chart/interactive/docs/dev/dsl_httpservlet).

## Customizing the Flow of Events

The default flow of events is defined in `DataSourceHelper.executeDataSourceServletFlow`.
The default flow is as follows:

1. Extract and parse query parameters.
2. For restricted access mode only, verify that the request originates from the same domain as the servlet.
3. Parse the request to create two query objects: the data source query and the completion query. Pass the data source query to your implementation of `generateDataTable()`.
4. Your implementation of `generateDataTable()` generates a data table.
5. Run the completion query on the data table generated in step 5.
6. Render the data table into the format specified by the visualization and set the servlet response.

To specify your own flow of events, call the
helper functions in `datasource.DataSourceHelper`. See
[Defining Capabilities and the Flow of Events](https://developers.google.com/chart/interactive/docs/dev/dsl_httpservlet) for an example
implementation.

## Passing Parameters to `DataTableGenerator.generateDataTable`

You can use the `HttpServletRequest.setAttribute` to pass
data that is not part of a query or `HttpServletRequest` object
to `DataTableGenerator.generateDataTable`. Example code is provided
below.

In your servlet's code, put the object you want to pass into the `HttpServletRequest` as
follows:

```
request.setAttribute("my_object_name", myObject);
DataSourceHelper.executeDataSourceServletFlow(request, response, dataTableGenerator);
```

In your `dataTableGenerator` interface implementation, get the object from the `HttpServletRequest` as follows:

```
public DataTable generateDataTable(Query query, HttpServletRequest request){
  Object myObject = request.getAttribute("my_object_name"); 
  // Add your code to manipulate myObject here 
} 
```

## Implementing a Non-servlet
Data Source

If you implement the library without using a servlet, you can
use only those classes and helper functions that do not require
a servlet environment. These include the `Query` and `DataTable`
classes and some of the `DataSourceHelper` functions
such as `parseQuery`, `applyQuery`, `validateQuery` and `splitQuery`.
You can use these classes and functions to do the following:

- Parse a visualization query.
- Split the query into a data source query and a completion query.
- Run the completion query to generate a data table.
- Return the data table to the visualization in `HTML`, `CSV`, or `JSON` format.