Revision : 1.0 Date : 04/07/2005 JRA4 COMMON SOFTWARE SOFTWARE USER REQUIREMENTS Gérard Zins (Gerard.Zins@obs.ujf-grenoble.fr ) LAOG/JMMC Author : Gérard Zins Institute : LOAG/JMMC Approved by : Team Leaders Institute : Released by : Gilles Duvert Institute : LOAG/JMMC Signature : Date : 16/06/2005 Signature : Date : 04/07/2005 Signature : Date : 04/07/2005
CHANGE RECORD REVISION 0.1 0.2 0.3 0.4 0.5 0.6 0.7 1.0 DATE AUTHOR SECTIONS/PAGES AFFECTED REMARKS 10/01/2005 J. Bérezné All First draft 05/04/2005 G. Zins All 04/05/2005 G. Zins Incorporated comments from Laurence and Gilles. Completed sections 3.1.6 and 3.1.8; added sections 3.1.7.5 and 3.1.7.6. 12/05/2004 G. Zins Incorporated comments from Sylvain and Guillaume. 01/06/2005 G. Zins 1.2, 1.3, 2.5 and 3.1.6 Incorporated comments from Isabelle and Rainer. 16/06/05 G. Zins 1.2, 2.1, 2.2, 3.1.1, 3.1.3, 3.1.4 and 3.1.5 Incorporated comments from John, David and Chris. 16/06/2005 G. Zins 3.1.4.1 and 3.1.5.4 Incorporated further comments from John. 04/07/2005 G. Zins Released document Revision: 1.0 Page 2/13
TABLE OF CONTENTS 1 Introduction 4 1.1 Purpose 4 1.2 Reference Documents 4 1.3 Abbreviations and Acronyms 4 1.4 Document Conventions 4 2 General Description 5 2.1 Software Perspective 5 2.2 User Classes and Characteristics 5 2.3 Operating Environment 5 2.4 General Constraints, Assumptions, Dependencies, Guidelines 5 2.5 Design and Implementation Constraints 5 2.6 User Documentation 5 2.7 Software License 5 3 Specific Requirements 6 3.1 Capability Requirements 6 3.1.1 Logging System 6 3.1.2 Error System 7 3.1.3 Communication System 8 3.1.4 Data Management System 8 3.1.5 Database System 9 3.1.6 Graphical toolkit 9 3.1.7 Development tools 10 3.1.8 Installation tool 11 3.2 Constraint requirements 11 4 User Interface Requirements 12 4.1 GUI 12 4.2 CLI 12 4.3 API 12 4.4 Diagnostics 12 5 Operational Scenarios 13 Revision: 1.0 Page 3/13
1 Introduction 1.1 Purpose The scope of this document is to describe the user (or programmer) requirements for the common software package developed for the JRA4 project. This software package provides a set of components for common services (e.g. inter-process communication or logging) to simplify the development of other JRA4 applications and facilitate their maintaining. 1.2 Reference Documents [1] JRA4-TRE-2000-0001, Revision 2.0, Software Preliminary ConceptDescription [2] JRA4-PLA-2000-0001, Revision 1.0, Software Management Plan [3] JRA4-PLA-2200-0001, Revision 1.0, Common Software - Software Management Plan [4] JRA4-MOD-2300-0001, In prep., Model Fitting - [5] JRA4-MOD-2410-0001, In prep., Astrometry - Geneva University - Software User Requirements [6] JRA4-MOD-2410-0001, In prep., Astrometry - Leiden University - Software User Requirements [7] JRA4-MOD-2500-0001, In prep., Image Reconstruction - [8] JRA4-PRO-2000-0001, In prep., Programming Standards [9] A Data Exchange Standard for Optical (Visible/IR) Interferometry, Thomas A. Pauls, John S. Young, William D. Cotton, John D. Monnier, Proc. SPIE 5491, p.1231 (2004) 1.3 Abbreviations and Acronyms API Application Programming Interface CLI Command Line Interface EII European Interferometry Initiative FITS Flexible Image Transport System GPL GNU General Public License GUI Graphical User Interface IPC Inter Process Communication JRA4 Join Research Activity 4 NA Not Applicable OI FITS Optical Interferometry FITS UML Unified Modeling Language UR User Requirements 1.4 Document Conventions The following styles are used: Teletype in the text : names of programs, files, directories, etc. in the examples: user typing. Italic in the text : for parts that have to be substituted with the real content before typing. <...> in the examples: for parts that have to be substituted with the real content before typing. [...] in the examples: for optional parts. Bold and italic are also used to highlight keywords. Revision: 1.0 Page 4/13
2 General Description 2.1 Software Perspective The Common Software package is intended to simplify development and maintenance of the JRA4 application software, by providing: a rich set of components that perform common services such as inter-process communication, logging, across a wide range of OS platforms. distributed services such as logging or database servers tools to support the developer during software implementation and test. 2.2 User Classes and Characteristics The Common Software will be used by the software developers during implementation and test phases for the JRA4 software development. 2.3 Operating Environment The Common Software will be developed to run across a wide range of Unix-like OS. 2.4 General Constraints, Assumptions, Dependencies, Guidelines The Common Software should provide components which encapsulate system calls to improve portability across a wide range of OS platforms. 2.5 Design and Implementation Constraints The design and implementation constraints identified for the development of this software package follow underneath: the package has to follow the programming standards as defined in [8], a state-of-art UML design of the package is recommended, provided services being callable from C, C++ and java programs, use of existing libraries is recommended, the used system calls must be compliant with POSIX standards to make porting applications between operating systems simpler. 2.6 User Documentation According to the Software Management Plan [2], a programmer manual has to be delivered with the software package. It should describe the SW installation and give all necessary information to use each service and provided tools. It should contain examples to illustrate descriptions. 2.7 Software License In order to avoid issues related with Software Copyrights under the Sixth Framework Programme 1 third party proprietary software use is not allowed for the products of JRA4 WP2. JRA4 WP2 software and documentation author's rights are by default protected by copyright. To insure proper dissemination of the software and accordingly grant sufficient access rights to the end users, the software shall be released under a public license such as the GPL. 1 See http://www.ipr-helpdesk.org Revision: 1.0 Page 5/13
3 Specific Requirements 3.1 Capability Requirements 3.1.1 Logging System The purpose of the logging system is to provide developers with facilities to log information and to retrieve it later. 3.1.1.1 Output destination Description: The log messages are: written to the console (standard output), stored into ASCII file. Logging system must take care of the multiple accesses to the log file by several processes. Format of the log file must be viewable and understandable using simple text editor. Log file size is supervised, and should not require human maintenance. 3.1.1.2 Message origin Description: Origin of the message is also logged. This includes at least the following information: process name which emits the log message, source code (file name and line number) from where the log message has been emitted, date and time of when the message has been emitted. The display of the origin information for log messages written to the console should be optional; i.e. could be switched on or off. 3.1.1.3 Filtering on message type Description: Different types of log messages are supported: error : for errors and abnormal events warning : for warning messages info : for major events test : for test activities purpose debug : for debugging information trace : for trace These types are used to filter out messages when they are logged, and then controls the verbosity level; i.e. number of log messages printed out on console and stored into log file. The control of message filtering is done at process level. 3.1.1.4 Filtering on source code Description: The messages can be also filtered on source code; either on source file name or on software module name from where the log message has been emitted. Priority: Medium Revision: 1.0 Page 6/13
3.1.1.5 Display tool Description: Messages stored in a log file can be displayed using a tool which provides more advanced features than a simple text editor, such message filtering or search facility. Priority: Medium 3.1.2 Error System The purpose of the error system is to provide facilities to handle errors generated by applications. Its role is to report to the user the software unwanted (but predictable) behaviors. 3.1.2.1 Error identification Description: Each generated error must be identifiable; i.e. associated to an identifier which must be unique. This identifier can be used to know which error occurred. 3.1.2.2 Error context Description: Error context is stored with the error message itself. This includes at least the following information: process name which generates the error, source code (file name and line number) from where the error has been generated, date and time of when the error has been generated. 3.1.2.3 Error enriching Description: The error can be enriched i.e. when an error condition is encountered, in some software layer, an error is generated and reported to the upper level which can add information having a meaning for this software level. 3.1.2.4 Error logging Description: Error can be sent to logging system when it is reported to user. 3.1.2.5 Maintainable error message Description: By experience the error messages have to be very often updated to make them more understandable by end-user. So, the message associated to an error should be easily modifiable, preferably without re-compilation of the source code, to facilitate maintenance. Priority: Medium Revision: 1.0 Page 7/13
3.1.3 Communication System The purpose of the communication system is to provide a similar access to inter-process communication facilities, independently of the location of the communicating processes. 3.1.3.1 Network communication Description: Communication shall be possible between processes which are running either on the same host or on different hosts connected to the network. 3.1.3.2 Synchronous and asynchronous exchanges Description: Communication system provides synchronous exchange (process sends message and waits for reply), or asynchronous exchange (process sends message and is informed by an event when reply is received). In both cases, a timeout can be specified giving the maximum waiting time. 3.1.4 Data Management System The purpose of the data management system is to provide facilities to manipulate data or parameter files. 3.1.4.1 FITS File interface Description: Data Management System provides facilities to: read and write FITS data file, including the header and data, for the following standard FITS formats: Basic FITS, the image extension, and the binary table extension. check FITS keyword name and value (format and range). This should be based on a commonly used public library, such as cfitsio. 3.1.4.2 OI-FITS File interface Description: Data Management System provides facilities to read and write data file in OI FITS format (see document [9]). It has to be robust against OI FITS format changes by providing adapted access to the data itself. 3.1.4.3 Parameter File interface Description: Data Management System provides facilities for reading and writing parameter files, where parameter is a pair <parameter-name> <value>. Parameter name and value (type, format and range) has to be checked. Parameter file is an ASCII file, and its format has to be as simple as possible allowing user to edit it easily. Revision: 1.0 Page 8/13
Advanced features such as parameter file inclusion or keyword substitution should be also possible. 3.1.5 Database System The purpose of the Database System is to provide real-time data store/access capabilities to share data among processes. It could be thought of as a shared memory pool for multiple clients 3.1.5.1 Creation and deletion of status points Description: The Database System provides facilities to: create and remove status points which can be viewed by other processes, check for existence of status points. 3.1.5.2 Reading and writing status points Description: The Database System provides facilities to write/update and read status points. The write access can be restricted to the status point owner. 3.1.5.3 Monitoring status points Description: The Database System provides facilities to monitor status point changes; i.e. a process is informed whenever the status value changes. 3.1.5.4 Data types/formats Description: The types of data stored in status point are either string, integer, double or boolean, which can be stored into two data structures: scalar or vector. 3.1.6 Graphical toolkit The purpose of the Graphical Toolkit is to provide facilities to implement GUI which interacts with a local application or a web service. 3.1.6.1 Widgets Description: Graphical Toolkit provides a library of components known as widgets (visual objects on the screen that can be manipulated with the mouse and keyboard). It provides fundamental widgets such as label, separator, text input, numerical input, push-button, toggle-button, scrollbar, slider or progress bar, and advanced widgets such as table, menu, container or 2D graph. This should be (or at least based on) an existing standard graphical public library. Revision: 1.0 Page 9/13
3.1.6.2 Images Description: Graphical Toolkit includes widgets for imaging and data visualization which provide classical support for imaging manipulation such as zoom, rotation, orientation, panning or cut. This should be (or at least based on) an existing standard graphical public library. 3.1.7 Development tools The purpose of the development tools is to provide a set of utilities to help developers during the software implementation and test. 3.1.7.1 Templates Description: Templates for directory structure and files forming a software module are provided. 3.1.7.2 Makefile Description: The development tools include facilities, based on Makefile, to compile source files, to generate documentation, to install software, etc, and provide homogenous way to do this independently from the programming language. Usage of tools like GNU Autotools is recommended to enhance portability. 3.1.7.3 Test Description: The development tools include utility to execute tests and check test results. This utility could be used for all tests performed during software cycle life; from unitary tests to validation tests. This utility should be (or at least based on) existing public test tools. 3.1.7.4 Documentation Description: Software documentation is part of the software itself; i.e. in the source code files. The development tools include utility to extract documentation from source code and produce manual in html and pdf format. This utility should be an existing public tool. 3.1.7.5 Configuration Control Management Description: The development tools include utility for software version control which is essential for software development. Revision: 1.0 Page 10/13
This utility should be an existing public tool. 3.1.7.6 Bug Tracking Description: Because the software change is often driven by problems report, a bug tracking utility should be integrated with the version control system. Verifiability: Easily testable 3.1.8 Installation tool Description: The Installation tool provides utilities which can be used to build, install, query, verify, update, and erase individual software packages. A software package consists of a set of software modules. 3.2 Constraint requirements This package should use and/or be based on, as much as possible, existing public libraries/tools. Revision: 1.0 Page 11/13
4 User Interface Requirements 4.1 GUI Not applicable. 4.2 CLI Not applicable. 4.3 API Not applicable. 4.4 Diagnostics Not applicable. Revision: 1.0 Page 12/13
5 Operational Scenarios Not applicable. Revision: 1.0 Page 13/13