diff options
Diffstat (limited to 'vendor/voclient/doc/Notes')
| -rw-r--r-- | vendor/voclient/doc/Notes | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/vendor/voclient/doc/Notes b/vendor/voclient/doc/Notes new file mode 100644 index 00000000..0bec7c3e --- /dev/null +++ b/vendor/voclient/doc/Notes @@ -0,0 +1,238 @@ + + VO Client-Side Libraries and Applications + v1.0 + + March 2, 2011 + + +Introduction +------------ + + The VOClient/VO-CLI support project (WBS 1.7) is intended to provide +a user-ready software distribution for both scientists and developers. Part +of the work to be done for this project is simple maintenance work required +to bring the code to a common standard, packaging work needed fior distrib- +ution, etc. Additional work is planned to provide new functionality needed +by higher-level projects built from this code. + + +User Applications +----------------- + + We expect to provide the following set of applications in the initial +distribution: + +* vodata Query and Access DAL services +* vodirectory VO Registry query +* vosesame Sesame Name Resolver + voxmatch VO Crossmatch + +* votinfo Print summary information about a VOTable document + votcopy Copy a VOTable to a different format + votlint VOTable validator + + samp Send a SAMP message + sampexec Listender to execute a host command from SAMP message + sampmon Monitor SAMP messages + +* voclientd VOClient Daemon startup script + + (*) Existing application requiring mantenance work only. + + + These applications are built entirely from the various libraries included +in this package. Each task has a complete unix-like man page to document +it's option and functionality as well as test cases that can be used for +Q&A (TBD). The work required for each application is described generally +below and in documentation included in the source tree. + + + +Client-Side Libraries +--------------------- + + The VOClient package will provide a number of APIs to support developers +building science applications of their own or for use in other environments. +These libraries are implemented in C and provide additional bindings for a +number of VO supported languages. Each interface is fully documented and +higher-level "User's Guide" documentation is planned for each interface. + + + VOApps High-level interface to application functionality. + Tasks are built on these routines to provide the + cmdline user interface, but are encapsulated in an + API to provide this functionality to other environ- + ments easily (as opposed to having that functionality + be re-implemented using the low-level interfaces). + + VOTable A VOTable parser library. The interface provides + both read (lax parsing) and write (strict compliance) + capabilities. Reference is VOTable v1.2. + + VOEvent A VOEvent parser library. The interface provides + both read (lax parsing) and write (strict compliance) + capabilities. Reference is VOTable v2.0. + + VOClient A VO Service interface library. This interface uses + the VOClient Daemon to access a variety of VO web + services (Registry, Sesame, DAL services, etc) which + then communicate to the API to pass information back + to the application. + + SAMP Client-side SAMP interface library. This interface + allows an application to send and receive SAMP + messages but does NOT (at this time) provide a local + Hub implementation. Applications can register their + own functions to be used as callbacks in response to + a message, the API provides only the middle-ware needed + to handle the SAMP protocol. + + + The VOApps library represents new development for the package but is +required to for the VO-IRAF Integration Science Initiative project to +allow multi-threaded queries (there is currently no native threading +interface in the IRAF environment). The high-level interface to the task +functionality also makes it trivial to include and extend these tasks in +other environemts or applications. + + The other libraries are mostly "complete", however they require some +work to bring them to a common code standard and to fit properly into the +new package structure. In particular, the VOClient library contains a +VOTable parser interface that should be replaced with code layered on the +more general VOTable parser library. Likewise, existing VO-CLI application +code is a mix of the VOClient interface and what will become the VOApps +interface. Since much of the code is already written, work will concentrate +on moving that code into the new package structure before beginning new +development or serious refactoring of existing code. + + + + +Documentation +------------- + + End-user documentation will be provided for each application and library +in the following form: + + - Command-line applications will have a unix-like manual page detailing + the options for the task, describing it's behavior and providing + working usage examples. + + - Interface documentation consists of Doxygen-generated manuals + created from the in-line source code tags. This documentation + gives a description of each function, its arguments and return + value. Both on-line and off-line formats will be created. Recent + versions of SWIG that generate the multi-language bindings can be + used to preserve the documentation for target languages. + + - Hand-written high-level Programmer's Guides will be written for each + library interface describing it's expected use within an application + and information needed to use the multi-language interfaces. + + + +Examples and Testing +-------------------- + + Usage examples in application help pages will be written to provide +both documentation and test cases for the task. Static resources (i.e. +catalogs rather than observation logs) will be used when necessary to +help ensure results are reproducible and provide a means of regression +testing. These examples can be captured in a script to provide the test +application. + + For library interfaces, example applications will be written in each +of the target languages that can similarly be used for testing. These +example apps will attempt to cover as much of the interface as possible, +unit tests will be developed according to the (TBD) requirements of the +Product Development WBS. + + + +Maintendance Development +------------------------ + + TBD + + + + + + + +Distribution Directory Structure +-------------------------------- + + The restructured VOClient distribution will provide a distribution +containing both command-line applications and the API libraries to be used by +developers. End-user documentation for apps and libraries is also included. +The distribution will have the following directory structure: + + bin - Directory for application binaries + doc - Top-level documentation, User's Guides for libs, + app man pages, etc + include - Include files needed by VOClient APIs, and for + include files needed to build those APIs (e.g. + from CURL or eXpat) + lib - Public libraries and dependency libs (CURL, etc) + used to build the interfaces + + common - Dependency libs used to build the interfaces. This + allows us to use controlled versions and not rely + on platform capabilities. + + apps - Applications provided by this package. Basically + the existing VO-CLI tools plus new work + libvoapps - High-level API to task functionality + libvoclient - VOClient API + libvotable - VOTable parser API + libsamp - SAMP API + + voclient - VOClient Daemon code + + + + +============================================================================= + +A 1) Hi-Level Requirements +--------------------------- + +VOCLient Distribution + 1.1 The VOClient distribution shall be self-contained (i.e. all + dependent code should be bundled with the distribution), binaries + shall run and be buildable from source on VO-supported platforms. + 1.1 The VOClient distribution shall provide complete documentation for + developers and end-users of both the API and command-line apps. + 1.2 The VOClient distribution shall support as many VO services as is + practical within the alloted resources. + +VOCLient API + 2.1 The VOClient API shall be language neutral: It shall be written in C + and provide bindings for all languages supported by the VO, API + methods only return datatype primitives common to all languages + (integers, strings, etc). + 2.2 Example applications for developers shall be be available for all + supported languages, these applications shall also be used in product + testing. + 2.3 All supported languages shall provide the same set of VO capabilities, + example applications, and test cases. + 2.4 Supported languages shall include Fortran and IRAF/SPP (as hand-coded + interfaces when automated bindings are not possible). + +VO-CLI Applications + 3.1 CLI applications shall provide a common interface across all tasks + where possible (i.e. a '-v' flag mean the same to all apps). + 3.2 CLI applications shall allow result tables to be saved is a format + other than VOTable. + 3.3 CLI applications shall process lists of input when appropriate and + allow simultaneous queries of VO services. + +VOCLient Daemon + 4.1 The VOClient daemon shall trap and return service errors to the API + code and higher-level applications. + 4.2 The VOClient daemon shall support multiple simultaneous clients. + 4.3 The VOClient daemon shall be started automatically by any + application using the VOClient API if it is not already running. + 4.4 The VOClient daemon shall be extensible to new services. + |