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.