com.google.visualization.datasource
Class DataSourceHelper

java.lang.Object
  com.google.visualization.datasource.DataSourceHelper

public class DataSourceHelper
extends java.lang.Object

A Helper class providing convenience functions for serving data source requests. The class enables replying to a data source request with a single method which encompasses all the request processing - executeDataSourceServletFlow. To enable users to change the default flow all the basic operations (such as: query parsing, data table creation, query execution, and response creation) are also exposed.

Author:

Yaniv S.

Method Summary

static DataTable	applyQuery(Query query, DataTable dataTable, com.ibm.icu.util.ULocale locale) Applies the given Query on the given DataTable and returns the resulting DataTable.
static void	executeDataSourceServletFlow(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, DataTableGenerator dtGenerator) Executes the default data source servlet flow.
static void	executeDataSourceServletFlow(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, DataTableGenerator dtGenerator, boolean isRestrictedAccessMode) Executes the default data source servlet flow.
static java.lang.String	generateErrorResponse(DataSourceException dse, DataSourceRequest dsRequest) Generates an error response string for the given DataSourceException.
static java.lang.String	generateErrorResponse(ResponseStatus responseStatus, DataSourceRequest dsRequest) Generates an error response string for the given ResponseStatus.
static java.lang.String	generateResponse(DataTable dataTable, DataSourceRequest dataSourceRequest) Generates a string response for the given DataTable.
static com.ibm.icu.util.ULocale	getLocaleFromRequest(javax.servlet.http.HttpServletRequest req) Get the locale from the given request.
static Query	parseQuery(java.lang.String queryString) Parses a query string (e.g., 'select A,B pivot B') and creates a Query object.
static void	setServletErrorResponse(DataSourceException dataSourceException, DataSourceRequest dataSourceRequest, javax.servlet.http.HttpServletResponse res) Sets the HTTP servlet response in case of an error.
static void	setServletErrorResponse(DataSourceException dataSourceException, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Sets the HTTP servlet response in case of an error.
static void	setServletErrorResponse(ResponseStatus responseStatus, DataSourceRequest dataSourceRequest, javax.servlet.http.HttpServletResponse res) Sets the HTTP servlet response in case of an error.
static void	setServletResponse(DataTable dataTable, DataSourceRequest dataSourceRequest, javax.servlet.http.HttpServletResponse res) Sets the response on the HttpServletResponse by creating a response message for the given DataTable and sets it on the HttpServletResponse.
static void	setServletResponse(java.lang.String responseMessage, DataSourceRequest dataSourceRequest, javax.servlet.http.HttpServletResponse res) Sets the given response string on the HttpServletResponse.
static QueryPair	splitQuery(Query query, Capabilities capabilities) Splits the Query object into two queries according to the declared data source capabilities: data source query and completion query.
static void	validateQueryAgainstColumnStructure(Query query, DataTable dataTable) Checks that the query is valid against the structure of the data table.
static void	verifyAccessApproved(DataSourceRequest req) Checks that the given request is sent from the same domain as that of the server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

executeDataSourceServletFlow

public static void executeDataSourceServletFlow(javax.servlet.http.HttpServletRequest req,
                                                javax.servlet.http.HttpServletResponse resp,
                                                DataTableGenerator dtGenerator)
                                         throws java.io.IOException

Executes the default data source servlet flow. Assumes restricted access mode.

Parameters:

req - The HttpServletRequest.

resp - The HttpServletResponse.

dtGenerator - An implementation of DataTableGenerator interface.

Throws:

java.io.IOException - In case of I/O errors.

See Also:

executeDataSourceServletFlow(HttpServletRequest req, HttpServletResponse resp, DataTableGenerator dtGenerator, boolean isRestrictedAccessMode)

executeDataSourceServletFlow

public static void executeDataSourceServletFlow(javax.servlet.http.HttpServletRequest req,
                                                javax.servlet.http.HttpServletResponse resp,
                                                DataTableGenerator dtGenerator,
                                                boolean isRestrictedAccessMode)
                                         throws java.io.IOException

Executes the default data source servlet flow. The default flow is as follows: - Parse the request parameters. - Verify access is approved (for restricted access mode only). - Split the query. - Generate the data-table using the data-table generator. - Run the completion query. - Set the servlet response. Usage note : this function executes the same flow provided to Servlets that inherit DataSourceServlet. Use this function when the default flow is required but DataSourceServlet cannot be inherited (e.g., your servlet already inherits from anther class, or not in a servlet context).

Parameters:

req - The HttpServletRequest.

resp - The HttpServletResponse.

dtGenerator - An implementation of DataTableGenerator interface.

isRestrictedAccessMode - Indicates whether the server should serve trusted domains only. Currently this translates to serving only requests from the same domain.

Throws:

java.io.IOException - In case of I/O errors.

verifyAccessApproved

public static void verifyAccessApproved(DataSourceRequest req)
                                 throws DataSourceException

Checks that the given request is sent from the same domain as that of the server.

Parameters:

req - The data source request.

Throws:

DataSourceException - If the access for this request is denied.

setServletResponse

public static void setServletResponse(DataTable dataTable,
                                      DataSourceRequest dataSourceRequest,
                                      javax.servlet.http.HttpServletResponse res)
                               throws java.io.IOException

Sets the response on the HttpServletResponse by creating a response message for the given DataTable and sets it on the HttpServletResponse.

Parameters:

dataTable - The data table.

dataSourceRequest - The data source request.

res - The http servlet response.

Throws:

java.io.IOException - In case an error happened trying to write the response to the servlet.

setServletResponse

public static void setServletResponse(java.lang.String responseMessage,
                                      DataSourceRequest dataSourceRequest,
                                      javax.servlet.http.HttpServletResponse res)
                               throws java.io.IOException

Sets the given response string on the HttpServletResponse.

Parameters:

responseMessage - The response message.

dataSourceRequest - The data source request.

res - The HTTP response.

Throws:

java.io.IOException - In case an error happened trying to write to the servlet response.

setServletErrorResponse

public static void setServletErrorResponse(DataSourceException dataSourceException,
                                           DataSourceRequest dataSourceRequest,
                                           javax.servlet.http.HttpServletResponse res)
                                    throws java.io.IOException

Sets the HTTP servlet response in case of an error.

Parameters:

dataSourceException - The data source exception.

dataSourceRequest - The data source request.

res - The http servlet response.

Throws:

java.io.IOException - In case an error happened trying to write the response to the servlet.

setServletErrorResponse

public static void setServletErrorResponse(ResponseStatus responseStatus,
                                           DataSourceRequest dataSourceRequest,
                                           javax.servlet.http.HttpServletResponse res)
                                    throws java.io.IOException

Sets the HTTP servlet response in case of an error.

Parameters:

responseStatus - The response status.

dataSourceRequest - The data source request.

res - The http servlet response.

Throws:

java.io.IOException - In case an error happened trying to write the response to the servlet.

setServletErrorResponse

public static void setServletErrorResponse(DataSourceException dataSourceException,
                                           javax.servlet.http.HttpServletRequest req,
                                           javax.servlet.http.HttpServletResponse res)
                                    throws java.io.IOException

Sets the HTTP servlet response in case of an error. Gets an HttpRequest parameter instead of a DataSourceRequest. Use this when DataSourceRequest is not available, for example, if DataSourceRequest constructor failed.

Parameters:

dataSourceException - The data source exception.

req - The http servlet request.

res - The http servlet response.

Throws:

java.io.IOException - In case an error happened trying to write the response to the servlet.

generateResponse

public static java.lang.String generateResponse(DataTable dataTable,
                                                DataSourceRequest dataSourceRequest)

Generates a string response for the given DataTable.

Parameters:

dataTable - The data table.

dataSourceRequest - The data source request.

Returns:

The response string.

generateErrorResponse

public static java.lang.String generateErrorResponse(DataSourceException dse,
                                                     DataSourceRequest dsRequest)
                                              throws java.io.IOException

Generates an error response string for the given DataSourceException. Receives an exception, and renders it to an error response according to the OutputType specified in the DataSourceRequest. Note: modifies the response status to make links clickable in cases where the reason type is ReasonType.USER_NOT_AUTHENTICATED. If this is not required call generateErrorResponse directly with a ResponseStatus.

Parameters:

dse - The data source exception.

dsRequest - The DataSourceRequest.

Returns:

The error response string.

Throws:

java.io.IOException - In case if I/O errors.

generateErrorResponse

public static java.lang.String generateErrorResponse(ResponseStatus responseStatus,
                                                     DataSourceRequest dsRequest)
                                              throws java.io.IOException

Generates an error response string for the given ResponseStatus. Render the ResponseStatus to an error response according to the OutputType specified in the DataSourceRequest.

Parameters:

responseStatus - The response status.

dsRequest - The DataSourceRequest.

Returns:

The error response string.

Throws:

java.io.IOException - In case if I/O errors.

parseQuery

public static Query parseQuery(java.lang.String queryString)
                        throws InvalidQueryException

Parses a query string (e.g., 'select A,B pivot B') and creates a Query object. Throws an exception if the query is invalid.

Parameters:

queryString - The query string.

Returns:

The parsed query object.

Throws:

InvalidQueryException - If the query is invalid.

applyQuery

public static DataTable applyQuery(Query query,
                                   DataTable dataTable,
                                   com.ibm.icu.util.ULocale locale)
                            throws InvalidQueryException,
                                   DataSourceException

Applies the given Query on the given DataTable and returns the resulting DataTable. This method may change the given DataTable.

Parameters:

query - The query object.

dataTable - The data table on which to apply the query.

locale - The user locale for the current request.

Returns:

The data table result of the query execution over the given data table.

Throws:

InvalidQueryException - If the query is invalid.

DataSourceException - If the data source cannot execute the query.

splitQuery

public static QueryPair splitQuery(Query query,
                                   Capabilities capabilities)
                            throws DataSourceException

Splits the Query object into two queries according to the declared data source capabilities: data source query and completion query. The data source query is executed first by the data source itself. Afterward, the QueryEngine executes the completion query over the resulting data table.

Parameters:

query - The query to split.

capabilities - The declared capabilities of the data source.

Returns:

A QueryPair object.

Throws:

DataSourceException - If the query cannot be split.

validateQueryAgainstColumnStructure

public static void validateQueryAgainstColumnStructure(Query query,
                                                       DataTable dataTable)
                                                throws InvalidQueryException

Checks that the query is valid against the structure of the data table. A query is invalid if:

1. The query references column ids that don't exist in the data table.
2. The query contains calculated columns operations (i.e., scalar function, aggregations) that do not match the relevant columns type.

Note: does NOT validate the query itself, i.e. errors like "SELECT a, a" or "SELECT a GROUP BY a" will not be caught. These kind of errors should be checked elsewhere (preferably by the Query.validate() method).

Parameters:

query - The query to check for validity.

dataTable - The data table against which to validate. Only the columns are used.

Throws:

InvalidQueryException - Thrown if the query is found to be invalid against the given data table.

getLocaleFromRequest

public static com.ibm.icu.util.ULocale getLocaleFromRequest(javax.servlet.http.HttpServletRequest req)

Get the locale from the given request.

Parameters:

req - The http serlvet request

Returns:

The locale for the given request.