Container Creation

new()

 # Give the user what they requested
 ->new({ tqx => $q->param('tqx') });

 # Be conscientious and pass in contents of X-DataSource-Auth
 ->new({
    tqx => $q->param('tqx'),
    datasource_auth => $q->header('X-DataSource-Auth')
 });

 # Set it by hand...
 ->new({ reqId => 3, out => 'json', sig => 'deadbeef' });

"new()" will set the following object attributes based on this, all based on the Request Format linked above:

"reqId" - allegedy required, and required to be an int. In fact, the documentation reveals that if you leave it blank, it should default to 0.

"version" - allows the calling client to specify the version of the API it wishes to use. Please note this module currently ONLY CLAIMS TO support 0.06. If any other version is passed, a "warning" message will be added, but we will try to continue anyway - see "Adding Messages" below.

"sig" - allows the client to specify an identifier for the last request retrieved, so it's not redownloaded. If the "sig" matches the data we were about to send, we'll follow the documentation, and add an "error" message, as per "Adding Messages" below.

"out" - output format. This defaults to "json", although whether JSON or JSONP is returned depends on if "X-DataSource-Auth" has been included - see the Google docs. Other formats are theoretically provided for, but this version of the software doesn't support them, and will add an "error" message (at serialization time) if they're specified.

"responseHandler" - in the case of our outputting JSONP, we wrap our payload in a function call to this method name. It defaults to "google.visualization.Query.setResponse". An effort is made to strip out unsafe characters.

"outFileName" - certain output formats allow us to specify that the data should be returned as a named file. This is simply ignored in this version.

"datasource_auth" - this does NOT correspond to the normal request object - instead it's used to capture the "X-DataSource-Auth" header, whose presence will cause us to output JSON instead of using the "responseHandler".

Adding Messages

Messages are errors or warnings that need to be passed back to the client, but they also have potential to change the rest of the data payload. The following algorithm is used:

 1. Have any error messages been added? If so, discard all but the first, set
    the response status to 'error', and discard the DataTable and all warning
    messages. We discard all the other messages (error and warning) to prevent
    malicious data discovery.

 2. An integrity check is run on the attributes that have been set. We check the
    attributes listed above, and generate any needed messages from those. If we
    generate any error messages, step 1 is rerun.

 2. Have any warning messages been added? If so, set the response status to
    'warning'. Include all warning messages and the DataTable in the response.

 3. If there are no warning or error messages, set the response status to 'ok',
    and include the DataTable in the response.

When messages are described as discarded, they are not included in the returned "body" - they're still available to the developer in the returned "messages". See the documentation on "serialize" below.

add_message()

Messages are added using the "add_message" method:

 $datasource->add_message({
    type    => 'error',         # Required. Can also be 'warning'
    reason  => 'access_denied', # Required. See Google Docs for allowed options
    message => 'Unauthorized User', # Optional
    detailed_message => 'Please login to use the service' # Optional
 });

datatable

The datatable is added via the "datatable" method:

 $datasource->datatable( $datatable_object );

and must be a Data::Google::Visualization::DataTable object. If you know you've already added an "error" message, you don't need to set this - it won't be checked.

Generating Output

To kick the whole circus off, call "serialize".

serialize

 my ( $headers, $body, $messages ) = $datasource->serialize();

Serialize accepts no arguments, and does not change the state of the underlying object. It returns:

headers

An arrayref or arrayrefs, which in this version of this module will always be:

 [[ 'Content-Type', 'text/javascript' ]]

However, don't use that knowledge, as future versions will definitely add new headers, based on other user options - "Content-Disposition", for starters. You should return all received headers to the user. As future versions will allow returning of different data types, you must allow control of "Content-Type" and "Content-Disposition" to fall to this module in their entirity.

body

A JSON-like string containing the response. Google JSON is not real JSON (see the continually linked documentation), and what's more, this may well be JSONP instead. This string will come back UTF-8 encoded, so make sure whatever you're serving this with doesn't re-encode that.

messages

 {
    errors => [
        {
            reason  => 'not_modified',
            message => 'Data not modified'
        }
    ]
    warnings => []
 }

A hashref of arrayrefs containing all messages raised. You must not show this to the user - it's purely for your own debugging. When we talk about messages being discarded in the "Adding Messages" section, they will turn up here instead. DO NOT MAKE DECISIONS ABOUT WHAT TO RETURN TO THE USER BY POKING THROUGH THIS DATA. The "not_modified" error is a great example of why not - it is not an error for the user, and the user has to act a certain way on getting it - it's expected in the normal course of use.