Changes between Initial Version and Version 1 of DataProviderInheritable

Timestamp:

07/05/05 13:55:18 (19 years ago)

Author:

joe

Comment:

--

DataProviderInheritable

@@ +1 @@
+= 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 [http://soaplite.com/ 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:
+
+   http://www.virtualsolar.org/
+
+== 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:
+
+   http://www.virtualsolar.org/
+
+==== _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:
+   
+   http://www.virtualsolar.org/
+
+==== _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:
+
+   http://www.virtualsolar.org/
+
+==== _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:
+   
+   http://www.virtualsolar.org/
+
+=== 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:
+
+         http://www.virtualsolar.org/
+
+   * 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:
+
+http://www.virtualsolar.org/
+
+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:
+
+http://www.virtualsolar.org/
+
+== 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.