| Version 1 (modified by joe, 19 years ago) (diff) |
|---|
Data Provider Inheritable
The following is rendered from the POD (Plain Old Documentation) inside the VSO Data Provider Inheritable.
The inheritable is written in Perl, and uses SOAP::Lite.
Please refer to the module itself for the most up-to-date (and most likely, better formatted) documentation, and example code.
NAME
Physics::Solar::VSO::DataProvider? - Inheritable Perl object for Virtual Solar Observatory Data Providers.
SYNOPSIS
use VSO::DataProvider;
@ISA = qw (VSO::DataProvider);
sub _ProviderID { return $id; }
sub _Search { ... }
sub _SupportedDataMethods { ... }
sub _ProcessDataRequest { ... }
DESCRIPTION
VSO::DataProvider? is an inheritable to allow organizations with archives of solar physics data to more easily create a web service to participate in the Virtual Solar Observatory project.
For more information about this project, please visit the VSO website:
USAGE
The VSO::DataProvider? module contains functions to handle the encoding and decoding of VSO messages. VSO::DataProvider? will perform some basic sanity checks on the message, and then call specific functons to handle the low-level processing, and to actually interact with the data archive.
Required Functions
_ProviderID()
This function should return a string containing this data provider's Provider ID.
For information about obtaining a Provider ID, please visit the VSO website:
_Search()
The _Search function handles the main processing for a VSO Query.
The input is a hashref containing the search parameters. The output should be either a VSO error message, or a VSO query response.
Two helper functions are provided to handle the encapsulation of the response, _ThrowError() and _PackageResults()
Please see the VSO website for an explaination of the formatting of a search request:
_SupportedDataMethods()
This function should return a reference to a hash of arrays, that contains the list of data transfer methods that the Data Provider supports, and the list of required information to complete the transaction:
sub _SupportedDataMethods {
return {
'TRANSFER_METHOD' => [ qw( INFO KEYWORD LIST ) ],
'TRANSFER_METHOD2' => [ qw( INFO KEYWORD LIST ) ],
};
}
See the VSO website for information about the current list of defined transfer methods and information keywords, and for information about adding defining new methods or keywords:
_ProcessDataRequest()
The _ProcessDataRequest function handles the main processing for a VSO GetData? request.
The input is a hashref containing the search parameters. The output should be either a VSO error message, or a VSO query response.
Two helper functions are provided to handle the encapsulation of the response, _ThrowError() and _PackageData()
Please see the VSO website for an explaination of the formatting of a GetData? request:
Useful Functions
The following functions may be useful in the writing of your functions.
Ping()
A function for the VSO Central Server to test the status of your system. There is no input. A Data Provider should return one of the following:
- '0' The system is not currently available.
- '1' The system seems to be functional.
- undef You have no idea if the system is available.
The default Ping() function will return undef.
_ValidDate()
Accepts a scalar, and returns 1 if it thinks the string looks like a VSO date, otherwise, it returns 0. The default function tests to see if the scalar is a 14 digit number. You can override this function if you want to make sure that you don't accept requests for February 42nd at 2762 UTC.
_PackageResults()
This function wraps the necessary packaging around a Query result set.
Input Arguments:
- Number Found
A scalar, with the number of records the Data Provider found. This number will not necessarily match the number of records returned, if the number of records exceeded an internal limit. If this number would be prohibitively expensive to calculate, the Data Provider may send undef.
- Records
A reference to an array of VSO records. Please see the VSO website for documentation on the format of VSO records:
- Additional Options
Additional options may be included as a hash after the positional arguments. There is currently only one option recognized:
- debug
Will include a 'debug' element in the VSO response, with the value passed in.
_ThrowError()
Will package an error message to be returned.
Input Arguments:
- Error Message
The error message should be a three digit status code, a space, and then a short message that is human readable.
- Debugging Message
You may also specify an extra message that would not typically be returned to the end user, but may assist in debugging problems down the road. This can be useful when you may generate the same error message multiple ways, or if you want to explain further about why you were throwing the error message.
_PackageData()
_PackageMultipleData()
Combines the results of multiple calls to _PackageData() into one VSO result message.
Other Functions
The following functions are explained for completeness of documentation. There should be no need for a Data Provider to override these functions, but this documentation may be useful to future maintainers of this module.
new()
Creates a new VSO::DataProvider? object.
Query()
Accepts the VSO request, and performs simple sanity checks on the request to search for data. Hands off any significant processing to _Search()
GetData?()
Accepts the VSO request, and performs simple sanity checks on the request to retrieve information. Will check that the client has requested an acceptable data transfer method, and that they have supplied the necessary information keywords. [Note -- it tests that they are defined, but additional tests may be required to ensure that they are valid values].
Hands off any significant processing to _ProcessDataRequest()
NewStubFunction()
Creates a function that will throw an error if it is called. This exists because the original coder was getting tired of redundant code in the module.
_VSOVersionSupported()
Returns the version of the VSO API that is supported by this web service.
_NegotiateReturnMethod()
Given a VSO GetData? request, it will return a hashref containing a subset of the data transfer methods that the Data Provider supports.
The function will return a hashref containing one of the following:
- A single hash element, containing an empty array
The key of the hash element is a mutually agreed upon data transfer method, and the client has supplied all required information for the method.
- A single hash element, containg a non-empty array
The key of the hash element is a mutually agreed upon data transfer method, but the client is missing required information to the method.
- Multiple hash elements
The keys of the hash are data transfer methods that the client may be interested in. The list is generated by comparing the list of generic methods that the client desires, and will expand those that the provider supports. If there is no match between the client request and the provider, will return all transfer methods that the provider supports.
_GenericDataMethods()
Will parse the return value of _SupportedDataMethods() to generate a list of the non-specific transfer methods that the provider sup- ports.
SEE ALSO
For more information about the Virtual Solar Observatory Project, please visit the VSO website:
Example files are available to show some of the functionality that is available in the different
AUTHOR
This module is a collaborative effort by the VSO Team.
Please see the VSO website for current contact information:
COPYRIGHT AND LICENSE
Copyright 2004 by The VSO Team
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
