Handling Security, Errors, Warnings, and Logging

This section covers the following topics:

• Security
• Errors and Warnings
• Logging

Security

A data source can operate in one of two access modes as follows:

• In restricted access mode, which is the default, a data source serves only those requests that originate from the same domain as that in which the data source is located. Restricted mode prevents cross-site request forgery (XSRF) attacks and so is more secure than unrestricted access mode. Because the data source library provides an interface for returning data only, and not for changing state or data on the server side, only XSRF attacks that attempt to steal data are possible. To make your data source secure against attempts to steal data, restricted mode must be used in conjunction with cookie-based authentication. The way that you authenticate users depends on your environment and implementation.

• In unrestricted access mode, a data source serves all requests regardless of their origin. A data source that runs in unrestricted mode can be protected by cookie-based authentication, but note that the data source will be vulnerable to XSRF attacks. Use unrestricted mode if visualizations on web pages outside the data source's domain need to access the data source, or if the data is in the public domain and so does not need to be protected.

A visualization request can specify a response format of JSON, CSV, or HTML. The response format determines the format in which a data source returns a data table. Because CSV and HTML formats are not vulnerable to XSRF attacks, these can be accessed from other domains, even in restricted mode.

To specify unrestricted mode, override isRestrictedAccessMode() as follows:

  @Override
  protected boolean isRestrictedAccessMode() {
    return false;
  }

For simplicity, all the examples provided with the library run in unrestricted access mode.

Errors and Warnings

When it is not possible, or desirable, to return a valid data table, the library throws a DataSourceException. For example if the user cannot be authenticated. The library throws these exceptions when errors prevent it from creating a data table. You may want to throw exceptions in situations unique to your data source. If so, create your own error exception types by inheriting from the DataSourceException class. You can also throw the DataSourceException class directly.

The DataSourceException class is located in the base package, it takes the following parameters:

• ReasonType 
  This parameter is mandatory. Available reason types are defined in the ReasonType enum. If none of the available reason types are suitable, you can use Other or Internal.
   
• MessageToUser 
  This parameter defines the text of the error message. In most cases, it is displayed to the user as a tooltip, so it is important not to include technical or confidential information.

You can use the set of helper functions in datasource.DataSourceHelper to handle errors. In this case call two functions both with same name of setErrorServletResponse to take a DataSourceException and set an error on the data servlet response. One of these functions takes a data source request, the other takes an HttpServlet request and is used in cases where there is a failure to create a DataSourceRequest. An example implementation is provided in Defining Capabilities and the Flow of Events.

If it is not possible to return a data table, the library returns an error. If it is possible to return a data table, but there is a problem to report, the library returns a warning together with the data table. For example, the library creates a warning in the following situations:

• if a querying visualization provides a LIMIT that results in truncated data.
• if a querying visualization requests an invalid formatting pattern in a FORMAT clause.

To add your own warning, create an instance of base.Warning and add it to your data table using the addWarning() method.

Logging

The library uses Jakarta commons logging. Jakarta commons logging can be used with most common logging systems that you might already have in place. You might need to write an adapter if your logging system is non-standard. For more details, see the Jakarta commons logging home page.

When an exception is thrown information is sent to the log. The way that you access the log depends on the logging system you use.