Changes between Initial Version and Version 1 of DataProviderInheritable


Ignore:
Timestamp:
07/05/05 13:55:18 (17 years ago)
Author:
joe
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DataProviderInheritable

    v1 v1  
     1= Data Provider Inheritable = 
     2 
     3The following is rendered from the POD (Plain Old Documentation) inside the VSO Data Provider Inheritable. 
     4 
     5The inheritable is written in Perl, and uses [http://soaplite.com/ SOAP::Lite]. 
     6 
     7Please refer to the module itself for the most up-to-date (and most likely, better formatted) documentation, and example code. 
     8 
     9------ 
     10 
     11 
     12== NAME == 
     13 
     14'''Physics::Solar::VSO::DataProvider''' - Inheritable Perl object for Virtual 
     15Solar Observatory Data Providers. 
     16 
     17== SYNOPSIS == 
     18 
     19{{{ 
     20 use VSO::DataProvider; 
     21 @ISA = qw (VSO::DataProvider); 
     22 
     23 sub _ProviderID   { return $id; } 
     24 sub _Search               { ... } 
     25 sub _SupportedDataMethods { ... } 
     26 sub _ProcessDataRequest   { ... } 
     27}}} 
     28 
     29== DESCRIPTION == 
     30 
     31VSO::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. 
     32 
     33For more information about this project, please visit the VSO website: 
     34 
     35   http://www.virtualsolar.org/ 
     36 
     37== USAGE == 
     38 
     39The VSO::DataProvider module contains functions to handle the encoding 
     40and decoding of VSO messages.  VSO::DataProvider will perform some 
     41basic sanity checks on the message, and then call specific functons to 
     42handle the low-level processing, and to actually interact with the data 
     43archive. 
     44 
     45 
     46=== Required Functions === 
     47 
     48 
     49==== _ProviderID() ==== 
     50 
     51   This function should return a string containing this data provider's Provider ID. 
     52 
     53   For information about obtaining a Provider ID, please visit the VSO website: 
     54 
     55   http://www.virtualsolar.org/ 
     56 
     57==== _Search() ==== 
     58   The _Search function handles the main processing for a VSO Query. 
     59    
     60   The input is a hashref containing the search parameters.  The output should be either a VSO error message, or a VSO query response. 
     61    
     62   Two helper functions are provided to handle the encapsulation of the response, _ThrowError() and _PackageResults() 
     63    
     64   Please see the VSO website for an explaination of the formatting of a search request: 
     65    
     66   http://www.virtualsolar.org/ 
     67 
     68==== _SupportedDataMethods() ==== 
     69 
     70  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: 
     71 
     72{{{ 
     73sub _SupportedDataMethods { 
     74  return { 
     75    'TRANSFER_METHOD'  => [ qw( INFO KEYWORD LIST ) ], 
     76    'TRANSFER_METHOD2' => [ qw( INFO KEYWORD LIST ) ], 
     77  }; 
     78} 
     79}}} 
     80 
     81   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: 
     82 
     83   http://www.virtualsolar.org/ 
     84 
     85==== _ProcessDataRequest() ==== 
     86 
     87   The _ProcessDataRequest function handles the main processing for a VSO GetData request. 
     88 
     89   The input is a hashref containing the search parameters.  The output should be either a VSO error message, or a VSO query response. 
     90    
     91   Two helper functions are provided to handle the encapsulation of the response, _ThrowError() and _PackageData() 
     92    
     93   Please see the VSO website for an explaination of the formatting of a GetData request: 
     94    
     95   http://www.virtualsolar.org/ 
     96 
     97=== Useful Functions === 
     98 
     99   The following functions may be useful in the writing of your functions. 
     100 
     101==== Ping() ==== 
     102 
     103   A function for the VSO Central Server to test the status of your 
     104   system.  There is no input.  A Data Provider should return one of 
     105   the following: 
     106 
     107   * '0' 
     108     The system is not currently available. 
     109 
     110   * '1' 
     111     The system seems to be functional. 
     112 
     113   * undef 
     114     You have no idea if the system is available. 
     115 
     116   The default Ping() function will return undef. 
     117 
     118==== _ValidDate() ==== 
     119 
     120   Accepts a scalar, and returns 1 if it thinks the string looks like 
     121   a VSO date, otherwise, it returns 0.  The default function tests to 
     122   see if the scalar is a 14 digit number.  You can override this 
     123   function if you want to make sure that you don't accept requests 
     124   for February 42nd at 2762 UTC. 
     125 
     126==== _PackageResults() ==== 
     127 
     128   This function wraps the necessary packaging around a Query result 
     129   set. 
     130 
     131   Input Arguments: 
     132 
     133   * Number Found 
     134 
     135      A scalar, with the number of records the Data Provider found. 
     136      This number will not necessarily match the number of records 
     137      returned, if the number of records exceeded an internal limit. 
     138      If this number would be prohibitively expensive to calculate, 
     139      the Data Provider may send undef. 
     140 
     141   * Records 
     142 
     143      A reference to an array of VSO records.  Please see the VSO 
     144      website for documentation on the format of VSO records: 
     145 
     146         http://www.virtualsolar.org/ 
     147 
     148   * Additional Options 
     149 
     150      Additional options may be included as a hash after the positional arguments.  There is currently only one option recognized: 
     151 
     152       * debug 
     153 
     154          Will include a 'debug' element in the VSO response, with 
     155          the value passed in. 
     156 
     157==== _ThrowError() ==== 
     158 
     159   Will package an error message to be returned. 
     160 
     161   Input Arguments: 
     162 
     163   * Error Message 
     164      The error message should be a three digit status code, a space, 
     165      and then a short message that is human readable. 
     166 
     167   * Debugging Message 
     168      You may also specify an extra message that would not typically 
     169      be returned to the end user, but may assist in debugging problems down the road.  This can be useful when you may generate 
     170      the same error message multiple ways, or if you want to explain 
     171      further about why you were throwing the error message. 
     172 
     173==== _PackageData() ==== 
     174==== _PackageMultipleData() ==== 
     175 
     176   Combines the results of multiple calls to _PackageData() into one 
     177   VSO result message. 
     178 
     179=== Other Functions === 
     180 
     181   The following functions are explained for completeness of documentation.  There should be no need for a Data Provider to override these 
     182   functions, but this documentation may be useful to future maintainers 
     183   of this module. 
     184 
     185==== new() ==== 
     186 
     187   Creates a new VSO::DataProvider object. 
     188 
     189==== Query() ==== 
     190 
     191   Accepts the VSO request, and performs simple sanity checks on the 
     192   request to search for data.  Hands off any significant processing 
     193   to _Search() 
     194 
     195==== GetData() ==== 
     196 
     197   Accepts the VSO request, and performs simple sanity checks on the 
     198   request to retrieve information.  Will check that the client has 
     199   requested an acceptable data transfer method, and that they have 
     200   supplied the necessary information keywords.  [Note -- it tests 
     201   that they are defined, but additional tests may be required to 
     202   ensure that they are valid values]. 
     203 
     204   Hands off any significant processing to _ProcessDataRequest() 
     205 
     206==== __NewStubFunction() ==== 
     207 
     208   Creates a function that will throw an error if it is called.  This 
     209   exists because the original coder was getting tired of redundant 
     210   code in the module. 
     211 
     212==== _VSOVersionSupported() ==== 
     213 
     214   Returns the version of the VSO API that is supported by this web 
     215   service. 
     216 
     217==== _NegotiateReturnMethod() ==== 
     218 
     219   Given a VSO GetData request, it will return a hashref containing a 
     220   subset of the data transfer methods that the Data Provider supports. 
     221    
     222   The function will return a hashref containing one of the following: 
     223    
     224   * A single hash element, containing an empty array 
     225    
     226      The key of the hash element is a mutually agreed upon data 
     227      transfer method, and the client has supplied all required 
     228      information for the method. 
     229    
     230   * A single hash element, containg a non-empty array 
     231    
     232      The key of the hash element is a mutually agreed upon data 
     233      transfer method, but the client is missing required information 
     234      to the method. 
     235    
     236   * Multiple hash elements 
     237    
     238      The keys of the hash are data transfer methods that the client 
     239      may be interested in.  The list is generated by comparing the 
     240      list of generic methods that the client desires, and will 
     241      expand those that the provider supports.  If there is no match 
     242      between the client request and the provider, will return all 
     243      transfer methods that the provider supports. 
     244 
     245==== _GenericDataMethods() ==== 
     246 
     247   Will parse the return value of _SupportedDataMethods() to generate 
     248   a list of the non-specific transfer methods that the provider sup- 
     249   ports. 
     250 
     251== SEE ALSO == 
     252 
     253For more information about the Virtual Solar Observatory Project, 
     254please visit the VSO website: 
     255 
     256http://www.virtualsolar.org/ 
     257 
     258Example files are available to show some of the functionality that is 
     259available in the different 
     260 
     261== AUTHOR == 
     262 
     263This module is a collaborative effort by the VSO Team. 
     264 
     265Please see the VSO website for current contact information: 
     266 
     267http://www.virtualsolar.org/ 
     268 
     269== COPYRIGHT AND LICENSE == 
     270 
     271Copyright 2004 by The VSO Team 
     272 
     273This library is free software; you can redistribute it and/or modify it 
     274under the same terms as Perl itself.