1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
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.
|
